Management Tools

AEGIS provides a suite of built-in management tools under the aegis.* namespace. These tools enable agents and external clients to perform full CRUD (Create, Read, Update, Delete) operations on agent and workflow definitions directly through the Model Context Protocol (MCP).

Unlike execution tools (like fs.* or cmd.run), management tools interact directly with the Orchestrator's internal registry and services.

These are MCP tool names, not shell commands. For the terminal CLI, use the separate CLI Reference.

The workflow management surface currently exposed through MCP is aegis.workflow.list, aegis.workflow.search, aegis.workflow.validate, aegis.workflow.create, aegis.workflow.update, aegis.workflow.export, aegis.workflow.delete, aegis.workflow.run, aegis.workflow.wait, aegis.workflow.status, aegis.workflow.executions.list, aegis.workflow.executions.get, aegis.workflow.generate, aegis.workflow.logs, aegis.workflow.cancel, aegis.workflow.signal, and aegis.workflow.remove. The task management surface includes aegis.task.execute, aegis.task.status, aegis.task.wait, aegis.task.list, aegis.task.logs, aegis.task.cancel, and aegis.task.remove. The execute surface includes aegis.execute.intent and aegis.execute.status for the intent-to-execution pipeline. The agent management surface also includes aegis.agent.search for semantic search, aegis.agent.logs for retrieving agent-level activity logs, and aegis.agent.wait (alias for aegis.task.wait) for blocking until an agent execution completes. The tool discovery surface includes aegis.tools.list and aegis.tools.search for programmatic enumeration and search of the available tool catalog. The runtime discovery surface includes aegis.runtime.list for enumerating the valid entries in the StandardRuntimeRegistry — agents that create or update manifests should call this tool before writing spec.runtime fields.

Versioning and Safety

All creation and update tools in the management suite respect AEGIS's strict versioning policy. By default, attempting to overwrite an existing name and version pair will be rejected.

• force parameter: Most mutating tools include an optional force boolean. Set this to true to explicitly overwrite an existing definition.
• Recommendations: It is generally recommended to increment the version in the manifest rather than using force, ensuring a clear audit trail.

Agent Management Tools

aegis.agent.create

Deploys a new agent to the orchestrator registry.

Returns: A JSON object confirming deployment, including the assigned agent_id and deployed: true.

aegis.agent.update

Updates an existing agent's definition.

Returns: Confirmation of the update and the agent_id.

aegis.agent.export

Retrieves the raw YAML manifest of a deployed agent.

Returns: A JSON object containing manifest_yaml (string) and agent metadata.

aegis.agent.delete

Permanently removes an agent from the registry. Cannot be undone.

Returns: A JSON object confirming deletion with agent_id and deleted: true.

aegis.agent.generate

Launches a natural language authoring loop that produces and deploys a new agent manifest from a plain-English description.

Returns: An object containing execution_id and status: "started". Stream the execution for real-time manifest generation output.

aegis.agent.list

Lists all currently deployed agents in the registry.

Parameters: None.

Returns: A list of agent summaries including id, name, version, status, and labels.

aegis.agent.search

Performs semantic search over deployed agents, returning results ranked by relevance to a natural-language query. Requires a Cortex connection (included in Zaru SaaS). If Cortex is not configured, calls return an error.

Returns:

{
  "tool": "aegis.agent.search",
  "query": "review pull requests for security issues",
  "results": [
    {
      "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "name": "security-reviewer",
      "version": "1.2.0",
      "description": "Reviews code changes for security vulnerabilities and best practices.",
      "labels": { "team": "security", "category": "review" },
      "score": 0.91
    }
  ],
  "total": 1
}

Errors: Returns an error with "Cortex not configured" if the node does not have a Cortex connection configured.

aegis.agent.logs

Retrieves agent-level activity logs, returning deployment events, execution summaries, and lifecycle transitions in reverse chronological order. This is a read-only query — skip_judge defaults to true.

Returns:

{
  "tool": "aegis.agent.logs",
  "agent_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "events": [
    {
      "event_type": "AgentDeployed",
      "payload": { "version": "1.0.0", "deployed_at": "2026-03-14T10:00:00Z" },
      "recorded_at": "2026-03-14T10:00:00Z"
    },
    {
      "event_type": "ExecutionCompleted",
      "payload": { "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "status": "completed" },
      "recorded_at": "2026-03-14T11:00:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Related CLI command:

aegis agent logs <agent_id>
aegis agent logs <agent_id> --follow        # stream events live

aegis.agent.wait

Alias for aegis.task.wait. Blocks server-side until an agent execution reaches a terminal state. Use after aegis.agent.generate to wait for the generation to complete.

Parameters:

Returns: Same shape as aegis.task.wait — guaranteed to be in a terminal state (completed, failed, cancelled) or timed_out. Includes status, iteration_count, last_output, last_error, started_at, and ended_at.

Workflow Management Tools

aegis.workflow.create

Performs strict deterministic and semantic validation on a workflow before registering it. This is the preferred way to deploy complex workflows.

This is the MCP equivalent of aegis workflow deploy; set force: true when you intentionally want to overwrite an existing workflow with the same name and version.

Returns: Detailed validation results from each judge and the final registration status, including workflow_id and deployed: true.

aegis.workflow.update

Updates an existing workflow definition.

Returns: Confirmation of the update and the workflow_id.

aegis.workflow.export

Retrieves the raw YAML manifest of a registered workflow.

Returns: A JSON object containing manifest_yaml (string) and workflow metadata.

aegis.workflow.delete

Permanently removes a workflow from the registry. Cannot be undone.

Returns: A JSON object confirming deletion with workflow_id and deleted: true.

aegis.workflow.run

Executes a registered workflow by name, passing an optional input payload to the initial blackboard state.

Returns: An object containing execution_id and status: "started".

aegis.workflow.validate

Parses and deterministically validates a workflow manifest before registration.

Returns: A JSON object with valid, deterministic validation details, and basic workflow metadata when parsing succeeds.

aegis.workflow.executions.list

Lists workflow executions for the current tenant, optionally filtered to a single workflow.

Returns: A paginated list of execution summaries including execution_id, workflow_id, status, current_state, and timestamps.

aegis.workflow.executions.get

Fetches a single workflow execution with its current status and persisted execution context.

Returns: A workflow execution object including status, input, blackboard, state_outputs, and timestamps.

This is the structured execution-detail alias for aegis.workflow.status.

aegis.workflow.generate

Launches a natural language authoring loop that produces and deploys a new workflow manifest from a plain-English objective.

Returns: An object containing execution_id and status: "started". Stream the execution to observe the iterative manifest generation loop.

aegis.workflow.logs

Retrieves the execution event log for a workflow run, returning state transitions, iteration results, and lifecycle events in chronological order. This is a read-only query — skip_judge defaults to true.

Parameters:

Returns:

{
  "tool": "aegis.workflow.logs",
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "completed",
  "events": [
    {
      "sequence": 1,
      "event_type": "WorkflowExecutionStarted",
      "state_name": null,
      "iteration_number": null,
      "payload": { "workflow_id": "my-workflow", "started_at": "2026-03-14T10:00:00Z" },
      "recorded_at": "2026-03-14T10:00:00Z"
    },
    {
      "sequence": 2,
      "event_type": "WorkflowStateEntered",
      "state_name": "analyze",
      "iteration_number": null,
      "payload": { "entered_at": "2026-03-14T10:00:01Z" },
      "recorded_at": "2026-03-14T10:00:01Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Related CLI command:

aegis workflow logs <execution_id>
aegis workflow logs <execution_id> --follow        # stream events live
aegis workflow logs <execution_id> --transitions   # state entries/exits only
aegis workflow logs <execution_id> --verbose       # include resolved workflow metadata
aegis workflow executions get <execution_id>
aegis workflow signal <execution_id> --response approved

aegis.workflow.cancel

Gracefully cancels a running workflow execution. The workflow engine will stop processing further states and mark the execution as cancelled.

Returns:

{
  "tool": "aegis.workflow.cancel",
  "cancelled": true,
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

On failure:

{
  "tool": "aegis.workflow.cancel",
  "cancelled": false,
  "error": "execution not found or already in terminal state"
}

aegis.workflow.wait

Blocks server-side until a workflow execution reaches a terminal state (completed, failed, or cancelled) and returns the final result. This is the workflow equivalent of aegis.task.wait.

Returns on completion:

{
  "execution_id": "...",
  "workflow_id": "...",
  "status": "completed",
  "current_state": "FORMAT_RESULT",
  "blackboard": { "final_result": "..." },
  "started_at": "...",
  "last_transition_at": "..."
}

Returns on timeout:

{
  "execution_id": "...",
  "status": "running",
  "current_state": "GENERATE_CODE",
  "timed_out": true
}

aegis.execute.wait is an alias for aegis.workflow.wait, available for use in Execute mode.

aegis.workflow.signal

Sends human input to a workflow execution that is paused at a human_input state. The workflow engine resumes execution with the provided response placed on the blackboard.

Returns:

{
  "tool": "aegis.workflow.signal",
  "signalled": true,
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

On failure:

{
  "tool": "aegis.workflow.signal",
  "signalled": false,
  "error": "execution is not in a waiting_for_human_input state"
}

aegis.workflow.remove

Deletes a workflow execution record from the registry. The execution must be in a terminal state (completed, failed, or cancelled).

Returns:

{
  "tool": "aegis.workflow.remove",
  "removed": true,
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

On failure:

{
  "tool": "aegis.workflow.remove",
  "removed": false,
  "error": "execution not found or still in progress"
}

aegis.workflow.list

Lists all currently registered workflows.

Returns: A list of workflow summaries including id, name, version, and initial_state.

aegis.workflow.search

Performs semantic search over registered workflows, returning results ranked by relevance to a natural-language query. Requires a Cortex connection (included in Zaru SaaS). If Cortex is not configured, calls return an error.

Returns:

{
  "tool": "aegis.workflow.search",
  "query": "deploy Node.js to Kubernetes",
  "results": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
      "name": "nodejs-k8s-deploy",
      "version": "2.0.0",
      "description": "Builds, tests, and deploys a Node.js application to a Kubernetes cluster.",
      "labels": { "category": "deployment", "runtime": "nodejs" },
      "score": 0.88
    }
  ],
  "total": 1
}

Errors: Returns an error with "Cortex not configured" if the node does not have a Cortex connection configured.

aegis.workflow.status

Returns the current status of a workflow execution — a lightweight status snapshot. Prefer aegis.workflow.executions.get when you need the full execution context including blackboard and state outputs.

Returns:

{
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "workflow_id": "my-workflow",
  "status": "running",
  "current_state": "ANALYZE",
  "started_at": "2026-03-14T10:00:00Z",
  "last_transition_at": "2026-03-14T10:00:05Z"
}

Related CLI command:

aegis workflow status <execution_id>

aegis.workflow.promote

Promotes a workflow to a broader visibility scope. A workflow at user scope can be promoted to tenant; a tenant-scoped workflow can be promoted to global. Requires operator or tenant-admin capabilities.

Returns:

{
  "workflow_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "nodejs-k8s-deploy",
  "promoted": true,
  "target_scope": "global"
}

aegis.workflow.demote

Demotes a workflow to a narrower visibility scope. A global workflow can be demoted to tenant; a tenant workflow can be demoted to user. Requires operator or tenant-admin capabilities.

Returns:

{
  "workflow_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "nodejs-k8s-deploy",
  "demoted": true,
  "target_scope": "tenant"
}

Task Management Tools

Task management tools provide direct control over agent execution lifecycle — launching, monitoring, and terminating individual runs.

aegis.task.execute

Executes a deployed agent by ID, optionally passing an input payload.

Returns: An object containing execution_id and status: "started".

aegis.task.status

Checks the current status and progress of a running or completed execution.

Returns: A status object including status (pending | running | completed | failed | cancelled), iteration_count, last_output, last_error, started_at, and ended_at.

aegis.task.wait

Blocks until an execution reaches a terminal state (completed, failed, or cancelled). Polls internally every poll_interval_seconds (default 10) up to timeout_seconds (default 300). Returns the final execution status, output, and error (if any). Use this instead of repeatedly calling aegis.task.status for async operations like aegis.agent.generate, aegis.workflow.generate, or aegis.task.execute.

Returns: Same shape as aegis.task.status but guaranteed to be in a terminal state (completed, failed, cancelled) or timed_out. Includes status, iteration_count, last_output, last_error, started_at, and ended_at.

aegis.task.list

Lists recent task executions, optionally filtered by agent.

Returns: A list of execution summaries including id, agent_id, status, and started_at.

aegis.task.logs

Retrieves the execution event log for an agent task, returning chronological execution events. This is a read-only query, so skip_judge defaults to true.

Returns:

{
  "tool": "aegis.task.logs",
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "completed",
  "events": [
    {
      "sequence": 1,
      "event_type": "ExecutionStarted",
      "payload": { "agent_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "started_at": "2026-03-14T10:00:00Z" },
      "recorded_at": "2026-03-14T10:00:00Z"
    },
    {
      "sequence": 2,
      "event_type": "ExecutionOutputReceived",
      "payload": { "chunk": "..." },
      "recorded_at": "2026-03-14T10:00:01Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Related CLI command:

aegis task logs <execution_id>
aegis task logs <execution_id> --follow        # stream events live

aegis.task.cancel

Gracefully stops a running execution.

Returns: A JSON object confirming cancellation with execution_id and cancelled: true.

aegis.task.remove

Deletes an execution record from the registry. The execution must be in a terminal state (completed, failed, or cancelled).

Returns: A JSON object confirming removal with execution_id and removed: true.

Tool Discovery

Tool discovery tools allow agents and external clients to programmatically enumerate and search the available MCP tool surface on the current node. Results are filtered by the caller's SecurityContext, so different tiers see different tool sets.

aegis.tools.list

Returns the full list of tools available to the caller, including both built-in dispatchers and external MCP server capabilities. The response is filtered by the caller's security context.

Parameters: None.

Returns:

{
  "tool": "aegis.tools.list",
  "tools": [
    {
      "name": "fs.read",
      "description": "Read file contents",
      "source": "builtin",
      "skip_judge": true
    },
    {
      "name": "aegis.agent.create",
      "description": "Deploy a new agent to the orchestrator registry",
      "source": "builtin",
      "skip_judge": false
    }
  ],
  "total": 42
}

Each entry includes:

aegis.tools.search

Searches the available tool surface by keyword, returning tools whose name or description matches the query. Like aegis.tools.list, results are filtered by the caller's security context.

Returns:

{
  "tool": "aegis.tools.search",
  "query": "workflow",
  "tools": [
    {
      "name": "aegis.workflow.create",
      "description": "Deploy a new workflow to the orchestrator registry",
      "source": "builtin",
      "skip_judge": false
    },
    {
      "name": "aegis.workflow.run",
      "description": "Execute a registered workflow by name",
      "source": "builtin",
      "skip_judge": false
    }
  ],
  "total": 2
}

Example usage: An agent that needs to discover what tools are available before deciding on a plan can call aegis.tools.search with a domain keyword (e.g. "filesystem", "workflow", "agent") to get a focused subset of the tool surface.

Execute Tools

These tools power the Execute conversation mode, providing a streamlined path from natural language intent to code execution.

aegis.execute.intent

Starts the intent-to-execution pipeline. Takes a natural language description of what to compute, discovers or generates an appropriate code-writing agent, generates code, executes it in an isolated container, and returns the formatted result.

Returns: { pipeline_execution_id, status: "started", stream_url }

aegis.execute.status

Returns the current status of an intent-to-execution pipeline run.

Returns:

• Running: { status: "running" }
• Completed: { status: "completed", final_result, duration_ms, reused_existing_agent }
• Failed: { status: "failed", reason, failed_at_state }

aegis.execute.wait

Alias for aegis.workflow.wait. Blocks server-side until the pipeline execution reaches a terminal state. Use the pipeline_execution_id returned by aegis.execute.intent as the execution_id parameter.

Returns the same shape as aegis.workflow.wait — a completed execution with final_result, or a timed_out indicator.

System Management Tools

System tools provide read-only introspection into the AEGIS node's status and active configuration.

aegis.system.info

Returns AEGIS node metadata, health status, software version, and the list of available capabilities and enabled built-in tools.

Parameters: None.

Returns: A JSON object containing version, status (healthy | unhealthy), and capabilities (array of enabled tool names).

aegis.system.config

Returns the full contents of the active node-config.yaml, including LLM provider settings, runtime configuration, and tool/MCP server registrations as read at daemon startup.

Parameters: None.

Returns: A JSON object containing config_path (absolute path to the loaded config file) and content_yaml (the raw YAML string).

Schema Tools

These tools provide access to the canonical JSON Schemas used by AEGIS for manifest validation.

aegis.schema.get

Retrieves the JSON Schema for a specific manifest type.

Returns: The full JSON Schema object for the requested manifest type.

aegis.schema.validate

Validates a manifest YAML string against its canonical schema without deploying it.

Returns: A JSON object with valid (boolean) and an optional errors array listing any validation failures.

Runtime Discovery

aegis.runtime.list

Returns all supported standard runtime environments from the StandardRuntimeRegistry. Use this tool before setting spec.runtime in an agent manifest to ensure the target language and version combination is valid and not deprecated. Available in the aegis-system-agent-runtime security context — no additional configuration required.

This tool is read-only; skip_judge defaults to true.

Returns:

{
  "tool": "aegis.runtime.list",
  "runtimes": [
    {
      "language": "python",
      "version": "3.11",
      "image": "python:3.11-slim",
      "description": "Python 3.11 with slim Debian base",
      "deprecated": false
    },
    {
      "language": "python",
      "version": "3.9",
      "image": "python:3.9-slim",
      "description": "Python 3.9 with slim Debian base",
      "deprecated": true
    },
    {
      "language": "go",
      "version": "1.21",
      "image": "golang:1.21-alpine",
      "description": "Go 1.21 with Alpine base",
      "deprecated": false
    }
  ],
  "custom_runtime_supported": true
}

Each entry in runtimes includes:

The top-level custom_runtime_supported field indicates whether the node accepts spec.runtime.image (CustomRuntime) as an alternative to StandardRuntime.

Example — filter by language:

{ "language": "python" }

{
  "tool": "aegis.runtime.list",
  "runtimes": [
    { "language": "python", "version": "3.11", "image": "python:3.11-slim", "description": "Python 3.11 with slim Debian base", "deprecated": false },
    { "language": "python", "version": "3.10", "image": "python:3.10-slim", "description": "Python 3.10 with slim Debian base", "deprecated": false },
    { "language": "python", "version": "3.9",  "image": "python:3.9-slim",  "description": "Python 3.9 with slim Debian base",  "deprecated": true  }
  ],
  "custom_runtime_supported": true
}

Usage pattern for agent-creator agents: Before writing or updating a manifest that includes spec.runtime, call aegis.runtime.list (optionally filtered by the target language) to confirm the intended language+version pair exists and is not deprecated. Specifying an unrecognized combination is rejected at execution validation time with no fallback.

See the Standard Runtime Registry for the full runtime matrix, lifecycle status, and pre-installed toolchains.