Overview
The Handoffs feature lets you:- Configure agents that can receive handoffs from the current agent
- Build router patterns where a central agent delegates to specialists
- Share conversation context when handing off
- Pin each handoff target to a specific version or use $LATEST
- Add descriptions to help the model decide when to hand off
Handoffs vs Agent as a Tool
| Feature | Handoffs | Agent as a Tool |
|---|---|---|
| Control flow | Transfers control entirely to target agent | Parent agent continues after sub-agent returns |
| Response | Target agent responds directly to user | Sub-agent result returned to parent agent |
| Conversation history | Shared with target agent | Sub-agent runs without history |
| Use case | Router patterns, specialist delegation | Tool-like sub-tasks, parallel processing |
Runtime Behavior
When an agent hands off to another agent:- Shared history – The target agent receives the conversation history, providing continuity for the user.
- Direct response – The target agent’s response goes directly to the user; the original agent does not process it further.
- Full transfer – Control is transferred to the handoff target; the original agent’s run ends.
Configuring Handoffs
- Open your agent in the Agent Builder and go to the Handoffs tab.
- Click Add Handoff to add a new handoff target.
- For each handoff entry:
- Agent – Select the target agent from the dropdown (other agents in the project; current agent is excluded).
- Version – Choose $LATEST (always use the latest version) or a specific version.
- Description – Optional but recommended. Describe when this handoff should be used; this helps the model decide when to hand off.
- Add more handoffs by clicking Add Handoff again.
- Remove a handoff with the delete (trash) icon on its row.
- Save your agent configuration.