Super-Agent (v2.3.0+)

Some tasks are too tangled for a single LLM call. Pulling a vendor's invoice, cross-referencing it with three internal systems, and producing a reconciled summary is not one question — it is five or six steps that need to happen in order, with each step double-checked.

Super-agent is an opt-in mode on any LLM agent that lets the model plan multi-step work on its own and then execute the plan step by step, with verification on each step. You turn it on with a single YAML flag. The agent still looks and behaves like any other LLM agent to the rest of the mesh — same yields contract, same can_call rules, same session — but inside its own dispatch it can think, plan, retry, and synthesize.

Think of it like the difference between asking someone "what's the answer?" and asking them "make a plan, work through it, and show me the result." Same person; very different output for hard questions.

When to use it

Turn on super-agent for agents that routinely face:

Multi-step research — fetch from A, filter, fetch from B, reconcile, summarize.
Long-form reasoning — proofs, root-cause analyses, multi-document comparison.
Tasks that fail silently as one-shots — the LLM "answers," but the answer is wrong because it skipped a step.

Leave it off for simple agents — classification, formatting, summarization of a single document. A super-agent dispatch is heavier than a plain LLM call; you only want it when the extra structure pays for itself.

Quick start

agents:
  researcher:
    name: researcher
    agent_type: llm                # super-agent only works on LLM agents
    model: gpt-4o
    super_agent: true              # ← opt in
    prompt: |
      You are a research analyst. Given a question, gather what you need,
      verify your reasoning, and produce a clean final answer.
    yields:
      answer: string
      sources: array
      confidence: number

That's the whole opt-in. The framework injects the planning tools, manages the loop, and gives you a richer response envelope when the dispatch completes.

Tuning the budgets

Super-agent dispatches have two budgets — a token ceiling and a wall-clock limit — both with sensible defaults. Override them per agent when you need to:

agents:
  researcher:
    name: researcher
    agent_type: llm
    super_agent: true
    super_agent_cost_ceiling: 80000    # tokens for a single dispatch (default 50000)
    super_agent_wall_clock: 900        # seconds (default 600)

The nested form takes the full tuning surface — every knob is optional and defaults sensibly:

agents:
  researcher:
    name: "researcher"
    super_agent:
      cost_ceiling: 80000        # token ceiling for one dispatch
      wall_clock: 900            # seconds for one dispatch
      step_max_tokens: 4000      # per-step output budget
      synth_max_tokens: 4000     # synthesis output budget
      verify_view_chars: 6000    # how much of a step the verifier reads
      goal_check_view_chars: 6000
      step_concurrency: 2        # independent steps run in parallel up to this

To keep the tuning but turn planning off, write enabled: false in the map:

    super_agent:
      enabled: false             # planning off; the tuning above is kept
      cost_ceiling: 80000

wall_clock_seconds is read as wall_clock.

Whichever budget runs out first ends the dispatch gracefully — see "Response envelope" below for how that surfaces.

What the final output is

A super-agent's final output is the synthesis, shaped by the agent's declared yields — the same contract every other LLM agent honors. Three distinct artifacts exist at the end of a run, and only one is the output:

The step work (the research itself) — internal to the run; the verifier scores it, the synthesis draws on it.
The synthesis — this is the output: parsed against yields:, stored as the agent's yields, and handed to the next agent.
The goal-check verdict (score + critique) — a judge's opinion, folded in as metadata (_goal_score, _goal_critique), never the content.

Downstream agents therefore receive the super-agent's declared yields like any other handoff — a fan-in target sees them under upstream_yields, and a wait_for on the super-agent genuinely waits for them.

How a dispatch unfolds

When the agent is called with super_agent: true, the framework runs this loop on its behalf:

Plan. The LLM sees the task and, instead of answering directly, emits a multi-step plan via the framework-injected todowrite tool. Up to 10 steps per plan.
Execute. The orchestrator walks each step. For tool-using steps, the LLM picks the tool and the framework runs it. For reasoning steps, the LLM produces the intermediate result.
Verify. Each step is graded by a small follow-up check (a verifier score between 0 and 1), which writes its score first, so a cut-off answer keeps it. A low-scoring step is tried again with the critique folded in, as set by tries (see Tries per step below; by default once). If it never passes, the best answer is kept, the step is recorded as below the bar and the plan continues.
Synthesize. A final synthesis step assembles the answer according to the agent's declared yields schema. The synthesized output is what downstream can_call rules see.
Goal check (optional). An additional pass confirms the plan actually met the goal it set for itself. The score lands on the response envelope.

The whole thing is capped at 30 total iterations across all steps and retries, so even a pathological plan can't run forever.

Tries per step

2.4.491+. super_agent.tries sets how hard each step works to pass its check.

super_agent:
  tries:
    mode: fixed   # or auto
    count: 3      # attempts at once, 1-10
    rounds: 3     # 1-10

Field	Default	Meaning
`mode`	`fixed`	`fixed`: each round runs `count` attempts at once with the same model. `auto`: one attempt; `count` at once only after a failed check.
`count`	`1`	Attempts at once, 1–10.
`rounds`	`2`	Rounds, 1–10. The default is one attempt plus one retry, as before.

