Context engineering → Context isolation (subagents get their own window)
What it is
A single agent that does everything accumulates every tool result, every retrieved document, every intermediate draft in one window. By step 30 it is expensive, slow, distracted, and prone to confusing old observations with current state (failure modes: poisoning, distraction, confusion, clash).
Context isolation splits work: the orchestrator keeps a small, clean window (goal, plan, summaries of results) and dispatches subagents, each started with a fresh window containing only what its subtask needs — a narrow instruction, the relevant inputs, and a small tool set. The subagent returns a compact, structured result (not its whole transcript). The orchestrator's window grows by the size of the result, not the size of the work.
orchestrator window: [goal][plan][result A: 300 tok][result B: 200 tok] ...
subagent A window: [task A][inputs A][tool calls...][observations 20k tok] → returns 300 tok
subagent B window: [task B][inputs B][...] → returns 200 tok
This is the context-engineering rationale for the orchestrator/subagent pattern (orchestrator / subagent) and fan-out (fan-out / fan-in).
How to implement
- Define the subtask contract: input schema, output schema (small, structured), success criteria, tool allow-list, model tier, budget (tokens/steps/time) (task decomposition).
- Construct the subagent's context from scratch: its own system prompt (cached), the task, the inputs it needs — not the orchestrator's history. Pass IDs/handles for large inputs rather than the content, and let the subagent fetch what it needs.
- Run the subagent with its own loop (single agent loop), its own budgets, its own compaction.
- Return a structured result with provenance (chunk IDs, tool call IDs, a trace ID) so the orchestrator can cite and audit without seeing the transcript.
- Persist the subagent transcript in the trace store (observability & tracing) for debugging, not in the orchestrator's window.
- Orchestrator integrates results (dedupe, conflict resolution, synthesis) and decides next steps.
- Handle failure as a structured result (
status: failed, reason), never as raw error spew into the orchestrator context.
Small example
from pydantic import BaseModel
class ReviewTask(BaseModel):
doc_id: str; version: int; question: str
class ReviewResult(BaseModel):
doc_id: str; status: str # "ok" | "failed" | "not_relevant"
findings: list[dict] # [{claim, chunk_ids}]
summary: str # ≤ 120 words
trace_id: str; tokens_used: int
SUB_SYSTEM = "You review a single document for the question. Use search_doc to find passages. Return findings with chunk ids. Be terse."
def run_subagent(task: ReviewTask, budget_tokens=30_000, max_steps=12) -> ReviewResult:
trace = new_trace("doc_review", task.doc_id)
ctx = [{"role": "user", "content": f"<task>{task.model_dump_json()}</task>"}] # fresh window: no orchestrator history
tools = [SEARCH_DOC_TOOL(task.doc_id, task.version)] # narrow tool set, pre-bound to this doc
result = agent_loop(system=SUB_SYSTEM, messages=ctx, tools=tools, model=TIER["fast"],
budget_tokens=budget_tokens, max_steps=max_steps, output_schema=ReviewResult, trace=trace)
store_transcript(trace, result.transcript) # trace store, not the orchestrator
return result.output if result.ok else ReviewResult(doc_id=task.doc_id, status="failed",
findings=[], summary=result.error[:200], trace_id=trace.id, tokens_used=result.tokens)
def orchestrate(question, doc_ids):
results = parallel_map(lambda d: run_subagent(ReviewTask(doc_id=d, version=current(d), question=question)), doc_ids)
compact = "\n".join(r.model_dump_json(exclude={"trace_id", "tokens_used"}) for r in results) # small
return llm("synthesize", SYNTH_SYSTEM, [{"role": "user", "content": f"<question>{question}</question>\n<results>{compact}</results>"}])
Pros
- Orchestrator stays small and cheap; its reasoning quality holds over long tasks.
- Parallelism: isolated windows can run concurrently (fan-out / fan-in).
- Right-sizing: each subtask gets its own model tier and tool set; cheaper and safer (least privilege, excessive agency).
- Cache-friendly: each subagent's system prompt is a stable prefix (prompt caching of static prefixes).
- Debuggable: per-subagent traces with clear inputs/outputs.
Cons
- Information loss at the boundary: the subagent doesn't know what the orchestrator knows unless told; the orchestrator doesn't see nuance the subagent discarded. Contracts must specify what to pass.
- Coordination overhead: more calls, more schemas, more failure handling.
- Duplicate work across subagents (each re-fetches the same context) — mitigate with shared caches/handles.
- Conflicting results need resolution logic in the orchestrator.
When to use
- Tasks with clearly separable subtasks (per-document review, per-section extraction, per-source research).
- Long agent runs where the orchestrator's window would otherwise balloon.
- When subtasks need different tools/models/permissions.
When NOT to use
- Short, sequential tasks with strong coupling between steps — the handoff costs more than it saves.
- When the subtask needs almost all of the orchestrator's context anyway (you'd copy the window; no isolation gained).
- Very latency-sensitive interactions with a single hop.
Production at scale
Contracts are the product. Input/output schemas, budgets, tool allow-lists, and success criteria per subagent type, versioned (prompt versioning & evaluation). A subagent that returns free text reintroduces pollution.
Pass handles, not payloads. Large inputs (documents, datasets) are referenced by ID; subagents fetch via tools with ACL enforcement (authentication & authorization). Keeps windows small and permissions explicit.
Budgets per subagent (tokens, steps, time, dollars) enforced by the runtime (cost & step budgets); a runaway subagent must not sink the whole run.
Partial failure: orchestrator proceeds with successful results and reports failures explicitly (fan-out / fan-in). Result ordering deterministic (sort by doc_id), so runs are reproducible.
Shared read-through caches (retrieval results, parsed documents, tool outputs keyed by content hash) prevent N subagents from paying N times for the same fetch.
Tracing: one run trace with child spans per subagent; the orchestrator's log references child trace IDs; cost roll-up per run and per subagent type (observability & tracing).
Security: subagents run with the minimum tools and a token scoped to the subtask; an injection in one document can't reach the orchestrator's tools (prompt-injection defence, excessive agency).
Evals: evaluate subagent types independently (their contracts make this easy) and the orchestration end-to-end (agent evals).
Prod checklist
- Subagent contracts: input/output schemas, budgets, tools, tier, success criteria; versioned
- Fresh window per subagent; inputs by handle; no orchestrator history copied
- Structured results with provenance; transcripts in the trace store
- Runtime-enforced budgets per subagent; structured failure results
- Deterministic result ordering; partial-failure handling in the orchestrator
- Shared caches for repeated fetches
- Least-privilege tools/tokens per subagent
- Per-subagent-type evals + end-to-end evals
Metrics to watch
| Metric | Why |
|---|---|
| Orchestrator window tokens per step | Isolation working |
| Subagent tokens/steps/cost per type | Budgets and right-sizing |
| Subagent failure rate by reason | Contract/tool problems |
| Duplicate fetch rate | Cache effectiveness |
Related
- Task decomposition, Orchestrator/subagent, Fan-out/fan-in
- Context failure modes — what isolation prevents
- Cost & step budgets
- Excessive agency — least privilege per subagent
- Observability — child traces