1What if the lead agent has hundreds of sub-tasks to hand out?
The lead agent stops delegating turn by turn. It writes a short script and a runtime runs it. The script holds the loops and branches, starts each sub-agent as a full agent with its own tools, and keeps their results. Only the script's final value returns to the lead. A sub-agent may do the same in turn.
You may need it if
- A lead agent assigns items one by one and skips some of them somewhere after the fiftieth.
- Every sub-agent result lands in the lead's context, which fills up long before the work is done.
- The coordination is a loop and a filter that you could write in twenty lines of code.
2When should coordination stay in the conversation, not in a script?
Use it when
- The same step must run over dozens or hundreds of items, and none may be skipped.
- The coordination can be written in advance as loops, branches and filters over results in a fixed format.
- Each item needs a real agent that reads files, searches or runs code, not a single model call.
Avoid it when
- There are a handful of sub-tasks. One conversation can assign them and read every result, for far fewer tokens.
Use Supervisor & Specialists instead - The next assignment depends on a judgement about the last result. That judgement cannot be written as a condition in advance.
Use Magentic Orchestration instead - Each piece needs one model call on a slice of a long input, with no tools. A full agent per piece is far more than the work requires.
Use Recursive Language Model instead - A person must approve or steer between stages. A running script does not pause to ask. Split the work into separate runs.
What it costs
- Model calls
- 1 script + 1 full agent run per sub-task (tens to hundreds) + 1 answer
- Latency
- high
- Complexity
- high
3Who holds the loop when the lead agent stops delegating by hand?
The lead sizes the workload and writes a script. A runtime runs it. The script starts sub-agents in parallel, each a full agent in its own workspace, and keeps what they return. It loops, filters and aggregates in code. The lead receives the final value only, and writes the answer from it.
- Step 1 of 6
The lead sizes the work
The task: among the supplier contracts in a folder, list those that renew automatically with less than 60 days' notice. The lead lists the folder and counts 300 files. Reading them itself, or assigning them one by one, would fill its context long before the end.
- Step 2 of 6
It writes a script instead of delegating
The lead writes about twenty lines of code. For each file, start a sub-agent with the same instruction and a fixed reply format: renews or not, notice in days, the clause quoted. Then keep the matches. It hands the script to the runtime.
- Step 3 of 6
The runtime fans out
The runtime executes the loop. It starts sub-agents, sixteen at a time, until all 300 files are covered. The loop decides which file comes next, not a model, so no file is skipped.
- Step 4 of 6
Each sub-agent is a full agent
One sub-agent opens its contract and finds a master agreement with forty annexes. It can write a script of its own and start one sub-agent per annex. A depth limit of three levels stops this from going further down.
- Step 5 of 6
Results stay with the script
Each sub-agent leaves a short record in the agreed format. The script reads the records, counts the 2 files that no sub-agent could read, filters on a notice below 60 days and sorts. None of this passes through the lead.
- Step 6 of 6
One value returns to the lead
The script returns 23 matches and the counts: 300 files planned, 298 read, 2 unreadable. That is all the lead sees. It writes the answer from this value and names the two files that still need a person.
What each part does
- Task
- A goal that covers many items or phases, with access to the material: a folder, a long document, a list.
- Lead agent
- Inspects the material to size the work and writes the orchestration script. Later turns the script's final value into the answer.
- Script runtime
- Runs the script outside the lead's context: its loops, branches and spawns. Enforces the limits on concurrency, depth and total agents.
- Sub-agents
- Full agents with file tools, code execution and planning. Each works in its own workspace and sees neither the lead nor its peers.
- Result records
- What each sub-agent returned, as files or script variables in a fixed format. The script reads them. The lead never does.
- Result
- The answer or report written from the script's final value, with the coverage counts.
- Lead agent → Script runtime: script to run
- Script runtime → Sub-agents: one per sub-task, in parallel
- Sub-agents → Script runtime: finished
- Script runtime → Lead agent: final value only
- Lead agent → Result: writes the answer
Where it connects
A goal over many items or phases, or a plan whose steps become the phases of the script. The material is reachable through the sub-agents' tools, not pasted into the request.
When: The script has returned its final value and the lead has written the answer from it.
The answer or report, then the coverage: items planned, completed and failed, sub-agents started, and the script that ran.
One record per sub-agent, in the format the script asked for. Read by the script only. Lost at the end of the run unless the final value carries it.
4What do I ask my assistant to set up?
The agents to launch
Lead agent
Inspect the material and count the sub-tasks. With more than five, do not delegate by hand. Write a script that starts one sub-agent per sub-task, fixes their reply format, runs them in parallel and returns one small aggregated value with counts of successes and failures. When the value comes back, write the answer from it and report the coverage.
Sees: The task, a listing of the material and the script's final value. Not the sub-agents' transcripts or their individual results.
Sub-agent, one per sub-task in the script, 16 at a time, 200 in total
Complete the one sub-task you receive with your own tools: read files, search, run code. Reply only in the requested format. If your sub-task itself splits into more than five parts and the depth limit allows it, write a script of your own. Otherwise do the work yourself.
Sees: Its own sub-task, workspace and tools. Not the lead's context, the script or the other sub-agents.
A prompt you can paste
Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.
You are the orchestrator of a multi-agent workflow that follows the "Recursive Agent Harness" architecture. Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it. # Task [Describe your task here] # Recursive Agent Harness The lead writes a script that launches and collects the sub-agents. Input: the task above. It must provide: A goal over many items or phases, or a plan whose steps become the phases of the script. The material is reachable through the sub-agents' tools, not pasted into the request. If something essential is missing, ask for it before starting. Agents to launch: - Lead agent: Inspect the material and count the sub-tasks. With more than five, do not delegate by hand. Write a script that starts one sub-agent per sub-task, fixes their reply format, runs them in parallel and returns one small aggregated value with counts of successes and failures. When the value comes back, write the answer from it and report the coverage. Context for this agent: The task, a listing of the material and the script's final value. Not the sub-agents' transcripts or their individual results. - Sub-agent (one per sub-task in the script, 16 at a time, 200 in total): Complete the one sub-task you receive with your own tools: read files, search, run code. Reply only in the requested format. If your sub-task itself splits into more than five parts and the depth limit allows it, write a script of your own. Otherwise do the work yourself. Context for this agent: Its own sub-task, workspace and tools. Not the lead's context, the script or the other sub-agents. Procedure: 1. Give the lead a runtime that executes its script in isolation and exposes one primitive, which starts a sub-agent on a prompt and returns its reply. 2. Launch the lead on the task. Let it inspect the material and write the script with the list of sub-tasks, the reply format, the parallel fan-out, the aggregation and the value to return. 3. Run the script. Cap it at 16 sub-agents at a time, 200 in total and 3 levels of nesting. Start each sub-agent in its own workspace with its own tools. 4. Keep every sub-agent reply as a record that the script can read. Do not copy the records into the lead's context. 5. If the script fails to run, return the error to the lead and let it correct the script once. 6. Give the script's final value to the lead and have it write the answer with the coverage counts. Stop rule: Stop when the script has returned and the lead has answered. The runtime refuses a 201st sub-agent and any script at level 3. After a second script failure, the lead reports the error and stops. Exit: - `result`, when: The script has returned its final value and the lead has written the answer from it. Deliver: The answer or report, then the coverage: items planned, completed and failed, sub-agents started, and the script that ran. # Final deliverable The answer, then the coverage: items planned, completed and failed, sub-agents started, the deepest level used, and the script that ran.
The same thing in code
import asyncio
import json
from typing import Any, TypedDict
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel
MAX_DEPTH, MAX_AGENTS, MAX_PARALLEL, MAX_FIXES, MAX_VALUE = 3, 200, 16, 1, 4000
HARNESS = ("You are an agent with your own tools. If your task splits into more than five independent sub-tasks, "
"do not do them yourself: fill `script` with the body of an async Python function. In it, "
"`await task(prompt)` starts one sub-agent and returns its reply as text, `await gather(...)` runs "
"several in parallel, and `json` is available. Ask each sub-agent for JSON so the script can filter "
"and count in code. End with `return` and one small aggregated value with counts of successes and "
"failures, never the raw replies. Otherwise leave `script` empty, do the work and fill `reply`.")
ANSWER = ("Your script ran and returned one value. Write the reply to your task from it. State the coverage: "
"items planned, completed and failed.")
class Move(BaseModel):
script: str # "" when the agent does the work itself
reply: str # the result of the work, or "" when a script is written
class State(TypedDict):
task: str
depth: int # the lead is at level 1
counters: dict[str, int] # shared by the whole tree: sub-agents started, deepest level
script: str
value: str
error: str
fixes: int
answer: str
model = init_chat_model("anthropic:claude-sonnet-5-5")
slots = asyncio.Semaphore(MAX_PARALLEL) # at most 16 agents think at the same time
def start(task: str, depth: int, counters: dict[str, int]) -> State:
return {"task": task, "depth": depth, "counters": counters, "script": "", "value": "", "error": "", "fixes": 0, "answer": ""}
async def agent(state: State) -> dict:
# a full agent: bind its file, search and code tools to the model here
prompt = f"Task: {state['task']}"
if state["depth"] >= MAX_DEPTH:
prompt += "\n\nYou are at the depth limit: leave `script` empty and do the work yourself."
if state["error"]:
prompt += f"\n\nYour script:\n{state['script']}\n\nIt failed with: {state['error']}\nCorrect it."
async with slots:
raw = await model.with_structured_output(Move).ainvoke([SystemMessage(HARNESS), HumanMessage(prompt)])
move = Move.model_validate(raw)
script = move.script if state["depth"] < MAX_DEPTH else ""
return {"script": script, "answer": "" if script.strip() else move.reply}
def after_agent(state: State) -> str:
return "runtime" if state["script"].strip() else END
async def runtime(state: State) -> dict:
counters = state["counters"]
async def task(prompt: str) -> str: # the one primitive the script gets
if counters["started"] >= MAX_AGENTS:
raise RuntimeError("agent budget spent")
counters["started"] += 1
counters["deepest"] = max(counters["deepest"], state["depth"] + 1)
sub = await graph.ainvoke(start(prompt, state["depth"] + 1, counters)) # the same harness, one level down
return sub["answer"]
body = "\n".join(" " + line for line in state["script"].splitlines())
env: dict[str, Any] = {"json": json}
try:
# replace exec with a real sandbox (container, no network): a model wrote this code
exec(f"async def main(task, gather):\n{body}", env)
value = json.dumps(await env["main"](task, asyncio.gather), default=str)
except Exception as e:
return {"error": f"{type(e).__name__}: {e}", "fixes": state["fixes"] + 1}
# the sub-agents' results stayed in the script: one value goes back to the agent
return {"value": value[:MAX_VALUE], "error": ""}
def after_runtime(state: State) -> str:
return "agent" if state["error"] and state["fixes"] <= MAX_FIXES else "write_answer"
async def write_answer(state: State) -> dict:
if state["error"]:
return {"answer": f"The script failed twice. Last error: {state['error']}"}
prompt = f"Task: {state['task']}\n\nYour script returned:\n{state['value']}"
async with slots:
reply = await model.ainvoke([SystemMessage(ANSWER), HumanMessage(prompt)])
return {"answer": reply.text}
builder = StateGraph(State)
builder.add_node("agent", agent)
builder.add_node("runtime", runtime)
builder.add_node("write_answer", write_answer)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", after_agent, ["runtime", END])
builder.add_conditional_edges("runtime", after_runtime, ["agent", "write_answer"])
builder.add_edge("write_answer", END)
graph = builder.compile()
async def run(task: str) -> dict:
counters = {"started": 0, "deepest": 1}
s = await graph.ainvoke(start(task, 1, counters))
return {"answer": s["answer"], "script": s["script"], "sub_agents": counters["started"], "deepest_level": counters["deepest"]}
Each task() call runs this same graph one level down: that is the recursion. exec is a placeholder for a sandbox, and the agents have no tools bound here.
import asyncio
import json
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel
MAX_DEPTH, MAX_AGENTS, MAX_PARALLEL, MAX_FIXES, MAX_VALUE = 3, 200, 16, 1, 4000
WORKSPACE = Path("workspace") # give each sub-agent its own copy when sub-tasks write files
TOOLS = ["Read", "Glob", "Grep", "Bash"] # every agent in the tree is a full harness
HARNESS = ("If your task splits into more than five independent sub-tasks, do not do them yourself: fill "
"`script` with the body of an async Python function. In it, `await task(prompt)` starts one "
"sub-agent and returns its reply as text, `await gather(...)` runs several in parallel, and `json` "
"is available. Ask each sub-agent for JSON so the script can filter and count in code. End with "
"`return` and one small aggregated value with counts of successes and failures, never the raw "
"replies. Otherwise leave `script` empty, do the work with your tools and fill `reply`.")
ANSWER = ("Your script ran and returned one value. Write the reply to your task from it. State the coverage: "
"items planned, completed and failed.")
class Move(BaseModel):
script: str # "" when the agent does the work itself
reply: str # the result of the work, or "" when a script is written
@dataclass
class Tree: # shared by the whole run
started: int = 0
deepest: int = 1
lead_script: str = ""
slots = asyncio.Semaphore(MAX_PARALLEL) # at most 16 agents work at the same time
async def session(system: str, prompt: str, structured: bool) -> ResultMessage:
options = ClaudeAgentOptions(
system_prompt=system, cwd=WORKSPACE, allowed_tools=TOOLS if structured else [],
output_format={"type": "json_schema", "schema": Move.model_json_schema()} if structured else None,
)
async with slots:
async for msg in query(prompt=prompt, options=options):
if isinstance(msg, ResultMessage):
return msg
raise RuntimeError("no result")
async def harness(task: str, depth: int, tree: Tree) -> str:
"""One full agent. The lead runs at level 1; every task() in a script runs this function one level down."""
tree.deepest = max(tree.deepest, depth)
may_script = depth < MAX_DEPTH
prompt = f"Task: {task}"
if not may_script:
prompt += "\n\nYou are at the depth limit: leave `script` empty and do the work yourself."
error = ""
for _ in range(MAX_FIXES + 1): # the script may be corrected once
move = Move.model_validate((await session(HARNESS, prompt, True)).structured_output)
if not may_script or not move.script.strip():
return move.reply
if depth == 1:
tree.lead_script = move.script
async def spawn(sub: str) -> str: # the one primitive the script gets
if tree.started >= MAX_AGENTS:
raise RuntimeError("agent budget spent")
tree.started += 1
return await harness(sub, depth + 1, tree)
body = "\n".join(" " + line for line in move.script.splitlines())
env: dict[str, Any] = {"json": json}
try:
# replace exec with a real sandbox (container, no network): a model wrote this code
exec(f"async def main(task, gather):\n{body}", env)
value = json.dumps(await env["main"](spawn, asyncio.gather), default=str)[:MAX_VALUE]
except Exception as e:
error = f"{type(e).__name__}: {e}"
prompt = f"Task: {task}\n\nYour script:\n{move.script}\n\nIt failed with: {error}\nCorrect it."
continue
# the sub-agents' results stayed in the script: one value goes back to the agent
final = await session(ANSWER, f"Task: {task}\n\nYour script returned:\n{value}", False)
return final.result or ""
return f"The script failed twice. Last error: {error}"
async def run(task: str) -> dict:
tree = Tree()
answer = await harness(task, 1, tree)
return {"answer": answer, "script": tree.lead_script, "sub_agents": tree.started, "deepest_level": tree.deepest}
Sub-agents are separate sessions with their own tools, started by the script and not by the lead's Agent tool. exec is a placeholder for a sandbox.
import asyncio
import json
from dataclasses import dataclass
from typing import Any
from agents import Agent, Runner
from pydantic import BaseModel
MAX_DEPTH, MAX_AGENTS, MAX_PARALLEL, MAX_FIXES, MAX_VALUE = 3, 200, 16, 1, 4000
class Move(BaseModel):
script: str # "" when the agent does the work itself
reply: str # the result of the work, or "" when a script is written
@dataclass
class Tree: # shared by the whole run
started: int = 0
deepest: int = 1
lead_script: str = ""
worker = Agent(
name="Harness",
instructions="If your task splits into more than five independent sub-tasks, do not do them yourself: fill "
"`script` with the body of an async Python function. In it, `await task(prompt)` starts one "
"sub-agent and returns its reply as text, `await gather(...)` runs several in parallel, and "
"`json` is available. Ask each sub-agent for JSON so the script can filter and count in code. "
"End with `return` and one small aggregated value with counts of successes and failures, never "
"the raw replies. Otherwise leave `script` empty, do the work with your tools and fill `reply`.",
tools=[], # plug in file, search and code tools: every agent in the tree is a full harness
output_type=Move,
)
writer = Agent(
name="Answer",
instructions="Your script ran and returned one value. Write the reply to your task from it. State the "
"coverage: items planned, completed and failed.",
)
slots = asyncio.Semaphore(MAX_PARALLEL) # at most 16 agents work at the same time
async def harness(task: str, depth: int, tree: Tree) -> str:
"""One full agent. The lead runs at level 1; every task() in a script runs this function one level down."""
tree.deepest = max(tree.deepest, depth)
may_script = depth < MAX_DEPTH
prompt = f"Task: {task}"
if not may_script:
prompt += "\n\nYou are at the depth limit: leave `script` empty and do the work yourself."
error = ""
for _ in range(MAX_FIXES + 1): # the script may be corrected once
async with slots:
move = (await Runner.run(worker, prompt)).final_output_as(Move)
if not may_script or not move.script.strip():
return move.reply
if depth == 1:
tree.lead_script = move.script
async def spawn(sub: str) -> str: # the one primitive the script gets
if tree.started >= MAX_AGENTS:
raise RuntimeError("agent budget spent")
tree.started += 1
return await harness(sub, depth + 1, tree)
body = "\n".join(" " + line for line in move.script.splitlines())
env: dict[str, Any] = {"json": json}
try:
# replace exec with a real sandbox (container, no network): a model wrote this code
exec(f"async def main(task, gather):\n{body}", env)
value = json.dumps(await env["main"](spawn, asyncio.gather), default=str)[:MAX_VALUE]
except Exception as e:
error = f"{type(e).__name__}: {e}"
prompt = f"Task: {task}\n\nYour script:\n{move.script}\n\nIt failed with: {error}\nCorrect it."
continue
# the sub-agents' results stayed in the script: one value goes back to the agent
async with slots:
final = await Runner.run(writer, f"Task: {task}\n\nYour script returned:\n{value}")
return final.final_output_as(str)
return f"The script failed twice. Last error: {error}"
async def run(task: str) -> dict:
tree = Tree()
answer = await harness(task, 1, tree)
return {"answer": answer, "script": tree.lead_script, "sub_agents": tree.started, "deepest_level": tree.deepest}
The script starts the sub-agents, so this uses neither handoffs nor agents as tools. exec is a placeholder for a sandbox. Give the worker real tools.
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent } from 'ai';
import { z } from 'zod';
const MAX_DEPTH = 3;
const MAX_AGENTS = 200;
const MAX_PARALLEL = 16;
const MAX_FIXES = 1;
const MAX_VALUE = 4000;
const model = anthropic('claude-sonnet-5-5');
const worker = new ToolLoopAgent({
model,
instructions:
'If your task splits into more than five independent sub-tasks, do not do them yourself: fill ' +
'script with the body of an async JavaScript function. In it, await task(prompt) starts one ' +
'sub-agent and returns its reply as text, and await parallel(promises) runs several at once. Ask ' +
'each sub-agent for JSON so the script can filter and count in code. End with return and one small ' +
'aggregated value with counts of successes and failures, never the raw replies. Otherwise leave ' +
'script empty, do the work with your tools and fill reply.',
tools: {}, // plug in file, search and code tools: every agent in the tree is a full harness
output: Output.object({
schema: z.object({
script: z.string().describe('"" when the agent does the work itself'),
reply: z.string().describe('the result of the work, or "" when a script is written'),
}),
}),
});
const writer = new ToolLoopAgent({
model,
instructions:
'Your script ran and returned one value. Write the reply to your task from it. State the ' +
'coverage: items planned, completed and failed.',
});
type Tree = { started: number; deepest: number; leadScript: string }; // shared by the whole run
let active = 0; // at most 16 agents work at the same time
const waiting: (() => void)[] = [];
async function slot<T>(work: () => Promise<T>): Promise<T> {
while (active >= MAX_PARALLEL) await new Promise<void>((resolve) => waiting.push(resolve));
active++;
try {
return await work();
} finally {
active--;
waiting.shift()?.();
}
}
// One full agent. The lead runs at level 1; every task() in a script runs this function one level down.
async function harness(task: string, depth: number, tree: Tree): Promise<string> {
tree.deepest = Math.max(tree.deepest, depth);
const mayScript = depth < MAX_DEPTH;
let prompt = `Task: ${task}`;
if (!mayScript) prompt += '\n\nYou are at the depth limit: leave script empty and do the work yourself.';
let error = '';
for (let attempt = 0; attempt <= MAX_FIXES; attempt++) { // the script may be corrected once
const { output: move } = await slot(() => worker.generate({ prompt }));
if (!mayScript || !move.script.trim()) return move.reply;
if (depth === 1) tree.leadScript = move.script;
const spawn = async (sub: string) => { // the one primitive the script gets
if (tree.started >= MAX_AGENTS) throw new Error('agent budget spent');
tree.started++;
return harness(sub, depth + 1, tree);
};
let value: string;
try {
// replace with a real sandbox (isolate, container, no network): a model wrote this code
const main = new Function('task', 'parallel', `return (async () => {\n${move.script}\n})();`);
const returned: unknown = await main(spawn, (jobs: Promise<unknown>[]) => Promise.all(jobs));
value = (JSON.stringify(returned) ?? 'null').slice(0, MAX_VALUE);
} catch (e) {
error = String(e);
prompt = `Task: ${task}\n\nYour script:\n${move.script}\n\nIt failed with: ${error}\nCorrect it.`;
continue;
}
// the sub-agents' results stayed in the script: one value goes back to the agent
const { text } = await slot(() => writer.generate({ prompt: `Task: ${task}\n\nYour script returned:\n${value}` }));
return text;
}
return `The script failed twice. Last error: ${error}`;
}
export async function run(task: string) {
const tree: Tree = { started: 0, deepest: 1, leadScript: '' };
const answer = await harness(task, 1, tree);
return { answer, script: tree.leadScript, subAgents: tree.started, deepestLevel: tree.deepest };
}
Scripts are JavaScript here. new Function is a placeholder: run them in an isolate or a container with no network. Give the worker real tools.
Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.
What goes wrong
- A script that returns every record pulls all the results back into the lead's context. Return an aggregate and the counts.
- Free-text replies cannot be filtered in code. Fix the reply format in the script and count the replies that do not match it.
- Each sub-agent can write files and run commands. Give each one its own workspace and only the tools its sub-task needs.
- Recursion multiplies cost. Without limits on depth and on total agents, one misjudged loop starts thousands of runs.
- The script is written by a model and then executed. Run it in a sandbox, and treat a script that does not parse as a normal case.
Chain it
Its result can feed
- Reflection direct
Treat the harness's answer or report as the existing draft to improve, and keep its coverage figures as facts the rewrite must not contradict.
- Chain of Verification conditional
Condition: Build the link only when A's payload is an answer rather than a document-style report.
- Debate conditional
Condition: Build the link only when A's payload is an answer rather than a document-style report.
- Constitutional Critique direct
Treat the harness's answer or report as the text to check rule by rule against the constitution, fixing only the rules it fails.
- Textual Backpropagation direct
Give the harness's answer or report to the first pipeline step as the existing result to improve, and keep the best evaluated version.