Aegis Orchestrator
Agents

The Execution Loop

How the 100monkeys outer loop, inner loop, and Dispatch Protocol work together to run an agent execution.

The Execution Loop

AEGIS executes agents in a two-loop architecture. The outer loop (ExecutionSupervisor) manages retries across fresh container instances. The inner loop (InnerLoopService) handles transparent LLM tool call interception within a single container run. Understanding both is essential for reasoning about agent behavior, debugging failures, and configuring validation correctly.


Why Iterative Execution?

Standard autonomous agents operate on a single-shot basis: generate output, execute it, return the result. When the LLM hallucinates an API, makes an off-by-one error, or produces structurally valid but semantically wrong code, the task fails — with no recovery path.

AEGIS treats LLM output as a candidate solution rather than a final product. Every iteration result is verified against declared success criteria before being accepted. This shifts the execution model from probabilistic generation to verified correctness: the orchestrator accepts an output only when it can demonstrate, deterministically, that the output meets the task requirements.

The practical effect: agents that would succeed roughly 60% of the time on a single attempt routinely reach >95% success rates through iteration, because the specific failure reason is fed back to the model as compiler-style feedback for the next attempt.


Execution Modes

An agent's spec.execution.mode is iterative (the default) or one-shot. An iterative agent runs the refinement loop, up to max_iterations tries (max_retries is the same field), each failure fed back into the next try; a one-shot agent runs one try.

spec:
  execution:
    mode: iterative     # "iterative" (default) | "one-shot" (one try)
    max_iterations: 10  # the tries, in all; default: 5
    iteration_timeout: "300s"  # per-iteration wall-clock limit; default: 600s
max_iterationsBehaviour
2 or moreRun up to max_iterations attempts. Inject failure context between attempts. Accept output only when all validators pass.
1Run exactly one attempt; its validators still score it, and a failing score ends the execution. Useful for judge agents and short-lived classification tasks.

The Outer Loop: ExecutionSupervisor

The ExecutionSupervisor drives the 100monkeys iterative refinement strategy. When an execution is started, the supervisor:

  1. Spawns a fresh, isolated container from the agent's image using the configured container runtime (Docker or Podman). Each iteration gets a clean environment -- no shared process state from previous iterations. In rootless Podman deployments, workspace volumes are mounted via FUSE bind mounts from the host-side FUSE daemon rather than NFS; the agent code is identical in both cases.
  2. Injects context into the container: the task input, any prior iteration errors (on retries), and tool definitions filtered to the agent's declared capabilities.
  3. Monitors execution until the inner loop reports completion or timeout.
  4. Checks declared outputs. When the manifest or the caller declares outputs (spec.execution.outputs), each is read from the execution's volume before the iteration counts as completed; a missing, short or wrong-prefix file fails the iteration, and its sentence is the next iteration's feedback.
  5. Runs validators against the iteration output. Validators produce a ValidationScore (0.0–1.0) and Confidence (0.0–1.0).
  6. Decides the next action:
    • Score ≥ threshold → IterationStatus::Success → execution completes.
    • Score < threshold, iterations remaining → IterationStatus::Refining → error context injected, next container spawned.
    • Score < threshold, max iterations reached → IterationStatus::Failed → execution fails.
    • Hard timeout hit → execution cancelled.

A bootstrap that exits non-zero fails its iteration with its stderr as the error, and the next iteration starts; when every iteration fails, the execution ends failed. AEGIS_KEEP_CONTAINER only keeps the failed container for inspection.

Iteration State Machine

          ┌─────────┐
          │ Running │
          └────┬────┘
               │ inner loop completes
               ▼
         ┌──────────┐      score ≥ threshold     ┌─────────┐
         │ Validating│─────────────────────────▶ │ Success │
         └──────────┘                            └─────────┘
               │ score < threshold
               │ iterations < max
               ▼
          ┌──────────┐
          │ Refining │──── inject error, spawn next container
          └──────────┘
               │ iterations == max
               ▼
           ┌────────┐
           │ Failed │
           └────────┘

