Aegis Orchestrator
Reference

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.

ContextTool groups availableNotes
Zaru Chat — chat modezaru.* (init, mode, docs, memory.get, memory.set) onlyMode switching, docs search, memory; no orchestrator tools
Zaru Chat — agentic modezaru.* + agent/task management subsetSee mode table below
Zaru Chat — execute modezaru.* + execute pipeline toolsSee mode table below
Zaru Chat — workflow modezaru.* + workflow/agent design subsetSee mode table below; starts a workflow with aegis.workflow.run
Zaru Chat — operator modeAll toolsNo filtering applied; only under an operator escalation
AEGIS agent inner loopEvery built-in toolSubject to agent spec.tools allowlist and SecurityContext
External SEAL callerEvery built-in toolFiltered 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.init
  • zaru.mode
  • zaru.docs
  • zaru.memory.get
  • zaru.memory.set
  • zaru.schedule
  • zaru.conversations.list
  • zaru.conversations.read
  • zaru.conversations.search
  • aegis.agent.generate
  • aegis.agent.wait
  • aegis.agent.list
  • aegis.agent.search
  • aegis.agent.logs
  • aegis.workflow.search
  • aegis.workflow.run
  • aegis.git.list
  • aegis.workflow.wait
  • aegis.schedule.list
  • aegis.schedule.get
  • aegis.schedule.pause
  • aegis.schedule.resume
  • aegis.schedule.delete
  • aegis.schedule.runs
  • aegis.task.execute
  • aegis.task.wait
  • aegis.task.list
  • aegis.task.logs
  • aegis.task.cancel
  • aegis.execution.file
  • aegis.tools.list
  • aegis.tools.search
  • aegis.image.generate
  • aegis.goal.cancel

Execute Mode

  • zaru.init
  • zaru.mode
  • zaru.docs
  • zaru.memory.get
  • zaru.memory.set
  • zaru.schedule
  • zaru.conversations.list
  • zaru.conversations.read
  • zaru.conversations.search
  • aegis.execute.intent
  • aegis.execute.status
  • aegis.execute.wait
  • aegis.execution.file
  • aegis.image.generate
  • aegis.goal.cancel

Architect Mode

  • zaru.init
  • zaru.mode
  • zaru.docs
  • zaru.memory.get
  • zaru.memory.set
  • zaru.schedule
  • zaru.conversations.list
  • zaru.conversations.read
  • zaru.conversations.search
  • aegis.workflow.generate
  • aegis.workflow.list
  • aegis.workflow.logs
  • aegis.workflow.run
  • aegis.git.list
  • aegis.workflow.create
  • aegis.workflow.update
  • aegis.agent.generate
  • aegis.agent.wait
  • aegis.agent.list
  • aegis.agent.logs
  • aegis.schema.get
  • aegis.schema.validate
  • aegis.task.execute
  • aegis.task.wait
  • aegis.execution.file
  • aegis.workflow.wait
  • aegis.schedule.list
  • aegis.schedule.get
  • aegis.schedule.pause
  • aegis.schedule.resume
  • aegis.schedule.delete
  • aegis.schedule.runs
  • aegis.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.

