The problem: routing document output through an orchestrator
We were building a multi-agent pipeline on Anthropic’s Claude Agent SDK to generate long, structured business documents output running into many thousands of words, following a precise organisational template, and feeding directly into downstream systems. Correctness and completeness were not optional.
The SDK offers two ways to define an agent. ClaudeAgentOptions is the top-level construct: it owns its own context window, supports the output_format parameter for schema-constrained output, and its response goes directly to the caller. AgentDefinition is the sub-agent construct, used inside a ClaudeAgentOptions instance to delegate focused tasks it runs in an isolated context, but only its final message returns to the parent, and it does not support output_format at all.
Our initial design used the classic pattern: an orchestrator (ClaudeAgentOptions) delegating to specialist sub-agents (AgentDefinition), each generating one type of document. It looked correct, and it worked in early testing. It broke once we moved to full-length documents in production.
Figure 1 – In the sub-agent model, output always passes back through the orchestrator before reaching the user.
2. Why it broke?
The orchestrator summarised the output
The sub-agent generated the document correctly we verified this by inspecting its output directly. But the orchestrator, receiving that document as a tool result inside its own growing context, reasoned about it before replying rather than passing it through untouched. Anthropic’s own documentation confirms this: the parent receives the sub-agent’s message verbatim but may summarise it, and preserving it verbatim requires an explicit instruction. That instruction helped, but was unreliable in longer sessions.
Schemas didn’t propagate to sub-agents
Structured output, the output_format parameter that enforces a JSON schema, is only available on ClaudeAgentOptions, not on AgentDefinition. Even when the orchestrator’s prompt described the required schema in detail, that constraint never reached the sub-agent doing the actual generation. Schema compliance was low; prompt-based instructions are best-effort, not enforcement.
Token costs compounded
Every sub-agent tool call adds to the session’s token count, and the orchestrator carries its full history plus every sub-agent description on every turn. Add in automatic retries when the orchestrator judged an output incomplete, and per-document cost ran well above our original estimate, consistent with Anthropic’s own guidance that multi-agent systems can cost several times more than single-agent equivalents on sequential tasks.
| Root cause: The orchestrator is a language model. It reasons about content passing through it, it doesn’t just relay it. For output that must reach the user completely intact, routing it through any intermediate LLM is the risk, not the prompt wording. |
3. The fix: independent specialist agents
The fix was to remove the orchestrator from the output path. Rather than sub-agents nested inside one orchestrator, we run several independent, top-level ClaudeAgentOptions agents: a lightweight planning agent that only routes requests, and specialist agents that generate documents and return them straight to the user. This is not Anthropic’s experimental Agent Teams feature, it’s a simpler pattern built from standard SDK primitives.
Because each specialist is a top-level agent, it has full access to output_format, so schema compliance is enforced rather than requested. The planning agent never sees document content only a small routing registry describing which specialist handles which request so its context stays small and cheap regardless of document size. We also moved schema definitions from verbose JSON into compact Markdown templates within each specialist’s system prompt, which further reduced token overhead.
Figure 2 – The planning agent only routes. Document content and output bypass it entirely.
4. Sub-agent vs. independent specialist
| Dimension | Sub-Agent (AgentDefinition) | Independent Specialist (ClaudeAgentOptions) |
| Output path | Through the orchestrator, which may summarise | Directly to the user |
| Structured output | Not supported | Fully supported (output_format) |
| Relative token cost | Substantially higher | Substantially lower |
| Output completeness | Inconsistent on long documents | Consistently complete |
| Best suited for | Isolated, parallel tasks | Sequential, schema-constrained pipelines |
The result: token usage and cost per document both dropped substantially, output became consistently complete, and schema compliance became reliable without changing the underlying model, only the architecture around it. Exact figures are specific to our production system and aren’t disclosed here, since they depend heavily on document type and organisational template.
5. When to use which
Sub-agents are still the right tool for genuinely parallel, independent work running several research threads at once, or a code review split across security, style, and test-coverage checks where the orchestrator aggregating a few short summaries is exactly the right behaviour.
Independent specialist agents are the right choice when output must reach the user completely intact and schema-compliant, when the task is sequential, and when document size makes orchestrator-mediated output risky. They cost more upfront engineering you build your own routing and state handoff but for pipelines where correctness isn’t negotiable, that cost is worth paying.
| Design principle: If the right thing for the orchestrator to do with an output is examine it and respond thoughtfully, use sub-agents. If the right thing is to pass it through untouched, change the architecture don’t try to prompt the orchestrator into passivity. |
6. About 47Billion
Building production AI? 47Billion can help.
The engineering patterns described in this post came from work on live, production agent systems. At 47Billion, we design and build multi-agent AI pipelines for enterprise teams from initial architecture through production operations. If you are running into similar problems around token costs, schema compliance, or context management in your own agent systems, we would be glad to talk.
Read more at 47billion.com.
7. Key takeaways
1. Sub-agents (AgentDefinition) always route output through the orchestrator. For large documents that must arrive intact, that routing is the source of loss.
2. Structured output (output_format) only works on top-level ClaudeAgentOptions agents, not on sub-agents. If schema compliance matters, the generating agent can’t be a sub-agent.
3. Token costs in sub-agent pipelines compound through tool calls, accumulated orchestrator context, and retries. Measure real cost on full-size documents, not small test cases.
4. Independent specialist agents cost more to build up front but are the right call whenever document correctness and schema compliance are non-negotiable.
