Aegis Orchestrator
Agents

Creating Agents via the UI

Step-by-step guide to creating, editing, and deleting agents using the Zaru web interface.

Creating Agents via the UI

The Zaru web interface provides a structured UI for creating, editing, and managing agents. This complements the CLI and conversational (Workflow mode) creation paths with a visual, form-driven experience.

Two surfaces are available:

  • Admin console (/admin/agents) — operators manage all agents across tenants
  • Dashboard (/dashboard/agents) — users manage their own agents

Both surfaces share the same form and editing components. The instructions below apply to either surface.


Prerequisites

  • A Zaru account with an active session
  • For admin access: an aegis:admin or aegis:operator Keycloak role

Creating an Agent

Step 1: Navigate to the Agent List

  • Admin: Click Agents in the admin sidebar
  • Dashboard: Click Agents in the dashboard navigation

Step 2: Click "New Agent"

The create button appears in the toolbar above the agent list. On the admin surface, this button is only visible to users with admin or operator roles.

Step 3: Choose an Editing Mode

The create page offers two editing modes, toggled via a switch at the top of the form:

Structured form (default) — fill in fields with validation feedback:

  • Metadata (name, version, description, labels, tags)
  • Runtime configuration (language + version or custom Docker image)
  • Task definition (instruction and prompt template)
  • Security policy (network mode, filesystem paths, resource limits)
  • Execution strategy (one-shot vs. iterative, max iterations, validators)
  • Tool bindings
  • Environment variables

YAML editor — write or paste the full agent manifest in YAML:

  • Syntax highlighting and line numbers via CodeMirror 6
  • Parse errors shown inline as you type
  • Toggle back to structured form at any time; the form fields populate from the YAML

You can switch between modes freely. When you switch from the form to YAML after changing the form, the YAML text is rewritten from the form's fields; if you have not changed the form since the text was last set, the YAML text stays as it was. When switching from YAML to form, the YAML is parsed and loaded into form fields.

Step 4: Fill in the Manifest

At minimum, you need:

FieldExampleNotes
namepython-coderLowercase, alphanumeric, hyphens. Must be unique.
version1.0.0Semantic version string.
runtime.languagepythonOr use runtime.image for a custom Docker image.
runtime.version3.11Required when using language.

A minimal agent manifest in YAML mode:

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: python-coder
  version: "1.0.0"
  description: "Writes Python solutions to programming tasks."
spec:
  runtime:
    language: python
    version: "3.11"
  task:
    instruction: |
      Write a Python solution to the given problem.
      Save the solution to /workspace/solution.py.
  tools:
    - fs.write
  volumes:
    - name: workspace
      storage_class: ephemeral
      mount_path: /workspace
      access_mode: read-write
      ttl_hours: 1

See the Agent Manifest Reference for the complete field specification.

The form's Recommended schedule section (Cron, Time zone, Jitter (seconds)) writes spec.default_schedule: "A recommendation only: it is offered when someone makes a schedule for this agent and creates nothing by itself." See Schedules. A manifest carrying the old spec.schedule is refused by the YAML mode's validation, and one loaded with it opens with that key left out and a line saying so.

Step 5: Submit

Click Deploy Agent, then choose the version in the Save Changes dialog. The dialog's current version is the manifest's metadata.version: from the YAML text while the YAML tab is the active tab, else from the form. The manifest is then sent to the orchestrator, which:

  1. Validates the manifest against the domain schema
  2. Resolves the runtime image (standard or custom)
  3. Registers the agent in the agent registry
  4. Returns success or detailed validation errors

On success, you are redirected to the agent detail page. On failure, validation errors are displayed inline.


Editing an Agent

  1. Navigate to the agent detail page (click the agent name in the list)
  2. Click Edit (visible only if you have mutation permissions)
  3. Modify fields on the Form tab or the YAML tab
  4. Click Update Agent, then choose the version in the Save Changes dialog: a patch, minor or major bump of the current version, or Force overwrite to keep the current version and overwrite its entry

The YAML tab shows the manifest as the orchestrator stores it, including fields the form does not model. It is rewritten from the form's fields only after you change something on the Form tab, so switching tabs without editing the form leaves the text as it was.

The orchestrator stores the parsed manifest and returns its own serialisation of it, so comments and formatting in a manifest are not kept.

The save sends POST /v1/agents with the version you chose. A new version creates a new entry in the version history; Force overwrite adds force=true and overwrites the existing agent with the same name and version, updating that version's snapshot.


Deleting an Agent

  1. Navigate to the agent detail page
  2. Click the Delete button
  3. Confirm in the dialog

Deletion removes the agent from the registry. Running executions are not affected, but no new executions can be started for the deleted agent.

On the admin surface, admin and operator roles can delete any agent. On the dashboard, users can only delete agents they created.


Running an Agent

From the agent detail page or the agent list, click Execute to open the execution dialog:

  1. Enter the task input (plain text or JSON)
  2. Click Run
  3. You are redirected to the execution detail view

Running Agents from the Context Panel

In Agentic, Workflow, and Operator conversation modes, the Context Panel (expand it with the sidebar icon in the top-right corner of the chat) includes an Agents tab listing all available agents. From there you have two options:

  • Execute — opens an inline parameter form directly in the panel, submits the agent, and shows the result without leaving the chat.
  • Send to Chat — injects a structured prompt describing the agent into the chat input, letting Zaru guide you through configuration, explain the agent's capabilities, or help you craft the right input before running it.

Key Manifest Fields

Runtime

Two mutually exclusive modes:

  • StandardRuntime: language + version — the orchestrator resolves the official Docker image
  • CustomRuntime: image — a fully-qualified Docker image reference (e.g., ghcr.io/org/agent:v1.0)

Task

  • instruction — high-level guidance for the agent (what it should accomplish)
  • prompt_template — Handlebars template for constructing LLM prompts; supports {{instruction}}, {{input}}, {{previous_error}}, {{iteration_number}}

Security

Security is deny-by-default. You must explicitly declare:

  • network.mode — allow (use allowlist), deny, or none (no network)
  • filesystem.read / filesystem.write — permitted container paths
  • resources — CPU, memory, disk, and timeout limits

Execution

  • mode — iterative (the default, up to max_iterations tries) or one-shot (one try)
  • max_iterations — maximum refinement loops (1-20, default 5)
  • validation — ordered list of validators (exit code, JSON schema, semantic judge)

See the Agent Manifest Reference for the full specification.


Version History

Every time you deploy an agent, the previous version is preserved in the version history. This gives you a complete audit trail of how an agent has evolved over time.

To view past versions:

  1. Navigate to the agent detail page
  2. Click the Versions tab
  3. The list shows all deployed versions with their timestamps
  4. Click any version to open a read-only manifest viewer showing that version's configuration

Redeploying the same version (via force=true) updates the snapshot for that version entry. Deploying with a new version string creates a new entry in the version history.

On this page