A transfer hands an in-progress conversation from one agent to another. The LLM chooses a specialist by calling a transfer tool; that specialist inherits the execution context and takes over the response. Use it when a request belongs to a clear domain expert, rather than when a coordinator must gather and synthesize several expert results. section 9.2 section 9.5
Table 9.1 Comparison of three collaboration patterns
| Pattern |
Order decision |
Context sharing |
Best use case |
|---|---|---|---|
| Workflow |
Developer |
Developer’s choice |
When the workflow is predictable |
| Agent as Tool |
LLM |
Isolated |
When synthesizing multiple expert results |
| Transfer |
LLM |
Shared |
When domains are clearly separated |
Compare who chooses the next agent and whether that agent receives shared or isolated context. Transfer combines LLM-selected routing with shared context. section 9.2
This differs from Agent as Tool: a tool-wrapped specialist returns a result to the orchestrator, which remains responsible for follow-up questions. After a transfer, the specialist answers follow-ups directly and can see the earlier conversation. section 9.5.1
A minimal implementation extends an existing Python Agent and ExecutionContext:
- Compose an agent tree with sub_agents and parent references. Available targets are children, the parent, and optionally siblings; disallow_transfer_to_peers removes siblings from an agent’s choices. section 9.5.3
- Create a transfer_to_agent tool for the current agent’s targets at the start of run(), and store it in context.transfer_tools. Add that tool both to the LLM request and to the tools available for execution. section 9.5.2 section 9.5.5
- When the tool runs, it sets context.transfer_to to the target’s name. After the step, run() finds that agent, clears the flag, and calls the target’s run() with the same context and no new user input. The previous agent exits its loop; the result remains in context.final_result. section 9.5.5
Routing to a specialist
A router with math and search sub-agents can send a calculation request to the math specialist. If the math specialist later needs search, it can transfer to its sibling unless peer transfers are disabled. In a support conversation, the equivalent handoff lets technical support see the customer’s earlier messages and answer the next question directly. section 9.5.3 section 9.5.1
The tree constrains possible handoffs: a supervisory structure keeps routing with one router, while hierarchical or peer-enabled structures allow different paths. Validate sub-agent names and parent assignments when composing the tree, and check target lookup when debugging a handoff: the execution loop calls the next agent only if the named agent is found. section 9.5.3 section 9.5.5
