MCP Tool Reference
Complete input and output schemas for all AEGIS MCP tools — built-in orchestrator tools and the Zaru-only zaru.init, zaru.mode, zaru.docs, zaru.memory.get, and zaru.memory.set tools — with availability by context and Zaru conversation mode.
This page is the authoritative schema reference for all AEGIS MCP tools. For the skip_judge policy and inner-loop judge optimization, see Built-in Tools. For usage patterns and examples, see Management Tools.
This page lists the AEGIS orchestrator's built-in tools and five Zaru client tools (zaru.init, zaru.mode, zaru.docs, zaru.memory.get, zaru.memory.set); zaru.chat, zaru.connection.needed, zaru.operator.escalate and zaru.operator.release are on MCP Tools. Which tools a caller is offered depends on its security context and, in Zaru, its mode.
Tool Access Tiers
AEGIS tools are divided into three access tiers. The tier determines which callers may invoke a tool.
User tools — available to all agents and Zaru users:
fs.read, fs.write, fs.list, fs.create_dir, fs.delete, fs.edit,
fs.multi_edit, fs.grep, fs.glob, web.search, web.fetch, cmd.run,
aegis.agent.list, aegis.agent.export, aegis.agent.generate, aegis.agent.logs,
aegis.agent.search, aegis.agent.wait, aegis.workflow.list, aegis.workflow.validate,
aegis.workflow.export, aegis.workflow.run, aegis.workflow.generate, aegis.workflow.logs,
aegis.workflow.wait, aegis.workflow.cancel, aegis.workflow.signal,
aegis.workflow.executions.list, aegis.workflow.executions.get, aegis.workflow.status,
aegis.workflow.search, aegis.task.execute, aegis.task.status, aegis.task.list,
aegis.task.cancel, aegis.task.logs, aegis.task.wait, aegis.execute.intent,
aegis.execute.status, aegis.execution.file, aegis.execute.wait, aegis.image.generate, aegis.goal.create, aegis.goal.evaluate, aegis.goal.status, aegis.goal.cancel, aegis.tools.list, aegis.tools.search,
aegis.schema.get, aegis.schema.validate, aegis.runtime.list,
aegis.file.list, aegis.file.read, aegis.file.write, aegis.file.delete, aegis.file.mkdir,
aegis.volume.create, aegis.volume.list, aegis.volume.delete, aegis.volume.quota,
aegis.git.clone, aegis.git.list, aegis.git.status, aegis.git.refresh,
aegis.git.delete, aegis.git.commit, aegis.git.push, aegis.git.diff, aegis.git.land (answered only for a workflow's own landing step),
aegis.script.save, aegis.script.list, aegis.script.get, aegis.script.update,
aegis.script.delete,
aegis.schedule.create, aegis.schedule.list, aegis.schedule.get, aegis.schedule.update,
aegis.schedule.pause, aegis.schedule.resume, aegis.schedule.run_now, aegis.schedule.delete, aegis.schedule.runs,
mail.list, mail.read, mail.attachment, mail.label, mail.draft, mail.send, mail.reply,
mail.forward, mail.archive, mail.delete,
zaru.init, zaru.mode, zaru.docs, zaru.memory.get, zaru.memory.set, zaru.schedule,
zaru.conversations.list, zaru.conversations.read, zaru.conversations.search
A schedule tool acts only for a person: a service account, or an operator acting for no person, is refused. A mail tool acts only on a mailbox connection of the caller's own; see Mail Tools.
A call refused because the caller has not connected the tool's family, or because the profile chosen does not admit the tool, carries error.needs {"family", "page"} beside code and message, naming the Zaru Web page that resolves it. A tool the chosen profile does not admit is answered 403 TOOL_NOT_IN_PROFILE: "This tool is not in the profile chosen for this conversation." (Refusals and Errors).
Volume, file, git, and script tools are available to every tier — Free, Pro, Business, and Enterprise. The backend enforces per-tier storage, bandwidth, and count quotas; the tool-availability gate itself is uniform across tiers.
System tools — only available to agents with security_context: aegis-system-agent-runtime
registered by platform operators:
aegis.agent.create, aegis.agent.update, aegis.workflow.create, aegis.workflow.update,
aegis.workflow.promote, aegis.workflow.demote, aegis.attachment.read
Operator-only tools — only available via operator SEAL sessions:
aegis.agent.delete, aegis.workflow.delete, aegis.workflow.remove, aegis.task.remove,
aegis.system.info, aegis.system.config
Through Zaru's MCP server, a connection reaches an operator SEAL session only while its API key holds an operator escalation.
Tool Availability by Context
AEGIS tools are available across three distinct execution contexts. The tool set exposed to a caller varies by context.
| Context | Tool groups available | Notes |
|---|---|---|
| Zaru Chat — chat mode | zaru.* (init, mode, docs, memory.get, memory.set) only | Mode switching, docs search, memory; no orchestrator tools |
| Zaru Chat — agentic mode | zaru.* + agent/task management subset | See mode table below |
| Zaru Chat — execute mode | zaru.* + execute pipeline tools | See mode table below |
| Zaru Chat — workflow mode | zaru.* + workflow/agent design subset | See mode table below; starts a workflow with aegis.workflow.run |
| Zaru Chat — operator mode | All tools | No filtering applied; only under an operator escalation |
| AEGIS agent inner loop | Every built-in tool | Subject to agent spec.tools allowlist and SecurityContext |
| External SEAL caller | Every built-in tool | Filtered by SecurityContext only; no mode concept |
See Tool Routing Architecture for the full routing pipeline.
Zaru Conversation Mode Tool Sets
The tool sets below are enforced by the Zaru client — not the orchestrator.
Outside of Zaru, inside agent inner loops and via direct SEAL calls, all
built-in tools are available subject to SecurityContext and the agent's
spec.tools allowlist.
Chat Mode
Only zaru.init, zaru.mode, zaru.docs, zaru.connection.needed, zaru.memory.get, zaru.memory.set, zaru.schedule and the three zaru.conversations.* tools are exposed. The model cannot invoke any orchestrator tools directly from chat mode.
Agentic Mode
zaru.initzaru.modezaru.docszaru.memory.getzaru.memory.setzaru.schedulezaru.conversations.listzaru.conversations.readzaru.conversations.searchaegis.agent.generateaegis.agent.waitaegis.agent.listaegis.agent.searchaegis.agent.logsaegis.workflow.searchaegis.workflow.runaegis.git.listaegis.workflow.waitaegis.schedule.listaegis.schedule.getaegis.schedule.pauseaegis.schedule.resumeaegis.schedule.deleteaegis.schedule.runsaegis.task.executeaegis.task.waitaegis.task.listaegis.task.logsaegis.task.cancelaegis.execution.fileaegis.tools.listaegis.tools.searchaegis.image.generateaegis.goal.cancel
Execute Mode
zaru.initzaru.modezaru.docszaru.memory.getzaru.memory.setzaru.schedulezaru.conversations.listzaru.conversations.readzaru.conversations.searchaegis.execute.intentaegis.execute.statusaegis.execute.waitaegis.execution.fileaegis.image.generateaegis.goal.cancel
Architect Mode
zaru.initzaru.modezaru.docszaru.memory.getzaru.memory.setzaru.schedulezaru.conversations.listzaru.conversations.readzaru.conversations.searchaegis.workflow.generateaegis.workflow.listaegis.workflow.logsaegis.workflow.runaegis.git.listaegis.workflow.createaegis.workflow.updateaegis.agent.generateaegis.agent.waitaegis.agent.listaegis.agent.logsaegis.schema.getaegis.schema.validateaegis.task.executeaegis.task.waitaegis.execution.fileaegis.workflow.waitaegis.schedule.listaegis.schedule.getaegis.schedule.pauseaegis.schedule.resumeaegis.schedule.deleteaegis.schedule.runsaegis.goal.cancel
Architect mode, like agentic mode, offers aegis.workflow.run. A run started from either carries the conversation's chosen connections as its contexts, or its chosen profile as profile, written by Zaru Web whatever the model wrote there.
Neither agentic nor architect mode lists aegis.schedule.create or aegis.schedule.update: the model proposes a schedule with zaru.schedule, and the person makes it.
Operator Mode
All tools are available — no filtering is applied. Through Zaru's MCP server, operator mode is available only under an operator escalation.
Quick-Reference Table
Zaru mode abbreviations: C = chat, Ag = agentic, Ex = execute, Ar = architect, Op = operator. Operator always has full access; only additional modes are listed per tool.
| Tool | Group | skip_judge | Required params | Zaru modes |
|---|---|---|---|---|
cmd.run | dispatch | false | command | Op |
fs.read | fs | true | path | Op |
fs.write | fs | false | path, content | Op |
fs.list | fs | true | path | Op |
fs.create_dir | fs | false | path | Op |
fs.delete | fs | false | path | Op |
fs.edit | fs | false | path, target_content, replacement_content | Op |
fs.multi_edit | fs | false | path, edits | Op |
fs.grep | fs | true | pattern, path | Op |
fs.glob | fs | true | pattern, path | Op |
web.search | web | true | query | Op |
web.fetch | web | true | url | Op |
aegis.schema.get | schema | true | key | Ar, Op |
aegis.schema.validate | schema | true | kind, manifest_yaml | Ar, Op |
aegis.agent.create | agent | true | manifest_yaml | Op |
aegis.agent.list | agent | true | — | Ag, Ar, Op |
aegis.agent.update | agent | true | manifest_yaml | Op |
aegis.agent.export | agent | true | name | Op |
aegis.agent.delete | agent | true | agent_id | Op |
aegis.agent.generate | agent | false | input | Ag, Ar, Op |
aegis.agent.logs | agent | true | agent_id | Ag, Ar, Op |
aegis.agent.search | agent | true | query | Ag, Op |
aegis.agent.wait | agent | true | execution_id | Ag, Ar, Op |
aegis.workflow.create | workflow | true | manifest_yaml | Ar, Op |
aegis.workflow.list | workflow | true | — | Ar, Op |
aegis.workflow.validate | workflow | true | manifest_yaml | Op |
aegis.workflow.update | workflow | true | manifest_yaml | Ar, Op |
aegis.workflow.export | workflow | true | name | Op |
aegis.workflow.delete | workflow | false | name | Op |
aegis.workflow.run | workflow | false | name | Ag, Ar, Op |
aegis.workflow.generate | workflow | false | input | Ar, Op |
aegis.workflow.logs | workflow | true | execution_id | Ar, Op |
aegis.workflow.wait | workflow | true | execution_id | Ag, Ar, Op |
aegis.workflow.cancel | workflow | true | execution_id | Op |
aegis.workflow.signal | workflow | true | execution_id, response | none: external MCP clients |
aegis.workflow.remove | workflow | true | execution_id | Op |
aegis.workflow.promote | workflow | false | name | Op |
aegis.workflow.demote | workflow | false | name | Op |
aegis.workflow.executions.list | workflow | true | — | Op |
aegis.workflow.executions.get | workflow | true | execution_id | Op |
aegis.workflow.status | workflow | true | execution_id | Op |
aegis.workflow.search | workflow | true | query | Ag, Op |
aegis.task.execute | task | false | agent_id | Ag, Ar, Op |
aegis.task.status | task | true | execution_id | Op |
aegis.task.list | task | true | — | Ag, Op |
aegis.task.cancel | task | false | execution_id | Ag, Op |
aegis.task.remove | task | false | execution_id | Op |
aegis.task.logs | task | true | execution_id | Ag, Op |
aegis.task.wait | task | true | execution_id | Ag, Ar, Op |
aegis.execution.file | execution | true | path; execution_id unless volume_id | Ag, Ex, Ar, Op |
aegis.attachment.read | attachment | true | volume_id, path | System-tier only |
aegis.image.generate | image | false | prompt | Ag, Ex |
aegis.execute.intent | execute | false | intent | Ex, Op |
aegis.execute.status | execute | true | pipeline_execution_id | Ex, Op |
aegis.execute.wait | execute | true | execution_id | Ex, Op |
aegis.goal.create | goal | true | statement, client_ref, channel | none: called by Zaru Web's turn |
aegis.goal.evaluate | goal | true | goal_id, companion_answer | none: called by Zaru Web's turn |
aegis.goal.status | goal | true | goal_id | none: called by Zaru Web's turn |
aegis.goal.cancel | goal | true | goal_id | Ag, Ex, Ar, Op |
aegis.schedule.create | schedule | false | name, target_kind, target | Op |
aegis.schedule.list | schedule | true | — | Ag, Ar, Op |
aegis.schedule.get | schedule | true | schedule_id | Ag, Ar, Op |
aegis.schedule.update | schedule | false | schedule_id | Op |
aegis.schedule.pause | schedule | false | schedule_id | Ag, Ar, Op |
aegis.schedule.resume | schedule | false | schedule_id | Ag, Ar, Op |
aegis.schedule.run_now | schedule | false | schedule_id | none until a security context names it |
aegis.schedule.delete | schedule | false | schedule_id | Ag, Ar, Op |
aegis.schedule.runs | schedule | true | schedule_id | Ag, Ar, Op |
aegis.tools.list | tools | true | — | Ag, Op |
aegis.tools.search | tools | true | — | Ag, Op |
aegis.system.info | system | true | — | Op |
aegis.system.config | system | true | — | Op |
aegis.runtime.list | runtime | true | — | Op |
aegis.file.list | file | true | volume_id, path | Op |
aegis.file.read | file | true | volume_id, path | Op |
aegis.file.write | file | false | volume_id, path, content | Op |
aegis.file.delete | file | false | volume_id, path | Op |
aegis.file.mkdir | file | false | volume_id, path | Op |
aegis.volume.create | volume | false | label, size_limit_bytes | Op |
aegis.volume.list | volume | true | — | Op |
aegis.volume.delete | volume | false | volume_id | Op |
aegis.volume.quota | volume | true | — | Op |
aegis.git.clone | git | false | repo_url, label | Op |
aegis.git.list | git | true | — | Ag, Ar, Op |
aegis.git.status | git | true | binding_id | Op |
aegis.git.refresh | git | false | binding_id | Op |
aegis.git.delete | git | false | binding_id | Op |
aegis.git.commit | git | false | binding_id, message | Op |
aegis.git.push | git | false | binding_id | Op |
aegis.git.diff | git | true | binding_id | Op |
aegis.git.land | git | false | — | none: answered only for a workflow's landing step |
aegis.script.save | script | false | name, code | Op |
aegis.script.list | script | true | — | Op |
aegis.script.get | script | true | id | Op |
aegis.script.update | script | false | id, name, code | Op |
aegis.script.delete | script | false | id | Op |
zaru.init | zaru | N/A | — | C, Ag, Ex, Ar, Op |
zaru.mode | zaru | N/A | target_mode, reason | C, Ag, Ex, Ar, Op |
zaru.docs | zaru | N/A | query | C, Ag, Ex, Ar, Op |
zaru.memory.get | zaru | N/A | — | C, Ag, Ex, Ar, Op |
zaru.memory.set | zaru | N/A | content, version | C, Ag, Ex, Ar, Op |
zaru.schedule | zaru | N/A | target_kind, target, intent, input, reason | C, Ag, Ex, Ar, Op |
zaru.conversations.list | zaru | N/A | — | C, Ag, Ex, Ar, Op |
zaru.conversations.read | zaru | N/A | conversation_id | C, Ag, Ex, Ar, Op |
zaru.conversations.search | zaru | N/A | query | C, Ag, Ex, Ar, Op |
Filesystem Tools (fs.*)
Interact with the agent's mounted Workspace volume via the FSAL layer. All paths must be within
the agent's path_allowlist. Absolute POSIX paths are recommended.
fs.read
Read the contents of a file at the given POSIX path from the mounted Workspace volume.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the file to read. |
line_start | integer | No | 1 | First line to return, counted from 1, at least 1. Give line_start, line_end or both to read only those lines. |
line_end | integer | No | the last line | Last line to return, included, at least 1. Omit both to read the whole file. |
Output:
{
"status": "success",
"path": "/workspace/src/main.rs",
"content": "...",
"size_bytes": 1024
}With a range, content holds those lines followed by a line naming the range and the file's line count, and the answer adds line_start, line_end and line_count:
{
"status": "success",
"path": "/workspace/notes.txt",
"content": "line 5\nline 6\nline 7\nline 8\nLines 5 to 8 of 20 in /workspace/notes.txt.",
"line_start": 5,
"line_end": 8,
"line_count": 20,
"size_bytes": 151
}A range past the file's end stops at its last line; one that starts after it answers "No lines: the range starts at line <n> and <path> has <count> lines." A line number that is not a whole number of 1 or more, or a line_end before line_start, is refused as invalid arguments.
fs.write
Write content to a file at the given POSIX path in the Workspace volume. Automatically creates missing parent directories.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the file to write. |
content | string | Yes | — | String content to write to the file. |
Output:
{
"status": "success",
"path": "/workspace/src/main.rs",
"bytes_written": 1024
}fs.list
List the contents of a directory in the Workspace volume.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the directory to list. |
Output:
{
"status": "success",
"path": "/workspace/src",
"entries": [
{ "name": "main.rs", "file_type": "file" },
{ "name": "lib", "file_type": "directory" }
]
}Each entry has a file_type of either "file" or "directory".
fs.create_dir
Creates a new directory along with any necessary parent directories.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the directory to create. |
Output:
{
"status": "success",
"path": "/workspace/output/reports"
}fs.delete
fs.delete is destructive and irreversible. To delete a non-empty directory,
set recursive: true. Without it, deletion of a non-empty directory will fail
with an error.
Deletes a file or directory.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the file or directory to delete. |
recursive | boolean | No | false | Set to true to delete a directory and all its contents. |
Output:
{
"status": "success",
"path": "/workspace/tmp/cache"
}fs.edit
Performs an exact string replacement in a file.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the file to edit. |
target_content | string | Yes | — | Exact string content to find and replace. Must match exactly once in the file. |
replacement_content | string | Yes | — | New string content to insert in place of target_content. |
target_content must appear exactly once in the file. If the string is not
found or appears more than once, the tool returns an error without modifying
the file.
Output:
{
"status": "success",
"path": "/workspace/src/main.rs",
"message": "File edited successfully"
}fs.multi_edit
Performs multiple sequential string replacements in a file.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Absolute or relative POSIX path of the file to edit. |
edits | array | Yes | — | Array of edit objects applied sequentially. Each object requires target_content (string) and replacement_content (string). |
Edits are applied sequentially in array order. Each edit operates on the
result of the previous edit, so target_content values for later edits must
account for earlier replacements.
Output:
{
"status": "success",
"path": "/workspace/src/main.rs",
"applied": 3
}The applied field is the count of replacements successfully performed.
fs.grep
Recursively searches for a regex pattern within files in a given directory.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
pattern | string | Yes | — | Regex pattern to search for. |
path | string | Yes | — | Directory path to start the recursive search from. |
Output: Formatted string of matches, one per line in path:line_number:content format.
fs.glob
Recursively matches files against a glob pattern.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
pattern | string | Yes | — | Glob pattern to match files (e.g. **/*.rs). |
path | string | Yes | — | Directory path to start the recursive search from. |
Output: Newline-separated list of matching file paths.
Web Tools (web.*)
Access external URLs and perform internet searches. These tools are subject to the agent's
network_profile and any egress restrictions configured at the node level.
web.search
Performs an internet search query.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | — | Search query. |
Output: Formatted list of results, each containing title, URL, and snippet text.
web.fetch
Fetches content from a URL, optionally converting HTML to Markdown.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Yes | — | URL to fetch content from. |
Output: Response body as a string. HTML responses are converted to Markdown when the
to_markdown conversion option is in effect.
Dispatch Protocol Tool (cmd.run)
cmd.run is routed via the Dispatch Protocol — not the FSAL layer. Commands execute inside the
agent's ephemeral container. To expose cmd.run to an agent, the agent manifest must declare a
subcommand_allowlist under spec.builtin_dispatchers:
spec:
builtin_dispatchers:
- name: cmd
capabilities:
- name: cmd.run
subcommand_allowlist:
- "python"
- "pip"
- "bash"Only commands whose first token appears in subcommand_allowlist will be permitted.
cmd.run
Executes a shell command inside the agent's ephemeral container environment. Use this to build, run, or analyze code locally.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
command | string | Yes | — | Command to execute. The first token must appear in the agent's subcommand_allowlist. |
args | array | No | — | Arguments passed to the command, as an array of strings, such as ["-c", "env"]. |
env_additions | object | No | — | Environment variables added for this command, as an object of string values. |
stdin | string | No | — | Text written to the command's standard input, which is then closed; at most max_output_bytes bytes. |
cwd | string | No | /workspace | The directory the command runs in, such as /workspace/app. |
timeout_secs | integer | No | 600 | Seconds the command may run before it is stopped. |
max_output_bytes | integer | No | 1048576 | The most bytes of output kept from the command, and the most bytes stdin may hold. |
A call naming an argument cmd.run does not take is refused, each such argument named: "cmd.run: 'path' is not an argument of cmd.run; its arguments are command, args, cwd, env_additions, stdin, timeout_secs and max_output_bytes, and the directory a command runs in is cwd (/workspace when absent)". The model is told the refusal and the try goes on.
| args | array | No | — | Arguments passed to the command, as an array of strings, such as ["-c", "env"]. |
| env_additions | object | No | — | Environment variables added for this command, as an object of string values. |
| stdin | string | No | — | Text written to the command's standard input, which is then closed; at most max_output_bytes bytes. |
| cwd | string | No | /workspace | The directory the command runs in, such as /workspace/app. |
| timeout_secs | integer | No | 600 | Seconds the command may run before it is stopped. |
| max_output_bytes | integer | No | 1048576 | The most bytes of output kept from the command, and the most bytes stdin may hold. |
A call naming an argument cmd.run does not take is refused, each such argument named: "cmd.run: 'path' is not an argument of cmd.run; its arguments are command, args, cwd, env_additions, stdin, timeout_secs and max_output_bytes, and the directory a command runs in is cwd (/workspace when absent)". The model is told the refusal and the try goes on.
Output:
{
"stdout": "Hello, world!\n",
"stderr": "",
"exit_code": 0
}A non-zero exit_code is returned as a successful tool response — the agent
is responsible for interpreting the exit code and deciding whether to retry or
fail.
Agent Management Tools (aegis.agent.*)
These tools manage the agent registry: creating, reading, updating, deleting, and searching agent definitions. For task execution (running agents), see Task Management Tools.
aegis.agent.create
Parses, validates, and deploys an Agent manifest to the registry.
Access: System
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
manifest_yaml | string | Yes | — | Full Agent manifest YAML to parse, validate, and deploy. |
force | boolean | No | false | Overwrite an existing deployed agent with the same name/version. |
Output:
{
"agent_id": "a1b2c3d4-...",
"deployed": true,
"name": "my-agent",
"version": "1.0.0"
}aegis.agent.list
Lists currently deployed agents and metadata.
Access: User
skip_judge: true
No parameters — accepts an empty object {}.
Output:
{
"agents": [
{
"id": "a1b2c3d4-...",
"name": "my-agent",
"version": "1.0.0",
"status": "active",
"description": "...",
"labels": {}
}
]
}aegis.agent.update
Updates an existing Agent manifest in the registry.
Access: System
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
manifest_yaml | string | Yes | — | Full Agent manifest YAML to update an existing agent. |
force | boolean | No | false | Overwrite an existing version if it already exists. |
Output:
{
"agent_id": "a1b2c3d4-...",
"deployed": true,
"name": "my-agent",
"version": "1.0.1"
}aegis.agent.export
Exports an Agent manifest by name.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Name of the agent to export. |
Output:
{
"manifest_yaml": "kind: Agent\n...",
"id": "a1b2c3d4-...",
"name": "my-agent",
"version": "1.0.0"
}aegis.agent.delete
Deletion is permanent and cannot be undone. Running executions are not affected, but the agent definition will no longer be available for new task dispatch.
Removes a deployed agent from the registry by UUID.
Access: Operator
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | Yes | — | UUID of the agent to remove. |
Output:
{
"agent_id": "a1b2c3d4-...",
"deleted": true
}aegis.agent.generate
Generates an Agent manifest from a natural-language intent.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
input | string | Yes | — | Natural-language intent for the agent to create. |
attachments | array | No | — | Optional array of AttachmentRef objects ({volume_id, path, name, mime_type, size, sha256?}) describing files the generated agent should be wired to read. When present, the generation pipeline declares attachments in the new agent's input_schema and grants it aegis.attachment.read. |
repositories | array | No | — | Your git repositories for the run, each mounted at /workspace/<label> on a work branch of its own: {binding_id, branch?} for one of your bindings (aegis.git.list lists them), or {url, ref?, branch?} for a repository by its URL, whose binding is found or made, before the run starts, with the GitHub connection the run names. See Repositories of a Run. |
This tool returns an execution_id immediately and starts an async authoring
loop. Use aegis.agent.wait or
aegis.task.wait to block until the generated agent is
deployed.
Output:
{
"execution_id": "e1f2a3b4-...",
"status": "started"
}aegis.agent.logs
Retrieve agent-level activity log snapshot.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | Yes | — | UUID of the agent whose activity log should be retrieved. |
limit | integer | No | 50 | Maximum number of events to return. |
offset | integer | No | 0 | Zero-based starting offset into the activity log. |
Output:
{
"tool": "aegis.agent.logs",
"agent_id": "a1b2c3d4-...",
"events": [
{
"event_type": "task_started",
"payload": {},
"recorded_at": "2026-04-05T12:00:00Z"
}
],
"total": 42,
"limit": 50,
"offset": 0
}aegis.agent.search
Semantic search over deployed agents by natural-language query.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | — | Natural-language description of the agent you are looking for. |
tenant_id | string | No | current tenant | Tenant ID to search within. |
limit | integer | No | 10 | Maximum results (1–100, tier-dependent cap). |
min_score | number | No | 0.3 | Minimum relevance score threshold (0.0–1.0). |
labels | object | No | — | Label key-value pairs to filter by. All must match. |
status | string | No | — | Filter by agent status. One of: active, paused, failed. |
include_platform_templates | boolean | No | true | Include platform-provided template agents: every global agent, the built-ins among them, found from your own tenant. |
aegis.agent.search requires a Cortex connection. Results are returned sorted
by score descending.
Output:
{
"tool": "aegis.agent.search",
"query": "image resizer",
"results": [
{
"id": "a1b2c3d4-...",
"name": "image-resizer",
"version": "1.0.0",
"description": "...",
"labels": {},
"score": 0.92
}
],
"total": 5
}aegis.agent.wait
aegis.agent.wait is an alias for aegis.task.wait. Both
tools share identical parameters and output shape.
Alias for aegis.task.wait. Blocks until an agent execution completes.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the execution to wait for. |
poll_interval_seconds | integer | No | 10 | Seconds between status polls (minimum: 1). |
timeout_seconds | integer | No | 600 | Maximum seconds to wait before returning a timeout (minimum: 1). |
Output:
{
"execution_id": "e1f2a3b4-...",
"status": "completed",
"iteration_count": 3,
"last_output": "...",
"produced_files": [],
"last_error": null,
"error": null,
"answer_rejected": false,
"started_at": "2026-04-05T12:00:00Z",
"ended_at": "2026-04-05T12:01:30Z"
}The status field will be one of completed, failed, cancelled, or timed_out. error is the execution's own failure, beside last_error, the last try's error. answer_rejected is true when the last try answered and its semantic judge rejected the answer; the status is still failed, and last_output is the rejected answer.
Workflow Management Tools (aegis.workflow.*)
These tools manage the workflow registry and control workflow execution lifecycle. For workflow authoring and schema, see the Workflow Manifest Reference.
aegis.workflow.create
Performs strict deterministic and semantic workflow validation, then registers on pass, in the caller's tenant at tenant scope. A version already registered answers "Workflow '<name>' version '<version>' is already registered. Increment the version (e.g. to '<version>.1') in the manifest and retry."
Access: System
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
manifest_yaml | string | Yes | — | Full Workflow manifest YAML to parse, validate, semantically judge, and register. |
force | boolean | No | false | Overwrite an existing version if it already exists. |
task_context | string | No | — | Optional task context to guide semantic judges. |
judge_agents | array | No | — | Judge agent names to use for semantic validation. |
min_score | number | No | — | Minimum consensus score required for deployment. |
min_confidence | number | No | — | Minimum consensus confidence required for deployment. |
Output:
{
"workflow_id": "w1b2c3d4-...",
"deployed": true,
"name": "my-workflow",
"version": "1.0.0"
}aegis.workflow.list
Lists currently registered workflows and metadata.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
tenant_id | string | No | local tenant | Optional tenant identifier. |
scope | string | No | — | Scope filter. One of: global (global workflows only), visible (user + tenant + global). Omit to list all for the tenant. |
user_id | string | No | — | Optional user ID for visible scope filter. |
Output:
{
"workflows": [
{
"id": "w1b2c3d4-...",
"name": "my-workflow",
"version": "1.0.0",
"initial_state": "start"
}
]
}aegis.workflow.validate
Validate a workflow manifest against the schema.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
manifest_yaml | string | Yes | — | Full Workflow manifest YAML to parse and deterministically validate. |
Output:
{
"valid": true,
"errors": null
}On failure: { "valid": false, "errors": ["error message 1", "error message 2"] }
aegis.workflow.update
Updates an existing Workflow manifest in the registry.
Access: System
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
manifest_yaml | string | Yes | — | Full Workflow manifest YAML to update an existing workflow. |
force | boolean | No | false | Overwrite an existing version if it already exists. |
Output:
{
"tool": "aegis.workflow.update",
"updated": true,
"deterministic_validation": { "passed": true },
"name": "my-workflow",
"workflow_id": "w1b2c3d4-..."
}It replaces the workflow of the manifest's name in the caller's tenant. On failure updated is false with an error, such as "Workflow not found" or "Workflow update failed: …".
aegis.workflow.export
Exports a Workflow manifest by name.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Name of the workflow to export. |
Output:
{
"manifest_yaml": "kind: Workflow\n...",
"id": "w1b2c3d4-...",
"name": "my-workflow",
"version": "1.0.0"
}aegis.workflow.delete
Deleting a workflow removes the definition from the registry. In-progress executions are not terminated, but new executions of this workflow will no longer be possible.
Removes a registered workflow from the registry by name.
Access: Operator
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Name of the workflow to delete. |
Output:
{
"workflow_id": "w1b2c3d4-...",
"deleted": true
}aegis.workflow.run
Executes a registered workflow by name with optional input parameters.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Name of the workflow to execute. |
intent | string | No | — | Natural-language description of the goal for this run. Injected into workflow input and available to agentic states and task activities. |
input | object | No | — | Workflow input parameters. |
blackboard | object | No | — | Optional blackboard overrides merged into the execution before startup. |
version | string | No | latest | Semantic version of the workflow to execute. When omitted, the latest deployed version is used. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
attachments | array | No | — | Optional array of AttachmentRef objects ({volume_id, path, name, mime_type, size, sha256?}): files the run carries in its input as input.attachments. A ContainerRun step reads them by mounting the volume attachments, read-only (see A step on the run's attachments). An input that names an attached file is filled from the only attachment when left out, and a run naming no attached file is answered {"error": "<sentence>"} before it starts (A model step). |
repositories | array | No | — | Your git repositories for the run, each mounted at /workspace/<label> on a work branch of its own: {binding_id, branch?} for one of your bindings (aegis.git.list lists them), or {url, ref?, branch?} for a repository by its URL, whose binding is found or made, before the run starts, with the GitHub connection the run names. See Repositories of a Run. |
Output:
{
"execution_id": "e1f2a3b4-...",
"status": "started"
}Use aegis.workflow.wait to block until completion.
Available in: Agentic, Architect modes
aegis.workflow.generate
Generates a Workflow manifest from a natural-language objective.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
input | string | Yes | — | Natural-language workflow objective. |
repositories | array | No | — | Your git repositories for the run, each mounted at /workspace/<label> on a work branch of its own: {binding_id, branch?} for one of your bindings (aegis.git.list lists them), or {url, ref?, branch?} for a repository by its URL, whose binding is found or made, before the run starts, with the GitHub connection the run names. See Repositories of a Run. |
Returns an execution_id immediately and starts an async authoring loop. Use
aegis.workflow.wait to block until the generated
workflow is registered.
Output:
{
"execution_id": "e1f2a3b4-...",
"status": "started"
}aegis.workflow.logs
Returns paginated workflow execution events.
Under an operator escalation, an execution of any tenant.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | The id aegis.workflow.run answered for the run. |
limit | integer | No | 50 | Maximum number of events to return, in sequence order (max 200; a larger value returns 200). |
offset | integer | No | 0 | Number of events to skip from the run's first event. |
A call without execution_id is refused: "required field 'execution_id' is missing or null for tool 'aegis.workflow.logs'".
Output:
{
"tool": "aegis.workflow.logs",
"execution_id": "e1f2a3b4-...",
"status": "running",
"events": [
{
"sequence": 1,
"event_type": "state_entered",
"state_name": "start",
"iteration_number": null,
"payload": {},
"recorded_at": "2026-04-05T12:00:00Z"
}
],
"total": 12,
"limit": 50,
"offset": 0,
"has_more": false
}The answer also carries the run's workflow_id. total is the run's number of events, not the page's; has_more is true when events follow the page; limit and offset are the values applied.
aegis.workflow.wait
Polls a workflow execution until it reaches a terminal state and returns the result.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow execution to wait for. |
poll_interval_seconds | integer | No | 5 | Seconds between polls. |
timeout_seconds | integer | No | 300 | Maximum wait time in seconds. |
Output (completed):
{
"execution_id": "e1f2a3b4-...",
"workflow_id": "w1b2c3d4-...",
"status": "completed",
"current_state": "end",
"blackboard": {},
"started_at": "2026-04-05T12:00:00Z",
"last_transition_at": "2026-04-05T12:02:00Z"
}Output (timed out):
{
"execution_id": "e1f2a3b4-...",
"status": "running",
"current_state": "processing",
"timed_out": true
}The status field upon completion will be one of completed, failed, or cancelled.
aegis.workflow.cancel
Cancel a workflow execution. An open run is asked to cancel; when Temporal no longer runs the execution, its record is ended as cancelled. A record already terminal is left as it is.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow execution to cancel. |
Output:
{
"tool": "aegis.workflow.cancel",
"cancelled": true,
"execution_id": "e1f2a3b4-..."
}On failure: { "cancelled": false, "error": "execution already in terminal state" }
aegis.workflow.signal
Send human input response to a paused workflow execution.
Access: User
Available in: no Zaru mode, operator mode included: Zaru's companion never answers a workflow run's Human gate, which the person answers on their own control (Human Gates of a Workflow Run). Zaru's MCP server still lists it to external MCP clients such as Claude Code, where the person's own client calls it.
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow execution to signal. |
response | string | Yes | — | Human input response text to send to the paused workflow. |
feedback | string | No | — | The person's feedback with the response, read by the workflow as {{human.feedback}}. |
Output:
{
"tool": "aegis.workflow.signal",
"signalled": true,
"execution_id": "e1f2a3b4-..."
}On failure: { "signalled": false, "error": "…" }, such as "Workflow execution '<id>' not found" for an execution that is not in the caller's tenant, or "Failed to signal workflow execution: …".
aegis.workflow.remove
Remove a workflow execution record.
Access: Operator
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow execution to remove. |
The execution must be in a terminal state (completed, failed, or
cancelled) before it can be removed.
Output:
{
"tool": "aegis.workflow.remove",
"removed": true,
"execution_id": "e1f2a3b4-..."
}On failure: { "removed": false, "error": "execution is not in a terminal state" }
aegis.workflow.promote
Promote a workflow from user scope to tenant scope.
Access: System
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Workflow name or ID to promote. |
target_scope | string | No | global | Target scope. One of: tenant, global. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
Promotion elevates a workflow's visibility scope, making it available to a
wider set of users. Promoting to global makes the workflow visible to all
tenants on the platform.
Output:
{
"workflow_id": "w1b2c3d4-...",
"name": "my-workflow",
"promoted": true,
"target_scope": "global"
}aegis.workflow.demote
Demote a workflow from tenant scope to user scope.
Access: System
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Workflow name or ID to demote. |
target_scope | string | No | tenant | Target scope. One of: tenant, user. |
user_id | string | No | — | Owner user ID when demoting to user scope. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
Demotion narrows a workflow's visibility scope, restricting access to a smaller audience.
Output:
{
"workflow_id": "w1b2c3d4-...",
"name": "my-workflow",
"demoted": true,
"target_scope": "tenant"
}aegis.workflow.executions.list
Lists workflow executions, optionally filtered.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer | No | 20 | Maximum number of results to return. |
offset | integer | No | 0 | Pagination offset. |
workflow_id | string | No | — | Optional workflow UUID or workflow name filter. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
Output:
{
"executions": [
{
"execution_id": "e1f2a3b4-...",
"workflow_id": "w1b2c3d4-...",
"status": "completed",
"current_state": "end",
"started_at": "2026-04-05T12:00:00Z"
}
],
"total": 42,
"limit": 20,
"offset": 0
}aegis.workflow.executions.get
Returns details of a specific workflow execution.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow execution to inspect. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
Output:
{
"execution_id": "e1f2a3b4-...",
"workflow_id": "w1b2c3d4-...",
"status": "completed",
"input": {},
"blackboard": {},
"state_outputs": {},
"current_state": "end",
"started_at": "2026-04-05T12:00:00Z",
"last_transition_at": "2026-04-05T12:02:00Z"
}aegis.workflow.status
Returns current status of a workflow execution.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow execution to inspect. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
Output:
{
"execution_id": "e1f2a3b4-...",
"workflow_id": "w1b2c3d4-...",
"status": "running",
"current_state": "processing",
"started_at": "2026-04-05T12:00:00Z",
"last_transition_at": "2026-04-05T12:01:00Z"
}aegis.workflow.search
Semantic search over registered workflows.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | — | Natural-language description of the workflow you are looking for. |
tenant_id | string | No | current tenant | Tenant ID to search within. |
limit | integer | No | 10 | Maximum results (1–100, tier-dependent cap). |
min_score | number | No | 0.3 | Minimum relevance score threshold (0.0–1.0). |
labels | object | No | — | Label key-value pairs to filter by. All must match. |
include_platform_templates | boolean | No | true | Include platform-provided template workflows: every global workflow, the built-ins such as transcribe-audio and the-forge among them, found from your own tenant. |
aegis.workflow.search requires a Cortex connection. Results are returned
sorted by score descending.
Output:
{
"tool": "aegis.workflow.search",
"query": "data pipeline",
"results": [
{
"id": "w1b2c3d4-...",
"name": "etl-pipeline",
"version": "1.0.0",
"description": "...",
"labels": {},
"score": 0.88
}
],
"total": 3
}Task Management Tools (aegis.task.*)
These tools start and monitor individual agent executions (tasks). An agent must be deployed before a task can be dispatched against it. For agent lifecycle management, see Agent Management Tools.
aegis.task.execute
Starts a new agent execution (task) by agent UUID or name.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | Yes | — | UUID or name of the agent to execute. |
intent | string | No | — | Natural-language description of what the agent should accomplish. Steers the LLM prompt directly. Complementary to structured input. |
input | object | No | — | Structured data for the agent, validated against spec.input_schema when declared. The well-known sub-field input.prompt (string) holds the full task instructions or user request. |
attachments | array | No | — | Optional array of AttachmentRef objects ({volume_id, path, name, mime_type, size, sha256?}) describing files the agent should read. The agent must declare attachments in spec.input_schema and include aegis.attachment.read in spec.tools to consume them. |
version | string | No | latest | Semantic version of the agent to execute. When omitted, the latest deployed version is used. |
repositories | array | No | — | Your git repositories for the run, each mounted at /workspace/<label> on a work branch of its own: {binding_id, branch?} for one of your bindings (aegis.git.list lists them), or {url, ref?, branch?} for a repository by its URL, whose binding is found or made, before the run starts, with the GitHub connection the run names. See Repositories of a Run. |
Use intent for natural-language steering and input.prompt for structured
task instructions. Both can be provided together.
Output:
{
"execution_id": "e1f2a3b4-...",
"status": "started"
}Use aegis.task.wait to block until completion.
aegis.task.status
Returns the current status and output of an execution by UUID.
Under an operator escalation the execution may belong to any tenant; without one, another tenant's execution is not found.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the execution to check. |
Output:
{
"execution_id": "e1f2a3b4-...",
"agent_id": "a1b2c3d4-...",
"tenant_id": "u-...",
"status": "completed",
"iteration_count": 2,
"last_output": "...",
"produced_files": [{"path": "/workspace/report.pdf", "size_bytes": 48213, "content_type": "application/pdf"}],
"last_error": null,
"error": null,
"answer_rejected": false,
"started_at": "2026-04-05T12:00:00Z",
"ended_at": "2026-04-05T12:01:00Z"
}The status field is one of pending, running, completed, failed, or cancelled.
error is the execution's own failure reason, beside last_error, the last try's error. answer_rejected is true when the last try answered and its semantic judge rejected that answer, otherwise false; an execution that ends this way is failed, and last_output is the rejected answer (When a Later Try Does Not Fit).
produced_files lists the files the execution's declared outputs (spec.execution.outputs) found once it completed, each with path, size_bytes and content_type; before completion, and for an execution with no declared outputs, it is empty.
aegis.task.list
Lists recent executions, optionally filtered by agent.
Under an operator escalation and without agent_id, the list holds the most recent executions of every tenant; with agent_id it stays within the caller's tenant.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | No | — | Optional UUID to filter executions by agent. |
limit | integer | No | 20 | Maximum number of results. |
Output:
{
"executions": [
{
"id": "e1f2a3b4-...",
"agent_id": "a1b2c3d4-...",
"tenant_id": "u-...",
"status": "completed",
"started_at": "2026-04-05T12:00:00Z"
}
]
}aegis.task.cancel
Cancels one running agent execution by UUID. The person's goal stays open and the execution stays bound to it, so the corrected execution can start next; aegis.goal.cancel ends the whole request.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the execution to cancel. |
Output:
{
"execution_id": "e1f2a3b4-...",
"cancelled": true
}aegis.task.remove
Removes a completed or failed execution record by UUID.
Access: Operator
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the execution to remove. |
The execution must be in a terminal state. Use
aegis.task.cancel first if the execution is still
running.
Output:
{
"execution_id": "e1f2a3b4-...",
"removed": true
}aegis.task.logs
Returns paginated execution events for a task by UUID.
Under an operator escalation, an execution of any tenant.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the execution whose event log should be retrieved. |
limit | integer | No | 50 | Maximum number of events to return (capped at 200). |
offset | integer | No | 0 | Zero-based starting offset into the persisted event log. |
Output:
{
"tool": "aegis.task.logs",
"execution_id": "e1f2a3b4-...",
"status": "completed",
"events": [
{
"sequence": 1,
"event_type": "iteration_started",
"payload": {},
"recorded_at": "2026-04-05T12:00:00Z"
}
],
"total": 8,
"limit": 50,
"offset": 0
}aegis.task.wait
Polls an execution until it reaches a terminal state and returns the result.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the execution to wait for. |
poll_interval_seconds | integer | No | 10 | Seconds between status polls (minimum: 1). |
timeout_seconds | integer | No | 600 | Maximum seconds to wait before returning a timeout (minimum: 1). |
Output:
{
"execution_id": "e1f2a3b4-...",
"status": "completed",
"iteration_count": 3,
"last_output": "...",
"produced_files": [{"path": "/workspace/report.pdf", "size_bytes": 48213, "content_type": "application/pdf"}],
"last_error": null,
"error": null,
"answer_rejected": false,
"started_at": "2026-04-05T12:00:00Z",
"ended_at": "2026-04-05T12:01:30Z"
}The status field will be one of completed, failed, cancelled, or timed_out. A terminal answer carries error and answer_rejected as aegis.task.status does.
A terminal answer carries produced_files as aegis.task.status does.
aegis.execution.file
Read a file from a completed execution's workspace volume. Use this to retrieve output files after an agent or task execution finishes. Given volume_id, it reads the file from that volume of yours instead, such as an image aegis.image.generate saved. Supports both text and binary files.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Unless volume_id is given | — | The execution ID to retrieve a file from. |
volume_id | string | No | — | Read the file from this volume of your tenant instead of the execution's workspace: the volume_id an aegis.image.generate answer names for each file. |
path | string | Yes | — | File path relative to /workspace (e.g. output.md or /workspace/output.md); with volume_id, the path inside that volume (e.g. generated/<batch>/1.jpg). |
A call naming neither execution_id nor volume_id is refused: "aegis.execution.file: missing required field 'execution_id' (string), or 'volume_id' (string) for a file in a volume".
Available in: Agentic, Execute, Workflow modes
The path is automatically normalized — both /workspace/report.md and
report.md resolve to the same file. Works after execution completes, while
the volume is still available (ephemeral volumes are cleaned up based on TTL).
Output schema:
| Field | Type | Description |
|---|---|---|
status | string | success. |
path | string | The path as the call gave it. |
content | string | File contents as text. Present only for text files. |
content_type | string | MIME type of the file (e.g. text/plain, image/png, application/pdf). |
is_binary | boolean | true if the file is binary, false for text files. |
download_url | string | The path of GET /v1/executions/{id}/files/{path} for this file, with ?volume_id=<id> when the call named a volume. |
volume_id | string | The volume read. Present only when the call named one. |
size_bytes | number | Size of the file in bytes. |
Text files include their content inline in the content field so LLMs can consume it directly. Binary files (images, PDFs, archives, etc.) omit content: their bytes are read from the route download_url names, by the client application.
A file that cannot be read answers {"status": "error", "error": "not_found", "message": "…"}. A volume that does not exist, another tenant's volume and a missing file answer alike, "no file <path> in volume <id>", and another tenant's execution answers as one with no workspace, "no workspace volume for execution <id>", so the answer never tells that it exists.
Text file example:
{
"status": "success",
"path": "output.md",
"content": "# Report\n\nAnalysis complete. Found 3 issues...",
"content_type": "text/markdown",
"is_binary": false,
"size_bytes": 1847,
"download_url": "/v1/executions/e1f2a3b4-.../files/output.md"
}Binary file example:
{
"status": "success",
"path": "generated/54a33efd/1.jpg",
"content_type": "image/jpeg",
"is_binary": true,
"size_bytes": 242323,
"download_url": "/v1/executions/9f0b2e1f-.../files/generated/54a33efd/1.jpg?volume_id=9f0b2e1f-...",
"volume_id": "9f0b2e1f-..."
}The download URL is the path of the REST endpoint GET /v1/executions/{id}/files/{path}, which answers the file's bytes from the
storage backend to a caller with the scope execution:read. With no
execution named, its id segment carries the volume's id and is not read.
Attachment Tools (aegis.attachment.*)
aegis.attachment.read
Reads the bytes of an attached file from a user volume. Platform-internal: only available to system-tier agents (those running under security_context: aegis-system-agent-runtime or aegis-system-operator). User-tier agents do not see this tool in aegis.tools.list and direct calls return ToolNotAllowed. Tenant-scoped — the orchestrator validates that the caller's tenant matches the volume's owner before reading.
This is the read path for files dispatched via the attachments field on aegis.task.execute, aegis.agent.generate, and aegis.execute.intent. Generated agents that consume attachments declare it in spec.tools and call it once per attachment they need to read.
Access: System
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the volume containing the attachment. Typically the volume_id of an AttachmentRef from the dispatch's attachments array. |
path | string | Yes | — | Path inside the volume. Typically the path of an AttachmentRef from the dispatch's attachments array. |
Output schema:
| Field | Type | Description |
|---|---|---|
content | string | File contents, base64-encoded. |
mime_type | string | MIME type detected by content-sniffing. |
size | integer | Size of the file in bytes. |
sha256 | string | Hex-encoded SHA-256 digest of the file bytes. |
Image Generation Tool (aegis.image.generate)
aegis.image.generate
Generates images from a text prompt with one of the node's image generation models and saves each as a file named by its type: .jpg, .png or .webp.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | Yes | — | What the image shows. |
alias | string | No | the node's first image generation alias | Which of the node's image generation models. |
size | string | No | the model's default | The image's size as <width>x<height>, such as 1024x1024. A model that takes no size is sent none, and the size asked is accepted. |
count | integer | No | 1 | How many images, 1 to 4. |
Inside a run, each image is written to the run's workspace volume as /workspace/generated/<n>.<ext>, numbered on from the files already there, and recorded as a file the run produced in that iteration. Called from a person's conversation, outside any run, each is written to the person's chat attachments as generated/<batch>/<n>.<ext>, where a next turn can attach it. <ext> is jpg for image/jpeg, webp for image/webp and png otherwise. A workflow generates images with its own step, the action image_generate.
Output:
{
"files": [
{ "volume_id": "9f0b2e1f-…", "path": "generated/54a33efd/1.jpg", "content_type": "image/jpeg", "size_bytes": 696043 }
],
"fetch": "Fetch it with aegis.execution.file, volume_id 9f0b2e1f-…, path generated/54a33efd/1.jpg."
}The answer names no URL. fetch says how to read each file back: aegis.execution.file with the file's volume_id and path; for several files it reads "Fetch each with aegis.execution.file: volume_id <id>, path <path>; volume_id <id>, path <path>.". Every refusal comes before the model is called: a node with no image generation alias answers "this node has no image generation model"; an alias that is not one answers "'<alias>' is not an image generation model; the image generation models are <list>"; a missing or empty prompt answers "'prompt' is required: what the image shows"; a count outside 1 to 4 answers "'count' is 1 to 4"; a size not of the form <width>x<height> answers "the image generation model refused the request: invalid image request: size '<size>' is not <width>x<height>, for example 1024x1024". A request the model refuses answers "the image generation model refused the request: …" in the model's words. Any other failure of the model, its capacity refusal (HTTP 429) among them, answers that the model is unavailable: "the image generation model '<alias>' failed: …", for a 429 "… failed: image provider rate limit exceeded".
Execute Pipeline Tools (aegis.execute.*)
These tools power Execute mode in Zaru and the intent-to-execution API. They run a multi-step pipeline: intent → agent discovery or generation → code generation → execution → result. No pre-existing agent is required.
aegis.execute.intent
Starts the intent-to-execution pipeline: discovers or generates an agent, writes code, executes in a container, and returns the formatted result.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
intent | string | Yes | — | Natural-language description of what to execute (e.g. "resize images in /workspace to 800x600"). |
inputs | object | No | — | Optional structured inputs passed to the pipeline. |
attachments | array | No | — | Optional array of AttachmentRef objects ({volume_id, path, name, mime_type, size, sha256?}) describing files the generated execution should be able to read. References are passed deterministically to the generated code agent and surface in its workspace. |
volume_id | string | No | ephemeral | Optional persistent volume ID to use as workspace. When omitted, an ephemeral volume is created. |
language | string | No | python | Execution language. One of: python, javascript, bash. |
timeout_seconds | integer | No | — | Optional execution timeout in seconds. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
repositories | array | No | — | Your git repositories for the run, each mounted at /workspace/<label> on a work branch of its own: {binding_id, branch?} for one of your bindings (aegis.git.list lists them), or {url, ref?, branch?} for a repository by its URL, whose binding is found or made, before the run starts, with the GitHub connection the run names. See Repositories of a Run. |
Output:
{
"pipeline_execution_id": "p1b2c3d4-...",
"status": "started",
"stream_url": "https://..."
}Use aegis.execute.status or aegis.execute.wait to
track completion.
aegis.execute.status
Returns the current status of an intent-to-execution pipeline run.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_execution_id | string | Yes | — | UUID of the pipeline execution to check. |
tenant_id | string | No | local tenant | Optional tenant identifier. |
Output (running):
{ "status": "running" }Output (completed):
{
"status": "completed",
"final_result": "...",
"duration_ms": 4523,
"reused_existing_agent": false
}Output (failed):
{
"status": "failed",
"reason": "...",
"failed_at_state": "code_generation"
}aegis.execute.wait
aegis.execute.wait is an alias for
aegis.workflow.wait. Pass the pipeline_execution_id
returned by aegis.execute.intent as the
execution_id parameter.
Alias for aegis.workflow.wait. Blocks until pipeline execution completes.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
execution_id | string | Yes | — | UUID of the workflow/pipeline execution to wait for. Pass the pipeline_execution_id from aegis.execute.intent. |
poll_interval_seconds | integer | No | 5 | Seconds between polls. |
timeout_seconds | integer | No | 300 | Maximum wait time in seconds. |
Output: Same shape as aegis.workflow.wait.
Goal Tools (aegis.goal.*)
A goal holds a user's request, stated once, and every execution started for it. Zaru Web's turn calls aegis.goal.create, aegis.goal.evaluate and aegis.goal.status itself, and no Zaru mode offers those three to the companion's model; aegis.goal.cancel is offered in Agentic, Execute and Architect modes. A goal belongs to the user who created it, in that user's tenant: a call with no user identity is refused, aegis.goal.status and aegis.goal.cancel answer another user's goal as not found, and aegis.goal.evaluate refuses it goal_not_open. A refusal is { "tool", "error", "message" }.
Binding work to a goal. aegis.agent.generate, aegis.task.execute, aegis.workflow.generate, aegis.workflow.run and aegis.execute.intent read an optional goal_id argument that their advertised schemas do not list. A goal_id that is not an open goal of the caller is refused goal_not_open before anything starts; otherwise the execution started is bound to the goal and appears in its executions.
The bounds and thresholds below are the node's spec.goals.
aegis.goal.create
Creates a goal. An open goal of the same user under the same client_ref is first closed superseded.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
statement | string | Yes | — | The user's request, verbatim; not empty, at most 32,768 characters. |
client_ref | string | Yes | — | The caller's opaque reference, for Zaru Web the conversation id; not empty. |
channel | string | Yes | — | web or api. |
Output: { "goal_id": "..." }. A statement that is empty or too long, or an empty client_ref, is refused goal_invalid.
aegis.goal.evaluate
Judges the goal after a turn with the built-in judge agent goal-judge and answers whether a continuation round is granted. One call waits at most 45 seconds for the verdict; until it is in, the answer is { "state": "judging", "goal_id", "round" }, and the caller calls again with the same round.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
goal_id | string | Yes | — | The goal. |
companion_answer | string | Yes | — | The text the user was shown in the turn just ended; read to 8,192 characters. |
round | integer | No | 0 | Absent on a goal's first evaluation; afterwards the round the last answer carried. |
Output:
{
"goal_id": "g1b2c3d4-...",
"state": "open",
"round": 1,
"rounds_left": 2,
"verdict": { "score": 0.4, "confidence": 0.8, "reasoning": "...", "signals": [] },
"outcome": "not_met",
"continue": true,
"executions": [{ "execution_id": "e1f2a3b4-...", "status": "completed", "agent_or_workflow": "..." }]
}round and rounds_left count the continuation rounds granted so far and those left; the caller passes round back on its next call. The judge receives the goal's statement, each bound execution's final state and output, and companion_answer; its verdict scores five signals, delivered, evidence, chain, feasibility and alignment. The outcome is met when the score and the confidence reach met_min_score and met_min_confidence; otherwise cannot_be_met when the feasibility signal scores at most cannot_be_met_max_feasibility; otherwise not_met. met and cannot_be_met close the goal in that state. not_met grants a round (continue: true) while fewer than max_continuations rounds have been granted, and otherwise closes the goal exhausted.
- A
not_metverdict while an execution started for the goal byaegis.agent.generateoraegis.task.executewaits on an approval answerswaiting_on: "approval"withapproval_idsandcontinue: false, and decides no round: the next evaluation judges it again. - Evaluating a round already decided answers that round's stored answer and grants nothing again; a round that is neither decided nor the current one is refused
goal_round_mismatch. - A goal open past
lifetime_secondsclosesexpired. A closed goal answers{ goal_id, state, round, rounds_left, continue: false, executions }. - A verdict that cannot be read, or a judge execution that fails or is cancelled, runs the judge once more; a second such end decides the round
not_metwith score and confidence 0 and the fault as its reasoning. - A judge that cannot be started, for example because
goal-judgeis not deployed, is refusedgoal_judge_unavailable.
aegis.goal.status
Returns the goal, its bound executions and every verdict. Read-only.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
goal_id | string | Yes | — | The goal. |
Output: { goal_id, statement, client_ref, channel, state, rounds, created_at, closed_at, closed_reason, executions: [{ execution_id, kind, agent_or_workflow, status, started_at, ended_at }], verdicts: [{ round, attempt, score, confidence, outcome, reasoning, continue, waiting_on }] }. Each verdict's round is the round it judged, counted from 0. state is open, met, cannot_be_met, exhausted, expired, superseded, stopped or cancelled; closed_reason says why a cancelled goal closed: the reason given to aegis.goal.cancel, or its execution <id> was cancelled when a cancel of a bound execution ended it; it is null otherwise. A goal that is not the caller's is refused goal_not_found.
aegis.goal.cancel
Stops the caller's goal when the person asks to stop. An open goal closes cancelled with the reason given, so no further round is granted and no judge starts after it; then the judge still running for the current round, and every execution bound to the goal that has not ended, is cancelled. Unlike the three tools above, the companion's model is offered this one, in Agentic, Execute and Architect modes, and Zaru Web calls it when the person stops a goal from the chat.
Access: User
skip_judge: true
Available in: Agentic, Execute, Architect modes
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
goal_id | string | Yes | — | The goal. |
reason | string | No | The person asked to stop. | Why the person stopped the goal, in their words. Kept with the goal, trimmed, to 1,000 characters; an empty reason keeps the default. |
Output:
{
"goal_id": "g1b2c3d4-...",
"state": "cancelled",
"closed_reason": "The person asked to stop.",
"round": 1,
"rounds_left": 2,
"continue": false,
"executions": [{ "execution_id": "e1f2a3b4-...", "status": "cancelled", "agent_or_workflow": "..." }],
"cancelled": true,
"cancelled_executions": ["e1f2a3b4-..."],
"failed_executions": []
}cancelled_executions lists each execution and judge this call cancelled, and failed_executions each one whose cancel failed; a later call tries those again. cancelled is true only when the goal is closed cancelled and no cancel failed. A goal that had already closed keeps its state and its reason: the call still cancels what is still running for it, and answers cancelled: false. A goal that is not the caller's is refused goal_not_found, and a call with no user identity is refused.
Tool Discovery (aegis.tools.*)
These tools enumerate the available MCP tool catalog. Results are filtered by the caller's
SecurityContext — different tiers see different subsets of tools.
These tools have no formally enforced input schema in the orchestrator (the schema falls through
to a generic { "type": "object" }). The parameters below are the de facto accepted values.
aegis.tools.list
List all MCP tools available to your security context with pagination and optional source/category filtering.
Access: User
skip_judge: true
No parameters — accepts an empty object {}.
Output:
{
"tool": "aegis.tools.list",
"tools": [
{
"name": "fs.read",
"description": "Read the contents of a file...",
"source": "builtin",
"skip_judge": true
}
],
"total": 60
}aegis.tools.search
Search for MCP tools by keyword, name pattern, source, category, or tags. Returns tools matching your query within your security context.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | No | — | Search term matched against tool names and descriptions. |
Output:
{
"tool": "aegis.tools.search",
"query": "workflow",
"tools": [
{
"name": "aegis.workflow.create",
"description": "...",
"source": "builtin",
"skip_judge": true
}
],
"total": 19
}System Tools (aegis.system.*)
aegis.system.info
Returns system version, status, and capabilities.
Access: Operator
skip_judge: true
No parameters — accepts an empty object {}.
Output:
{
"version": "0.12.0",
"status": "healthy",
"capabilities": ["workflows", "cortex", "seal_gateway"]
}The status field is one of healthy or unhealthy.
aegis.system.config
Returns the current node configuration.
Access: Operator
skip_judge: true
No parameters — accepts an empty object {}.
Returns the node configuration, parsed from the active configuration file,
never the file's text. Every secret setting is shown as the reference it is
written with (such as env:STRIPE_SECRET_KEY), or as [REDACTED] when it is
written literally; addresses are shown without any credential in them. See
the Node Configuration Reference for the full
schema.
Output:
{
"tool": "aegis.system.config",
"config_path": "/etc/aegis/node-config.yaml",
"config": {
"apiVersion": "100monkeys.ai/v1",
"kind": "NodeConfig",
"metadata": { "name": "..." },
"spec": {
"database": { "url": "env:AEGIS_DATABASE_URL" },
"billing": { "stripe_secret_key": "[REDACTED]" }
}
}
}If the file cannot be read as a node configuration, the output carries error,
naming the line and column, and none of the file's text.
Schema Tools (aegis.schema.*)
aegis.schema.get
Returns the canonical JSON Schema for a manifest kind (agent or workflow).
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
key | string | Yes | — | Schema key to retrieve. Supported values: "agent/manifest/v1", "workflow/manifest/v1". |
Output: The full JSON Schema object for the requested manifest type.
aegis.schema.validate
Validates a manifest YAML string against its canonical JSON Schema.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
kind | string | Yes | — | Manifest kind to validate against. Supported values: "agent", "workflow". |
manifest_yaml | string | Yes | — | Full manifest YAML text to validate against the canonical schema. |
Output:
{
"valid": true,
"errors": null
}On failure: { "valid": false, "errors": ["error message 1"] }
Runtime Discovery (aegis.runtime.*)
aegis.runtime.list
List all supported standard runtime environments (language/version pairs). Call this before creating an agent manifest to ensure the declared runtime is valid.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
language | string | No | — | Filter by language name (e.g. "python", "go"). |
Call aegis.runtime.list before writing spec.runtime in agent manifests to
verify the exact language + version identifiers accepted by the platform.
See the Standard Runtime Registry
for the full list.
Output:
{
"tool": "aegis.runtime.list",
"runtimes": [
{
"language": "python",
"version": "3.12",
"image": "ghcr.io/100monkeys/runtime-python:3.12",
"description": "CPython 3.12",
"deprecated": false
}
],
"custom_runtime_supported": true
}Volume Filesystem Tools (aegis.file.*)
These tools operate on files inside tenant-scoped persistent volumes. Every call is authorized against the caller's bearer token — callers can only reach volumes they own. Paths are resolved relative to the volume root. Volume ownership, quota, and tier limits are enforced by the orchestrator backend; the tool-availability gate itself is uniform across all tiers.
The aegis.file.* family is distinct from the agent-workspace fs.* family.
fs.* operates on the mounted ephemeral workspace inside a running agent
container; aegis.file.* operates on the caller's persistent user volumes by
volume_id.
aegis.file.list
List directory contents in a user volume.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the target volume. |
path | string | Yes | — | Directory path relative to the volume root. |
Output: Directory listing with entry names and file / directory type discriminators.
aegis.file.read
Read the contents of a file in a user volume.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the target volume. |
path | string | Yes | — | File path relative to the volume root. |
Output: File contents. Text files return inline string content. Binary files return a base64-encoded payload or a short-lived download URL depending on size.
aegis.file.write
Write content to a file in a user volume. Creates the file if it does not exist and overwrites it if it does.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the target volume. |
path | string | Yes | — | File path relative to the volume root. |
content | string | Yes | — | File content. Binary payloads must be base64-encoded by the caller. |
Output: Confirmation with path and bytes written. Fails if the write would exceed the volume's quota.
aegis.file.delete
aegis.file.delete is destructive and irreversible.
Delete a file or directory in a user volume.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the target volume. |
path | string | Yes | — | File or directory path relative to the volume root. |
Output: Confirmation with the deleted path.
aegis.file.mkdir
Create a directory in a user volume, including any missing parent directories.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the target volume. |
path | string | Yes | — | Directory path relative to the volume root. |
Output: Confirmation with the created path.
Git Repository Tools (aegis.git.*)
Manage SeaweedFS-backed git repository bindings. A binding pairs a remote repository with a
persistent volume mounted at /workspace/{label}. The clone is performed asynchronously —
aegis.git.clone returns immediately with the binding in a Pending/Cloning state; use
aegis.git.status to poll until ready. aegis.git.commit, aegis.git.push, and aegis.git.diff
enable canvas-style write-back against the bound volume.
Inside a run. aegis.git.status, aegis.git.diff, aegis.git.commit and aegis.git.push name one of the run's repositories by its label in repository, and never read a binding_id. A call that names no repository (absent or empty) takes the run's repository when the run holds exactly one, as if its label had been named; in a run holding two or more it is refused with "name one of this run's repositories by its label: <labels>", the run's labels in its order, and a label the run did not mount is refused with "repository '<label>' is not one of this run's repositories".
aegis.git.clone
Create a git repo binding and trigger an asynchronous clone into a workspace volume.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
repo_url | string | Yes | — | Repository URL (https://... or git@...). |
label | string | Yes | — | Human-readable binding name; the clone is mounted at /workspace/{label}. |
credential_binding_id | string | No | — | UUID of a credential binding (SSH key or API key) for private repos. |
git_ref | object | No | { kind: "branch", value: "main" } | Git ref to check out. Fields: kind (branch / tag / commit) and value. |
sparse_paths | array | No | — | Optional list of sparse-checkout paths. |
auto_refresh | boolean | No | false | Enable webhook-driven auto-refresh. |
shallow | boolean | No | true | Perform a shallow clone. |
Output: The newly created binding DTO with status Pending or Cloning.
aegis.git.list
Lists the caller's git repository bindings, redacted: each binding's id, repository URL, ref, state and label. A run on a repository names a binding by its id in repositories (see Repositories of a Run); a binding the platform made for a repository named by its URL is listed with the others.
Access: User
skip_judge: true
Available in: Agentic, Architect modes
Takes no arguments: the caller is the person whose bindings are listed.
aegis.git.status
Get clone/refresh status for a git repo binding. Returns the binding with its current status,
last commit SHA, and last_cloned_at timestamp.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
repository | string | No | — | Inside a run: the label of one of the run's repositories, mounted at /workspace/<label>. In a run that holds one repository it may be left out. |
binding_id | string | No | — | Outside a run: the id of one of your git repository bindings. Never read inside a run. |
Output: Binding DTO with status and most recent commit information.
aegis.git.refresh
Trigger a fetch + checkout to update the bound volume to the latest remote HEAD (for branch refs) or re-verify the pinned ref (for tag / commit refs).
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
binding_id | string | Yes | — | UUID of the git repo binding. |
Output: Confirmation with updated status fields.
aegis.git.delete
Deletes the binding and cascade-deletes the associated volume. Any uncommitted or unpushed work in the bound volume is lost.
Soft-delete a git repo binding and cascade-delete the associated volume.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
binding_id | string | Yes | — | UUID of the git repo binding. |
Output: Confirmation of deletion.
aegis.git.commit
Stage all changes in the bound volume and commit with the given message. Returns the new commit SHA. Fails if there are no changes to commit.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
repository | string | No | — | Inside a run: the label of one of the run's repositories, mounted at /workspace/<label>. In a run that holds one repository it may be left out. |
binding_id | string | No | — | Outside a run: the id of one of your git repository bindings. Never read inside a run. |
message | string | Yes | — | Commit message. |
Output: Object containing the new commit SHA.
aegis.git.push
Push committed changes to the remote. Requires a credential_binding_id set on the binding for
authenticated remotes.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
repository | string | No | — | Inside a run: the label of one of the run's repositories. In a run that holds one repository it may be left out. |
binding_id | string | No | — | Outside a run: the id of one of your git repository bindings. Never read inside a run. |
remote | string | No | origin | Remote name. |
ref | string | No | current branch | Ref to push. |
Output: Confirmation of push with remote and ref details.
aegis.git.diff
Return the unified diff of the bound volume's working tree (or index, if staged: true). Read-only.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
repository | string | No | — | Inside a run: the label of one of the run's repositories. In a run that holds one repository it may be left out. |
binding_id | string | No | — | Outside a run: the id of one of your git repository bindings. Never read inside a run. |
staged | boolean | No | false | If true, return the diff of the index against HEAD. |
Output: Unified-diff text.
aegis.git.land
Lands a workflow run's work branch on its repository's branch as a fast-forward. It is the call a workflow's Action state with action: repository_land makes (see The Forge), answered only for that step: any other caller, an agent's tool call among them, is refused with "aegis.git.land is answered only for a workflow's own landing step". No agent lists it.
Access: the workflow interpreter only
skip_judge: false
Approval: always asked of the run's person, as for any approval-gated tool; a declined request answers "approval request <status>; nothing was landed" and pushes nothing.
Takes no argument of the caller's: the run's repository is the one the workflow execution holds. Approved, the orchestrator, in one git step with the person's binding, pushes the work branch to origin, then the work branch's HEAD to refs/heads/<the binding's ref>, neither with force.
| Refusal | When |
|---|---|
the remote branch '<ref>' has commits this run does not have; nothing was landed | The binding's branch moved on the remote. The work branch may have been pushed; the branch is unchanged. |
a run lands only on a branch; '<ref>' is not one | The binding's ref is a tag or a commit. Refused before any push. |
this run holds no repository | The workflow execution holds no repository. |
Output: commit_sha (the work branch's HEAD, now the branch's), branch (the work branch), ref and branch_url (the host's page of the branch). The run's narrative records RepositoryLanded with the line "Landed <commit_sha> of repository <label> on <ref>"; it carries no credential.
Script Library Tools (aegis.script.*)
Persist and retrieve saved TypeScript programs in the caller's script library. Scripts are tenant-scoped; names are unique per tenant. Updates bump a monotonic version number and append to the script's version history. Deletes are soft — version history is retained for audit and the name reservation is released.
aegis.script.save
Persist a TypeScript program to the caller's script library.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Unique script name (≤128 bytes; no / or \). Duplicate names return 409. |
code | string | Yes | — | TypeScript program source (≤256 KiB). |
description | string | No | — | Optional free-form description (≤2 KiB). |
tags | array | No | — | Optional tags — lowercase alphanumeric plus - / _, ≤32 chars each, ≤16 tags. |
Output: The saved script DTO with its assigned id and version: 1.
aegis.script.list
List the caller's saved scripts with optional filters.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
tag | string | No | — | Filter scripts that contain this tag. |
q | string | No | — | Case-insensitive substring filter on script name. |
Output: Array of script DTOs (without the versions field).
aegis.script.get
Retrieve a saved script by ID, including its full version history.
Access: User
skip_judge: true
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | UUID of the saved script. |
Output: Script DTO with versions array. Returns 404 for scripts the caller does not own.
aegis.script.update
Update a saved script. Bumps the version monotonically and appends to the script's version history.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | UUID of the saved script. |
name | string | Yes | — | Script name (≤128 bytes). |
code | string | Yes | — | TypeScript program source (≤256 KiB). |
description | string | No | — | Optional free-form description. |
tags | array | No | — | Optional tags. |
Output: Updated script DTO with the new version number.
aegis.script.delete
aegis.script.delete is a soft delete — the name reservation is released and
new scripts may reuse the name, but the version history is retained for audit.
Soft-delete a saved script.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | UUID of the saved script. |
Output: Empty body on success.
Volume Management Tools (aegis.volume.*)
Create, list, and manage tenant-scoped persistent volumes. Volumes are backed by SeaweedFS and subject to per-tier quotas enforced by the orchestrator backend. Every call is authorized against the caller's bearer token — callers can only see and modify volumes they own.
aegis.volume.create
Provision a new persistent volume with a specified storage quota.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
label | string | Yes | — | Human-readable volume name. |
size_limit_bytes | integer | Yes | — | Storage quota in bytes. Must fall within the caller's tier quota. |
Output: The created volume DTO, including its volume_id.
aegis.volume.list
List all persistent volumes owned by the current user.
Access: User
skip_judge: true
No parameters — accepts an empty object {}.
Output: Array of volume DTOs.
aegis.volume.delete
Deleting a volume is destructive and irreversible. All files stored in the volume are removed.
Delete a persistent user volume and all of its contents.
Access: User
skip_judge: false
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
volume_id | string | Yes | — | UUID of the volume to delete. |
Output: Confirmation of deletion.
aegis.volume.quota
Get storage quota usage for the current user.
Access: User
skip_judge: true
No parameters — accepts an empty object {}.
Output: Quota summary — total bytes allowed by the caller's tier and bytes currently used across their volumes.
Zaru UI Tools
zaru.init, zaru.mode, zaru.docs, zaru.memory.get, and
zaru.memory.set are intercepted by the zaru-mcp-server and are never
forwarded to the AEGIS orchestrator. They are only available when using the
StreamableHTTP transport and are injected by the Zaru MCP server at the point
of tool advertisement.
zaru.init
Activate Zaru in any MCP client. Call this tool at the start of a session to retrieve the current mode, system prompt, available tools, and server version. Any MCP client (Claude Code, Claude Desktop, or the Zaru web UI) should call zaru.init on connection to bootstrap the session.
Access: User
skip_judge: N/A (never reaches the orchestrator)
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
mode | string | No | chat | The initial mode to activate. One of: chat, agentic, architect, operator, execute. |
Output:
{
"mode": "chat",
"system_prompt": "You are Zaru, a helpful AI assistant...",
"available_tools": ["zaru.init", "zaru.mode"],
"version": "0.8.0"
}zaru.mode
Switch to a different conversation mode. Use this when the user's request cannot be fulfilled in the current mode. In the Zaru web UI this renders a confirmation card inline in the chat — the user can accept, refuse, or dismiss. In headless MCP clients the mode switch is applied immediately.
Access: User
skip_judge: N/A (never reaches the orchestrator)
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
target_mode | string | Yes | — | The mode to switch to. One of: chat, agentic, architect, operator, execute. |
reason | string | Yes | — | Short, plain-language explanation for the user. One sentence. |
Output:
{
"action": "mode_switch_requested",
"target_mode": "agentic",
"reason": "This request requires running an agent."
}In the Zaru web UI, this response renders as an inline confirmation card. The user can accept, refuse, or dismiss the mode switch. In headless MCP clients (Claude Code, Claude Desktop), the mode switch is applied immediately and the response confirms the new mode.
zaru.docs
Search AEGIS and Zaru documentation. Results are fetched from docs.100monkeys.ai and cached for 5 minutes. Available in every conversation mode.
Access: User
skip_judge: N/A (never reaches the orchestrator)
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | — | What the user wants to know about AEGIS or Zaru. |
Output:
{
"query": "how to create an agent",
"sections": [
{
"title": "Creating Your First Agent",
"content": "To create an agent, define a manifest YAML...",
"url": "https://docs.100monkeys.ai/docs/guides/creating-agents"
}
],
"total_matches": 3
}Example call:
zaru.docs({ query: "how to create an agent" });zaru.docs is handled entirely by the zaru-mcp-server. It searches the
published documentation at docs.100monkeys.ai and returns matching sections
with titles, content excerpts, and direct URLs. Results are cached per query
for 5 minutes to reduce latency on repeated lookups.
zaru.memory.get
Read the caller's persistent memory blob. Memory is per-user, shared across all MCP clients connected as that user (Zaru Web, Claude Desktop, Windsurf, etc.), and auto-injected into the system prompt at session start. Available in every conversation mode.
Use mid-conversation primarily to obtain the current version before issuing zaru.memory.set, or to re-read after a 409 conflict.
Access: User
skip_judge: N/A (never reaches the orchestrator)
No parameters — accepts an empty object {}.
Output:
{
"content": "# User memory\n\n- Prefers concise answers...",
"version": 7,
"updated_at": "2026-04-28T14:32:11Z"
}When no memory has been written yet, returns { "content": "", "version": 0, "updated_at": "..." }.
zaru.memory.set
Persist a new memory state for the caller. Pass the full new markdown blob — not a diff or patch — together with the version returned by the most recent zaru.memory.get. On success the server increments the version and returns the new state. Available in every conversation mode.
Use to record user preferences, work-style cues, recurring projects, frustrations, or anything worth carrying into future conversations. Always zaru.memory.get first to obtain the current version. Keep memory concise and signal-rich — it is not a transcript log.
Access: User
skip_judge: N/A (never reaches the orchestrator)
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
content | string | Yes | — | The full new memory markdown blob. |
version | integer | Yes | — | The version returned by the previous zaru.memory.get call. |
Output:
{
"content": "# User memory\n\n- Prefers concise answers...\n- New project: zaru-edge",
"version": 8,
"updated_at": "2026-04-28T14:35:42Z"
}Conflict handling: if version does not match the server's current version, the call returns a structured conflict error containing the server's current { content, version, updated_at }. The model should merge the user's intended changes into the returned content and retry with the new version.
Edge Fleet Tools
System-tier tools for multi-host fleet operations against user-installed edge daemons. Gated by an operator/tenant-admin SecurityContext.
aegis.edge.fleet.invoke
Invoke any registered tool against an EdgeTarget with a FleetDispatchPolicy. Server-streamed: per-node CommandProgress chunks stream back tagged with node_id; the terminal payload is FleetExecutionResult.
Inputs:
| Field | Type | Description |
|---|---|---|
target | tagged-union | One of { Node: <id> }, { Group: <id> }, { Selector: {...} }, { All: null }. |
tool | string | Registered tool name. Must declare fleet_capable: true for multi-target dispatch. |
args | object | Tool-specific argument map. |
policy.mode | enum | { Sequential: null }, { Parallel: null }, or { Rolling: { batch: N } }. |
policy.max_concurrency | int? | Optional cap on concurrent in-flight dispatches. |
policy.failure_policy | enum | { FailFast: null }, { ContinueOnError: null }, or { StopAfter: N }. |
policy.require_min_targets | int? | Refuse upfront if fewer matches resolve. |
policy.per_target_deadline_secs | int | Propagated as EdgeCommand.deadline. Default 60. |
Outputs (streamed):
command_progressevents, one per chunk, tagged withnode_idandcommand_id.command_resultevents, one per terminal per-node outcome.- A terminal
fleet_resultpayload withfleet_command_id,targets_resolved,targets_skipped,per_node, andsummary { ok, err, timed_out, cancelled, not_started }.
aegis.edge.fleet.list
Resolve an EdgeTarget to a node list without dispatching.
Inputs:
| Field | Type | Description |
|---|---|---|
target | tagged-union | Same shape as aegis.edge.fleet.invoke. |
Outputs:
{
"resolved": [{ "node_id": "...", "name": "...", "status": "Connected" }],
"skipped": [{ "node_id": "...", "reason": "Disconnected" }]
}aegis.edge.fleet.cancel
Broadcast Cancel to every in-flight per-node command in a fleet operation.
Inputs:
| Field | Type | Description |
|---|---|---|
fleet_command_id | string | The id returned by aegis.edge.fleet.invoke. |
Outputs:
{
"fleet_command_id": "f-...",
"cancelled": 12,
"already_terminal": 5
}For the broader fleet model, see fleet operations.