Execution Aggregate

The Execution aggregate root enforces these invariants at the domain level:

  • At most one iteration is running at a time.
  • Iteration numbers are sequential with no gaps.
  • max_iterations cannot be exceeded (default: 5).
  • A completed or failed execution is immutable.

The ExecutionHierarchy value object tracks an execution's position within multi-agent structures. It includes an optional swarm_id field that links the execution to its parent swarm when spawned as a child agent. This swarm_id is propagated to all child executions for end-to-end tracing correlation across the swarm.


The Inner Loop: InnerLoopService

Within a single container run, InnerLoopService implements transparent LLM tool call interception. The agent's bootstrap.py never receives raw tool call JSON from the LLM — the orchestrator handles it completely.

Communication Channel

bootstrap.py communicates with the orchestrator over a single long-running HTTP POST to /v1/dispatch-gateway. This channel carries a discriminated union of message types in both directions.

Agent → Orchestrator (AgentMessage):

// Start an LLM inference pass
{
  "type": "generate",
  "agent_id": "<agent-uuid>",
  "execution_id": "<execution-uuid>",
  "iteration_number": 1,
  "prompt": "Write a function that reverses a string.",
  "model_alias": "default",
  "messages": []
}

// Return result of a dispatched subprocess
{
  "type": "dispatch_result",
  "dispatch_id": "<uuid>",
  "exit_code": 0,
  "stdout": "...",
  "stderr": ""
}
FieldRequiredDescription
typeyes"generate" to start an LLM pass; "dispatch_result" to return a subprocess result.
agent_idyesUUID of the agent. Injected by the orchestrator as AEGIS_AGENT_ID.
execution_idyesUUID of the current execution. Injected as AEGIS_EXECUTION_ID.
iteration_numberyes1-based iteration counter. Injected as AEGIS_ITERATION.
promptyesThe fully-rendered task prompt. Written to bootstrap.py's standard input, which it reads to end of file.
model_aliasnoLLM alias to route through. Defaults to "default" (the orchestrator's configured default provider). Maps from spec.runtime.model in the agent manifest.
messagesnoPrior conversation turns to prepend. Empty array for a fresh iteration start.

Orchestrator → Agent (OrchestratorMessage):

// LLM produced a final text response — iteration complete
{ "type": "final", "content": "I have written the solution to /workspace/solution.py" }

// LLM requested a subprocess execution — run it and report back
{ "type": "dispatch", "dispatch_id": "<uuid>", "action": "exec", "command": "python", "args": ["/workspace/test.py"] }

Tool Call Flow

When the LLM emits a tool call in its response:

  1. The orchestrator intercepts and routes the tool call via the Tool Router (see MCP Tool Routing).
  2. The tool result is appended to the conversation as a tool message.
  3. The orchestrator makes another LLM inference call with the updated conversation.
  4. Steps 1–3 repeat until the LLM emits a response with no tool calls.
  5. The orchestrator returns OrchestratorMessage { type: "final" } to bootstrap.py.

From bootstrap.py's perspective, it sends one generate message and receives one final response. All tool calls happen inside the orchestrator.


The Dispatch Protocol

The Dispatch Protocol handles tool calls that require running a subprocess inside the agent container — for example, compiling code, running tests, or executing an interpreter. This is Path 3 of the three-path tool router.

Why Not Container Exec?

The orchestrator cannot call the container runtime's exec API directly because:

  • It would be runtime-specific (breaks Firecracker support and ties the orchestrator to a single container engine).
  • It bypasses the bootstrap script's process supervision and output capture.

Instead, the orchestrator sends a dispatch message over the existing HTTP channel to bootstrap.py, which runs the subprocess and sends back a dispatch_result.

Wire Format

Orchestrator                              bootstrap.py (in container)
     │                                           │
     │  POST /v1/dispatch-gateway                    │
     │  { type: "generate", messages: [...] }    │
     │ ─────────────────────────────────────────▶│
     │                                           │  (LLM calls cmd.run)
     │  { type: "dispatch",                      │
     │    dispatch_id: "abc-123",                │
     │    action: "exec",                        │
     │    command: "python",                     │
     │    args: ["/workspace/test.py"] }         │
     │ ◀─────────────────────────────────────────│
     │                                           │  (runs subprocess)
     │  POST /v1/dispatch-gateway                    │
     │  { type: "dispatch_result",               │
     │    dispatch_id: "abc-123",                │
     │    exit_code: 0,                          │
     │    stdout: "All tests passed",            │
     │    stderr: "" }                           │
     │ ─────────────────────────────────────────▶│
     │                                           │  (LLM continues)
     │  { type: "final", content: "..." }        │
     │ ◀─────────────────────────────────────────│

SubcommandAllowlist

Not every cmd.run invocation is permitted. The node config's SubcommandAllowlist is a HashMap<String, Vec<String>> mapping base commands to their allowed first positional arguments:

tools:
  subcommand_allowlist:
    python: ["test.py", "-m", "-c"]
    node: ["index.js", "test.js"]
    cargo: ["build", "test", "run"]
    npm: ["install", "test", "run"]
    git: ["status", "diff", "log"]

If an agent attempts cmd.run with a command or subcommand not in the allowlist, the orchestrator rejects the dispatch and returns a policy violation event.


Validation: Gradient Scoring

AEGIS does not use binary pass/fail validation. Every validator produces:

  • ValidationScore (0.0–1.0): how well the output meets the criteria.
  • Confidence (0.0–1.0): certainty of the score.

This allows nuanced threshold configuration. An agent can succeed with a score of 0.8 if min_score: 0.8 is set, or be required to reach 0.95 for high-stakes tasks.

Multiple validators are applied in order. The execution proceeds to the next iteration if any validator's score falls below its threshold.

Validator types:

  • exit_code — deterministic; checks process exit code.
  • json_schema — deterministic; validates stdout against a JSON Schema.
  • regex — deterministic; matches stdout against a pattern.
  • semantic — LLM-as-Judge; single judge agent produces a score.
  • multi_judge — consensus across N judge agents.

See Configuring Agent Validation for full configuration details.


Workflow Execution Output

When a workflow declares output_schema and output_template in its metadata, the engine produces a structured final_output at completion. The lifecycle is:

  1. States complete -- each state writes its output to the Blackboard as usual.
  2. Blackboard populated -- by the time the workflow reaches a terminal state, the Blackboard contains all state outputs.
  3. Output template evaluated -- the engine renders each output_template value as a Handlebars expression against the final Blackboard. Each leaf value is rendered independently.
  4. Type coercion -- rendered string values are coerced to the types declared in output_schema (e.g. parseInt for integers, parseFloat for numbers, === "true" for booleans, JSON.parse for objects and arrays).
  5. Validation -- the coerced output is validated against output_schema. If coercion or validation fails, the workflow fails with a descriptive error identifying the field and the value that could not be coerced or validated.
  6. Storage -- the validated output is stored as WorkflowExecution.final_output in PostgreSQL and returned as last_output in aegis.workflow.wait tool responses.

Workflows without output_template complete as before -- the Blackboard is captured but no structured final_output is produced.


Attachments Propagation

When a dispatch carries an attachments array (e.g. from a Zaru chat upload, an SDK call, or an enclosing workflow state), the orchestrator merges those references into the agent's JSON input under the key attachments before the prompt is built. If the caller's input is a JSON object, attachments is added as a sibling key. If the caller's input is a scalar (string, number) and attachments are non-empty, the orchestrator wraps it as { "value": <scalar>, "attachments": [...] }. The merged input is what the agent's LLM sees when {{input}} is substituted into the agent's prompt template.

The same merged input also reaches the running container through the standard hydration surfaces:

SurfaceWhere it appears
LLM promptThe substituted {{input}} JSON contains input.attachments. The agent's task.instruction references input.attachments in prose.
EnvironmentINTENT_INPUTS JSON contains params.input.attachments.
Filesystem/workspace/params.json includes attachments in its input object.

Each AttachmentRef is { volume_id, path, name, mime_type, size, sha256? }. The agent reads the actual bytes by calling aegis.attachment.read({ volume_id, path }), which returns base64 content plus MIME, size, and SHA-256. The tool is read-only and tenant-scoped. Agents that consume attachments must declare them in spec.input_schema, include aegis.attachment.read in spec.tools, and be type: system.

Agent task.instruction is not re-rendered as a Handlebars template at runtime — the orchestrator substitutes {{instruction}} into prompt_template once, and the result is passed to the LLM as raw text. To loop over attachments, the instruction describes the loop in prose (e.g. "for each entry in input.attachments, call aegis.attachment.read({volume_id, path})"); embedding {{#each attachments}} in the instruction body would reach the LLM as literal text and is rejected by the agent generator's validation.


Timeout Hierarchy

Four independent timeout boundaries apply to every execution. They nest from outermost to innermost:

LevelConfigDefaultEnforced by
Overall executionspec.security.resources.timeout1800 s (30 min)ExecutionSupervisor outer tokio::time::timeout
Per iterationspec.execution.iteration_timeout600 sExecutionSupervisor per-iteration tokio::time::timeout, terminating the container
One model callspec.execution.llm_timeout_seconds300 sThe orchestrator's inner loop; the call fails with an error naming llm_timeout_seconds
Inner loop tool callsMAX_INNER_LOOP_ITERATIONS constant50 callsInnerLoopService loop bail

The outer timeout is a hard wall: if the total execution time exceeds spec.security.resources.timeout, the orchestrator cancels the execution regardless of which iteration is in progress. The per-iteration timeout is reset for each new iteration, so a long-running first iteration does not consume the per-iteration budget of subsequent attempts.

bootstrap.py holds no timeout of its own: an agent container whose iteration never answers is ended by the iteration's bound, then by the execution's. The orchestrator records each execution's bound when it starts; see Container Cleanup Guarantees for what ends an execution that outlives it.

Room for Two Tries

An agent that may try more than once (spec.execution.max_retries, or its alias max_iterations, of 2 or more; 5 when unset) must have an execution bound with room for two whole tries: 2 × (its iteration_timeout, 600 s when unset, plus the timeout_seconds of its semantic and multi_judge validators) + 15 s, the wait after a failed first try, + 30 s to start the container. Creating or updating an agent whose resources.timeout (1800 s when unset) is under that figure is refused, by every path that creates or updates an agent, with:

Agent '<name>' is refused (execution-bound/two-tries): resources.timeout <bound> s is under the <need> s that two whole tries need (iteration_timeout <i> s and its judges' <j> s each, the wait between them and the start). Set resources.timeout to <need>s or more, or max_retries to 1.

For example, an agent with max_retries: 3, no iteration_timeout and one semantic judge of timeout_seconds: 180 needs 2 × (600 + 180) + 15 + 30 = 1605 s: at resources.timeout: 900s it is refused, naming 900 s and 1605 s, and at 1605s, or at max_retries: 1, it is accepted. Some of the platform's built-in agents keep bounds of their own; an agent of yours with the same name does not.

Agents stored before this check whose bound was under their figure had resources.timeout raised to it once, when the check was deployed; nothing else in their manifests changed, and aegis.agent.export shows the new bound. An agent that declares no spec.security and needs more than 1800 s was left as it was.

When a Later Try Does Not Fit

The first try always starts. A later try starts only when the time left under resources.timeout is at least one whole try, its iteration_timeout plus its judges' timeout_seconds. When it is not, the execution ends failed with the last try's cause first and the time second: "Execution ended after <n> tries: <cause>; a further try does not fit: <left> s left under the <bound> s bound, under the <need> s a try needs" ("after 1 try" for one). The cause is how the last try ended, for example "the last attempt's output was rejected: <the judge's reason>" or "the last attempt failed validation: <the error>".

aegis.task.status and aegis.task.wait (and aegis.agent.wait, its alias) answer that sentence as error, 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.

On this page