ToolGroupskip_judgeRequired paramsZaru modes
cmd.rundispatchfalsecommandOp
fs.readfstruepathOp
fs.writefsfalsepath, contentOp
fs.listfstruepathOp
fs.create_dirfsfalsepathOp
fs.deletefsfalsepathOp
fs.editfsfalsepath, target_content, replacement_contentOp
fs.multi_editfsfalsepath, editsOp
fs.grepfstruepattern, pathOp
fs.globfstruepattern, pathOp
web.searchwebtruequeryOp
web.fetchwebtrueurlOp
aegis.schema.getschematruekeyAr, Op
aegis.schema.validateschematruekind, manifest_yamlAr, Op
aegis.agent.createagenttruemanifest_yamlOp
aegis.agent.listagenttrue—Ag, Ar, Op
aegis.agent.updateagenttruemanifest_yamlOp
aegis.agent.exportagenttruenameOp
aegis.agent.deleteagenttrueagent_idOp
aegis.agent.generateagentfalseinputAg, Ar, Op
aegis.agent.logsagenttrueagent_idAg, Ar, Op
aegis.agent.searchagenttruequeryAg, Op
aegis.agent.waitagenttrueexecution_idAg, Ar, Op
aegis.workflow.createworkflowtruemanifest_yamlAr, Op
aegis.workflow.listworkflowtrue—Ar, Op
aegis.workflow.validateworkflowtruemanifest_yamlOp
aegis.workflow.updateworkflowtruemanifest_yamlAr, Op
aegis.workflow.exportworkflowtruenameOp
aegis.workflow.deleteworkflowfalsenameOp
aegis.workflow.runworkflowfalsenameAg, Ar, Op
aegis.workflow.generateworkflowfalseinputAr, Op
aegis.workflow.logsworkflowtrueexecution_idAr, Op
aegis.workflow.waitworkflowtrueexecution_idAg, Ar, Op
aegis.workflow.cancelworkflowtrueexecution_idOp
aegis.workflow.signalworkflowtrueexecution_id, responsenone: external MCP clients
aegis.workflow.removeworkflowtrueexecution_idOp
aegis.workflow.promoteworkflowfalsenameOp
aegis.workflow.demoteworkflowfalsenameOp
aegis.workflow.executions.listworkflowtrue—Op
aegis.workflow.executions.getworkflowtrueexecution_idOp
aegis.workflow.statusworkflowtrueexecution_idOp
aegis.workflow.searchworkflowtruequeryAg, Op
aegis.task.executetaskfalseagent_idAg, Ar, Op
aegis.task.statustasktrueexecution_idOp
aegis.task.listtasktrue—Ag, Op
aegis.task.canceltaskfalseexecution_idAg, Op
aegis.task.removetaskfalseexecution_idOp
aegis.task.logstasktrueexecution_idAg, Op
aegis.task.waittasktrueexecution_idAg, Ar, Op
aegis.execution.fileexecutiontruepath; execution_id unless volume_idAg, Ex, Ar, Op
aegis.attachment.readattachmenttruevolume_id, pathSystem-tier only
aegis.image.generateimagefalsepromptAg, Ex
aegis.execute.intentexecutefalseintentEx, Op
aegis.execute.statusexecutetruepipeline_execution_idEx, Op
aegis.execute.waitexecutetrueexecution_idEx, Op
aegis.goal.creategoaltruestatement, client_ref, channelnone: called by Zaru Web's turn
aegis.goal.evaluategoaltruegoal_id, companion_answernone: called by Zaru Web's turn
aegis.goal.statusgoaltruegoal_idnone: called by Zaru Web's turn
aegis.goal.cancelgoaltruegoal_idAg, Ex, Ar, Op
aegis.schedule.createschedulefalsename, target_kind, targetOp
aegis.schedule.listscheduletrue—Ag, Ar, Op
aegis.schedule.getscheduletrueschedule_idAg, Ar, Op
aegis.schedule.updateschedulefalseschedule_idOp
aegis.schedule.pauseschedulefalseschedule_idAg, Ar, Op
aegis.schedule.resumeschedulefalseschedule_idAg, Ar, Op
aegis.schedule.run_nowschedulefalseschedule_idnone until a security context names it
aegis.schedule.deleteschedulefalseschedule_idAg, Ar, Op
aegis.schedule.runsscheduletrueschedule_idAg, Ar, Op
aegis.tools.listtoolstrue—Ag, Op
aegis.tools.searchtoolstrue—Ag, Op
aegis.system.infosystemtrue—Op
aegis.system.configsystemtrue—Op
aegis.runtime.listruntimetrue—Op
aegis.file.listfiletruevolume_id, pathOp
aegis.file.readfiletruevolume_id, pathOp
aegis.file.writefilefalsevolume_id, path, contentOp
aegis.file.deletefilefalsevolume_id, pathOp
aegis.file.mkdirfilefalsevolume_id, pathOp
aegis.volume.createvolumefalselabel, size_limit_bytesOp
aegis.volume.listvolumetrue—Op
aegis.volume.deletevolumefalsevolume_idOp
aegis.volume.quotavolumetrue—Op
aegis.git.clonegitfalserepo_url, labelOp
aegis.git.listgittrue—Ag, Ar, Op
aegis.git.statusgittruebinding_idOp
aegis.git.refreshgitfalsebinding_idOp
aegis.git.deletegitfalsebinding_idOp
aegis.git.commitgitfalsebinding_id, messageOp
aegis.git.pushgitfalsebinding_idOp
aegis.git.diffgittruebinding_idOp
aegis.git.landgitfalse—none: answered only for a workflow's landing step
aegis.script.savescriptfalsename, codeOp
aegis.script.listscripttrue—Op
aegis.script.getscripttrueidOp
aegis.script.updatescriptfalseid, name, codeOp
aegis.script.deletescriptfalseidOp
zaru.initzaruN/A—C, Ag, Ex, Ar, Op
zaru.modezaruN/Atarget_mode, reasonC, Ag, Ex, Ar, Op
zaru.docszaruN/AqueryC, Ag, Ex, Ar, Op
zaru.memory.getzaruN/A—C, Ag, Ex, Ar, Op
zaru.memory.setzaruN/Acontent, versionC, Ag, Ex, Ar, Op
zaru.schedulezaruN/Atarget_kind, target, intent, input, reasonC, Ag, Ex, Ar, Op
zaru.conversations.listzaruN/A—C, Ag, Ex, Ar, Op
zaru.conversations.readzaruN/Aconversation_idC, Ag, Ex, Ar, Op
zaru.conversations.searchzaruN/AqueryC, 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