tries: 3 is short for {mode: fixed, count: 3}.

The step stops as soon as its check passes. Otherwise the next round gets the earlier critiques. When the rounds run out, the best answer of all rounds is kept and the run is reported partial (step_below_bar), never as a pass.

A wrong value is refused at load:

super_agent.tries.mode must be 'fixed' or 'auto', got '<x>'
super_agent.tries.count must be a whole number from 1 to 10, got <n>
super_agent.tries.rounds must be a whole number from 1 to 10, got <n>

Pause and resume

The LLM can also call a framework-injected pause tool mid-plan — for example, "I need a human approval before continuing." When that happens, the dispatch pauses cleanly with its full state preserved, and the response envelope returns _status: "paused". The customer or an upstream agent decides when (and whether) to resume.

Cancelling mid-dispatch

A super-agent dispatch can be cancelled from outside at any time:

await sdk.cancel_dispatch(session_id="customer-42", agent_name="researcher")

The current step finishes its in-flight tool call (cancellation is cooperative), and the response comes back with _status: "cancelled" and whatever the plan got through.

Auto-injected tools

When super_agent: true, two tools appear on the agent automatically — you don't list them under tools::

Tool	Purpose
`todowrite`	The LLM emits its plan through this tool instead of answering directly.
`pause`	The LLM uses this to pause its own dispatch (state preserved, resumable).

Your own configured tools: array still works exactly the same — super-agent doesn't take any tool slots from you. The planning tools live alongside whatever the agent already has.

Guardrails baked in

These limits aren't knobs — they're the framework's safety net so a super-agent can't run away:

Max 10 steps per plan. Anything bigger means the LLM is over-planning; the orchestrator caps it.
Max 30 total iterations per dispatch (steps + retries + verifier calls).
Low-score retry — by default one retry per step; set with tries (below).
2 retries per phase on transient errors (network blips, rate limits) before the step is marked errored.

Combined with super_agent_cost_ceiling and super_agent_wall_clock, these give every dispatch a hard outer envelope.

Response envelope

When super_agent fires, the response carries a few extra fields alongside your declared yields. They all start with an underscore so you can spot them at a glance and ignore them in normal flows.

Field	Type	Meaning
`_super_agent`	bool	Always `true` on a super-agent response.
`_status`	string	One of `"completed"`, `"cancelled"`, `"paused"`, `"errored"`, `"synthesis_only"`.
`_status_reason`	list[str]	Human-readable reasons that produced the status.
`_plan`	object	Plan summary with per-step status and verifier scores.
`_cost_ceiling_hit`	bool	`true` if the token budget ran out before the plan completed.
`_wall_clock_hit`	bool	`true` if the wall-clock limit ran out before the plan completed.
`_goal_met`	bool	Did the final goal-check confirm the plan met its goal?
`_goal_score`	float \	null	The numeric goal-check score, or `null` if the check didn't run.

_status: "synthesis_only" happens when the LLM short-circuited the plan and answered directly without writing a plan at all — useful to spot when a task didn't actually need the heavier flow.

Inspecting a plan

result = await sdk.mesh_call("researcher", input_data={"question": "..."})

if result.get("_super_agent"):
    print(result["_status"])               # "completed"
    print(result["_plan"]["steps"])        # [{name, status, score}, ...]
    print(result["_goal_met"])             # True / False
    if result["_cost_ceiling_hit"]:
        print("Bumped the token budget — consider raising super_agent_cost_ceiling")

The plan summary is meant for logging, debugging, and Studio's inspector view. Downstream agents in your can_call chain still receive your declared yields unchanged — the underscore-prefixed fields are metadata, not part of your contract.

Interaction with the rest of the mesh

A super-agent dispatch is transparent to everyone else:

can_call rules still fire after the dispatch completes. They read your declared yields, not the underscore fields.
Session state is shared — the super-agent reads and writes the same conversation history any other LLM agent would.
communication_type (dual, chain, execute) works the same. Streaming (stream_yield) works the same for the final synthesized output.
Intelligence functions (the Python function whose name matches the agent name) still run on the synthesized response.

This is why super_agent is a per-agent flag, not a project-wide mode — you can have one super-agent and ten regular LLM agents in the same mesh, with no special wiring between them.

Configuration reference

Field	Type	Default	Description
`super_agent`	bool / object	`false`	Opt in. Only valid on `agent_type: llm`.
`super_agent_cost_ceiling`	int	`50000`	Token budget for one dispatch.
`super_agent_wall_clock`	int	`600`	Wall-clock budget in seconds for one dispatch.

Nested form (equivalent):

super_agent:
  cost_ceiling: 80000
  wall_clock: 900

Next Steps

LLM Agents — All the standard LLM-agent fields work alongside super-agent.
Skill-Augmented Agents — Skills compose with super-agent; the plan can reference any attached skill.
Agent Configuration Reference — Complete YAML schema.

LeafMesh — Plan, execute, verify, synthesize — on any LLM agent, with one YAML flag.