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:adminoraegis:operatorKeycloak 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:
| Field | Example | Notes |
|---|---|---|
name | python-coder | Lowercase, alphanumeric, hyphens. Must be unique. |
version | 1.0.0 | Semantic version string. |
runtime.language | python | Or use runtime.image for a custom Docker image. |
runtime.version | 3.11 | Required 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: 1See 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:
- Validates the manifest against the domain schema
- Resolves the runtime image (standard or custom)
- Registers the agent in the agent registry
- 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
- Navigate to the agent detail page (click the agent name in the list)
- Click Edit (visible only if you have mutation permissions)
- Modify fields on the Form tab or the YAML tab
- 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
- Navigate to the agent detail page
- Click the Delete button
- 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:
- Enter the task input (plain text or JSON)
- Click Run
- 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, ornone(no network)filesystem.read/filesystem.write— permitted container pathsresources— CPU, memory, disk, and timeout limits
Execution
mode—iterative(the default, up tomax_iterationstries) orone-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:
- Navigate to the agent detail page
- Click the Versions tab
- The list shows all deployed versions with their timestamps
- 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.