PropertyTypeRequiredDefaultDescription
pathstringYes—Absolute or relative POSIX path of the file to read.
line_startintegerNo1First line to return, counted from 1, at least 1. Give line_start, line_end or both to read only those lines.
line_endintegerNothe last lineLast 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

PropertyTypeRequiredDefaultDescription
pathstringYes—Absolute or relative POSIX path of the file to write.
contentstringYes—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

PropertyTypeRequiredDefaultDescription
pathstringYes—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

PropertyTypeRequiredDefaultDescription
pathstringYes—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

PropertyTypeRequiredDefaultDescription
pathstringYes—Absolute or relative POSIX path of the file or directory to delete.
recursivebooleanNofalseSet 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

PropertyTypeRequiredDefaultDescription
pathstringYes—Absolute or relative POSIX path of the file to edit.
target_contentstringYes—Exact string content to find and replace. Must match exactly once in the file.
replacement_contentstringYes—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

PropertyTypeRequiredDefaultDescription
pathstringYes—Absolute or relative POSIX path of the file to edit.
editsarrayYes—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

PropertyTypeRequiredDefaultDescription
patternstringYes—Regex pattern to search for.
pathstringYes—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

PropertyTypeRequiredDefaultDescription
patternstringYes—Glob pattern to match files (e.g. **/*.rs).
pathstringYes—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

PropertyTypeRequiredDefaultDescription
querystringYes—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

PropertyTypeRequiredDefaultDescription
urlstringYes—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

PropertyTypeRequiredDefaultDescription
commandstringYes—Command to execute. The first token must appear in the agent's subcommand_allowlist.
argsarrayNo—Arguments passed to the command, as an array of strings, such as ["-c", "env"].
env_additionsobjectNo—Environment variables added for this command, as an object of string values.
stdinstringNo—Text written to the command's standard input, which is then closed; at most max_output_bytes bytes.
cwdstringNo/workspaceThe directory the command runs in, such as /workspace/app.
timeout_secsintegerNo600Seconds the command may run before it is stopped.
max_output_bytesintegerNo1048576The 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

PropertyTypeRequiredDefaultDescription
manifest_yamlstringYes—Full Agent manifest YAML to parse, validate, and deploy.
forcebooleanNofalseOverwrite 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

PropertyTypeRequiredDefaultDescription
manifest_yamlstringYes—Full Agent manifest YAML to update an existing agent.
forcebooleanNofalseOverwrite 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

PropertyTypeRequiredDefaultDescription
namestringYes—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

PropertyTypeRequiredDefaultDescription
agent_idstringYes—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

PropertyTypeRequiredDefaultDescription
inputstringYes—Natural-language intent for the agent to create.
attachmentsarrayNo—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.
repositoriesarrayNo—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

PropertyTypeRequiredDefaultDescription
agent_idstringYes—UUID of the agent whose activity log should be retrieved.
limitintegerNo50Maximum number of events to return.
offsetintegerNo0Zero-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

PropertyTypeRequiredDefaultDescription
querystringYes—Natural-language description of the agent you are looking for.
tenant_idstringNocurrent tenantTenant ID to search within.
limitintegerNo10Maximum results (1–100, tier-dependent cap).
min_scorenumberNo0.3Minimum relevance score threshold (0.0–1.0).
labelsobjectNo—Label key-value pairs to filter by. All must match.
statusstringNo—Filter by agent status. One of: active, paused, failed.
include_platform_templatesbooleanNotrueInclude 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the execution to wait for.
poll_interval_secondsintegerNo10Seconds between status polls (minimum: 1).
timeout_secondsintegerNo600Maximum 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

PropertyTypeRequiredDefaultDescription
manifest_yamlstringYes—Full Workflow manifest YAML to parse, validate, semantically judge, and register.
forcebooleanNofalseOverwrite an existing version if it already exists.
task_contextstringNo—Optional task context to guide semantic judges.
judge_agentsarrayNo—Judge agent names to use for semantic validation.
min_scorenumberNo—Minimum consensus score required for deployment.
min_confidencenumberNo—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

PropertyTypeRequiredDefaultDescription
tenant_idstringNolocal tenantOptional tenant identifier.
scopestringNo—Scope filter. One of: global (global workflows only), visible (user + tenant + global). Omit to list all for the tenant.
user_idstringNo—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

PropertyTypeRequiredDefaultDescription
manifest_yamlstringYes—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

PropertyTypeRequiredDefaultDescription
manifest_yamlstringYes—Full Workflow manifest YAML to update an existing workflow.
forcebooleanNofalseOverwrite 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

PropertyTypeRequiredDefaultDescription
namestringYes—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

PropertyTypeRequiredDefaultDescription
namestringYes—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

PropertyTypeRequiredDefaultDescription
namestringYes—Name of the workflow to execute.
intentstringNo—Natural-language description of the goal for this run. Injected into workflow input and available to agentic states and task activities.
inputobjectNo—Workflow input parameters.
blackboardobjectNo—Optional blackboard overrides merged into the execution before startup.
versionstringNolatestSemantic version of the workflow to execute. When omitted, the latest deployed version is used.
tenant_idstringNolocal tenantOptional tenant identifier.
attachmentsarrayNo—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).
repositoriesarrayNo—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

PropertyTypeRequiredDefaultDescription
inputstringYes—Natural-language workflow objective.
repositoriesarrayNo—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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—The id aegis.workflow.run answered for the run.
limitintegerNo50Maximum number of events to return, in sequence order (max 200; a larger value returns 200).
offsetintegerNo0Number 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the workflow execution to wait for.
poll_interval_secondsintegerNo5Seconds between polls.
timeout_secondsintegerNo300Maximum 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the workflow execution to signal.
responsestringYes—Human input response text to send to the paused workflow.
feedbackstringNo—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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—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

PropertyTypeRequiredDefaultDescription
namestringYes—Workflow name or ID to promote.
target_scopestringNoglobalTarget scope. One of: tenant, global.
tenant_idstringNolocal tenantOptional 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

PropertyTypeRequiredDefaultDescription
namestringYes—Workflow name or ID to demote.
target_scopestringNotenantTarget scope. One of: tenant, user.
user_idstringNo—Owner user ID when demoting to user scope.
tenant_idstringNolocal tenantOptional 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

PropertyTypeRequiredDefaultDescription
limitintegerNo20Maximum number of results to return.
offsetintegerNo0Pagination offset.
workflow_idstringNo—Optional workflow UUID or workflow name filter.
tenant_idstringNolocal tenantOptional 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the workflow execution to inspect.
tenant_idstringNolocal tenantOptional 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the workflow execution to inspect.
tenant_idstringNolocal tenantOptional 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

PropertyTypeRequiredDefaultDescription
querystringYes—Natural-language description of the workflow you are looking for.
tenant_idstringNocurrent tenantTenant ID to search within.
limitintegerNo10Maximum results (1–100, tier-dependent cap).
min_scorenumberNo0.3Minimum relevance score threshold (0.0–1.0).
labelsobjectNo—Label key-value pairs to filter by. All must match.
include_platform_templatesbooleanNotrueInclude 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

PropertyTypeRequiredDefaultDescription
agent_idstringYes—UUID or name of the agent to execute.
intentstringNo—Natural-language description of what the agent should accomplish. Steers the LLM prompt directly. Complementary to structured input.
inputobjectNo—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.
attachmentsarrayNo—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.
versionstringNolatestSemantic version of the agent to execute. When omitted, the latest deployed version is used.
repositoriesarrayNo—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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—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

PropertyTypeRequiredDefaultDescription
agent_idstringNo—Optional UUID to filter executions by agent.
limitintegerNo20Maximum 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the execution whose event log should be retrieved.
limitintegerNo50Maximum number of events to return (capped at 200).
offsetintegerNo0Zero-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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the execution to wait for.
poll_interval_secondsintegerNo10Seconds between status polls (minimum: 1).
timeout_secondsintegerNo600Maximum 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

PropertyTypeRequiredDefaultDescription
execution_idstringUnless volume_id is given—The execution ID to retrieve a file from.
volume_idstringNo—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.
pathstringYes—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:

FieldTypeDescription
statusstringsuccess.
pathstringThe path as the call gave it.
contentstringFile contents as text. Present only for text files.
content_typestringMIME type of the file (e.g. text/plain, image/png, application/pdf).
is_binarybooleantrue if the file is binary, false for text files.
download_urlstringThe path of GET /v1/executions/{id}/files/{path} for this file, with ?volume_id=<id> when the call named a volume.
volume_idstringThe volume read. Present only when the call named one.
size_bytesnumberSize 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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—UUID of the volume containing the attachment. Typically the volume_id of an AttachmentRef from the dispatch's attachments array.
pathstringYes—Path inside the volume. Typically the path of an AttachmentRef from the dispatch's attachments array.

Output schema:

FieldTypeDescription
contentstringFile contents, base64-encoded.
mime_typestringMIME type detected by content-sniffing.
sizeintegerSize of the file in bytes.
sha256stringHex-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

PropertyTypeRequiredDefaultDescription
promptstringYes—What the image shows.
aliasstringNothe node's first image generation aliasWhich of the node's image generation models.
sizestringNothe model's defaultThe 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.
countintegerNo1How 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

PropertyTypeRequiredDefaultDescription
intentstringYes—Natural-language description of what to execute (e.g. "resize images in /workspace to 800x600").
inputsobjectNo—Optional structured inputs passed to the pipeline.
attachmentsarrayNo—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_idstringNoephemeralOptional persistent volume ID to use as workspace. When omitted, an ephemeral volume is created.
languagestringNopythonExecution language. One of: python, javascript, bash.
timeout_secondsintegerNo—Optional execution timeout in seconds.
tenant_idstringNolocal tenantOptional tenant identifier.
repositoriesarrayNo—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

PropertyTypeRequiredDefaultDescription
pipeline_execution_idstringYes—UUID of the pipeline execution to check.
tenant_idstringNolocal tenantOptional 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

PropertyTypeRequiredDefaultDescription
execution_idstringYes—UUID of the workflow/pipeline execution to wait for. Pass the pipeline_execution_id from aegis.execute.intent.
poll_interval_secondsintegerNo5Seconds between polls.
timeout_secondsintegerNo300Maximum 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

PropertyTypeRequiredDefaultDescription
statementstringYes—The user's request, verbatim; not empty, at most 32,768 characters.
client_refstringYes—The caller's opaque reference, for Zaru Web the conversation id; not empty.
channelstringYes—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

PropertyTypeRequiredDefaultDescription
goal_idstringYes—The goal.
companion_answerstringYes—The text the user was shown in the turn just ended; read to 8,192 characters.
roundintegerNo0Absent 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_met verdict while an execution started for the goal by aegis.agent.generate or aegis.task.execute waits on an approval answers waiting_on: "approval" with approval_ids and continue: 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_seconds closes expired. 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_met with score and confidence 0 and the fault as its reasoning.
  • A judge that cannot be started, for example because goal-judge is not deployed, is refused goal_judge_unavailable.

aegis.goal.status

Returns the goal, its bound executions and every verdict. Read-only.

Access: User

skip_judge: true

PropertyTypeRequiredDefaultDescription
goal_idstringYes—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

PropertyTypeRequiredDefaultDescription
goal_idstringYes—The goal.
reasonstringNoThe 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

PropertyTypeRequiredDefaultDescription
querystringNo—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

PropertyTypeRequiredDefaultDescription
keystringYes—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

PropertyTypeRequiredDefaultDescription
kindstringYes—Manifest kind to validate against. Supported values: "agent", "workflow".
manifest_yamlstringYes—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

PropertyTypeRequiredDefaultDescription
languagestringNo—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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—UUID of the target volume.
pathstringYes—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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—UUID of the target volume.
pathstringYes—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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—UUID of the target volume.
pathstringYes—File path relative to the volume root.
contentstringYes—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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—UUID of the target volume.
pathstringYes—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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—UUID of the target volume.
pathstringYes—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

PropertyTypeRequiredDefaultDescription
repo_urlstringYes—Repository URL (https://... or git@...).
labelstringYes—Human-readable binding name; the clone is mounted at /workspace/{label}.
credential_binding_idstringNo—UUID of a credential binding (SSH key or API key) for private repos.
git_refobjectNo{ kind: "branch", value: "main" }Git ref to check out. Fields: kind (branch / tag / commit) and value.
sparse_pathsarrayNo—Optional list of sparse-checkout paths.
auto_refreshbooleanNofalseEnable webhook-driven auto-refresh.
shallowbooleanNotruePerform 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

PropertyTypeRequiredDefaultDescription
repositorystringNo—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_idstringNo—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

PropertyTypeRequiredDefaultDescription
binding_idstringYes—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

PropertyTypeRequiredDefaultDescription
binding_idstringYes—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

PropertyTypeRequiredDefaultDescription
repositorystringNo—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_idstringNo—Outside a run: the id of one of your git repository bindings. Never read inside a run.
messagestringYes—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

PropertyTypeRequiredDefaultDescription
repositorystringNo—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_idstringNo—Outside a run: the id of one of your git repository bindings. Never read inside a run.
remotestringNooriginRemote name.
refstringNocurrent branchRef 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

PropertyTypeRequiredDefaultDescription
repositorystringNo—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_idstringNo—Outside a run: the id of one of your git repository bindings. Never read inside a run.
stagedbooleanNofalseIf 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.

RefusalWhen
the remote branch '<ref>' has commits this run does not have; nothing was landedThe 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 oneThe binding's ref is a tag or a commit. Refused before any push.
this run holds no repositoryThe 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

PropertyTypeRequiredDefaultDescription
namestringYes—Unique script name (≤128 bytes; no / or \). Duplicate names return 409.
codestringYes—TypeScript program source (≤256 KiB).
descriptionstringNo—Optional free-form description (≤2 KiB).
tagsarrayNo—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

PropertyTypeRequiredDefaultDescription
tagstringNo—Filter scripts that contain this tag.
qstringNo—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

PropertyTypeRequiredDefaultDescription
idstringYes—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

PropertyTypeRequiredDefaultDescription
idstringYes—UUID of the saved script.
namestringYes—Script name (≤128 bytes).
codestringYes—TypeScript program source (≤256 KiB).
descriptionstringNo—Optional free-form description.
tagsarrayNo—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

PropertyTypeRequiredDefaultDescription
idstringYes—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

PropertyTypeRequiredDefaultDescription
labelstringYes—Human-readable volume name.
size_limit_bytesintegerYes—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

PropertyTypeRequiredDefaultDescription
volume_idstringYes—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)

PropertyTypeRequiredDefaultDescription
modestringNochatThe 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)

PropertyTypeRequiredDefaultDescription
target_modestringYes—The mode to switch to. One of: chat, agentic, architect, operator, execute.
reasonstringYes—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)

PropertyTypeRequiredDefaultDescription
querystringYes—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)

PropertyTypeRequiredDefaultDescription
contentstringYes—The full new memory markdown blob.
versionintegerYes—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:

FieldTypeDescription
targettagged-unionOne of { Node: <id> }, { Group: <id> }, { Selector: {...} }, { All: null }.
toolstringRegistered tool name. Must declare fleet_capable: true for multi-target dispatch.
argsobjectTool-specific argument map.
policy.modeenum{ Sequential: null }, { Parallel: null }, or { Rolling: { batch: N } }.
policy.max_concurrencyint?Optional cap on concurrent in-flight dispatches.
policy.failure_policyenum{ FailFast: null }, { ContinueOnError: null }, or { StopAfter: N }.
policy.require_min_targetsint?Refuse upfront if fewer matches resolve.
policy.per_target_deadline_secsintPropagated as EdgeCommand.deadline. Default 60.

Outputs (streamed):

  • command_progress events, one per chunk, tagged with node_id and command_id.
  • command_result events, one per terminal per-node outcome.
  • A terminal fleet_result payload with fleet_command_id, targets_resolved, targets_skipped, per_node, and summary { ok, err, timed_out, cancelled, not_started }.

aegis.edge.fleet.list

Resolve an EdgeTarget to a node list without dispatching.

Inputs:

FieldTypeDescription
targettagged-unionSame 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:

FieldTypeDescription
fleet_command_idstringThe 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.

On this page

Tool Access TiersTool Availability by ContextZaru Conversation Mode Tool SetsChat ModeAgentic ModeExecute ModeArchitect ModeOperator ModeQuick-Reference TableFilesystem Tools (fs.*)fs.readfs.writefs.listfs.create_dirfs.deletefs.editfs.multi_editfs.grepfs.globWeb Tools (web.*)web.searchweb.fetchDispatch Protocol Tool (cmd.run)cmd.runAgent Management Tools (aegis.agent.*)aegis.agent.createaegis.agent.listaegis.agent.updateaegis.agent.exportaegis.agent.deleteaegis.agent.generateaegis.agent.logsaegis.agent.searchaegis.agent.waitWorkflow Management Tools (aegis.workflow.*)aegis.workflow.createaegis.workflow.listaegis.workflow.validateaegis.workflow.updateaegis.workflow.exportaegis.workflow.deleteaegis.workflow.runaegis.workflow.generateaegis.workflow.logsaegis.workflow.waitaegis.workflow.cancelaegis.workflow.signalaegis.workflow.removeaegis.workflow.promoteaegis.workflow.demoteaegis.workflow.executions.listaegis.workflow.executions.getaegis.workflow.statusaegis.workflow.searchTask Management Tools (aegis.task.*)aegis.task.executeaegis.task.statusaegis.task.listaegis.task.cancelaegis.task.removeaegis.task.logsaegis.task.waitaegis.execution.fileAttachment Tools (aegis.attachment.*)aegis.attachment.readImage Generation Tool (aegis.image.generate)aegis.image.generateExecute Pipeline Tools (aegis.execute.*)aegis.execute.intentaegis.execute.statusaegis.execute.waitGoal Tools (aegis.goal.*)aegis.goal.createaegis.goal.evaluateaegis.goal.statusaegis.goal.cancelTool Discovery (aegis.tools.*)aegis.tools.listaegis.tools.searchSystem Tools (aegis.system.*)aegis.system.infoaegis.system.configSchema Tools (aegis.schema.*)aegis.schema.getaegis.schema.validateRuntime Discovery (aegis.runtime.*)aegis.runtime.listVolume Filesystem Tools (aegis.file.*)aegis.file.listaegis.file.readaegis.file.writeaegis.file.deleteaegis.file.mkdirGit Repository Tools (aegis.git.*)aegis.git.cloneaegis.git.listaegis.git.statusaegis.git.refreshaegis.git.deleteaegis.git.commitaegis.git.pushaegis.git.diffaegis.git.landScript Library Tools (aegis.script.*)aegis.script.saveaegis.script.listaegis.script.getaegis.script.updateaegis.script.deleteVolume Management Tools (aegis.volume.*)aegis.volume.createaegis.volume.listaegis.volume.deleteaegis.volume.quotaZaru UI Toolszaru.initzaru.modezaru.docszaru.memory.getzaru.memory.setEdge Fleet Toolsaegis.edge.fleet.invokeaegis.edge.fleet.listaegis.edge.fleet.cancel