Workflow:Openai Openai agents python Multi Agent Handoff
| Knowledge Sources | |
|---|---|
| Domains | AI_Agents, Multi_Agent, Orchestration |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
End-to-end process for building a multi-agent system where a triage agent delegates user requests to specialized agents via the handoff mechanism.
Description
This workflow demonstrates the SDK's multi-agent orchestration pattern. Multiple agents are defined with distinct responsibilities (e.g., FAQ handling, booking, general triage). A triage agent is configured with handoffs pointing to specialized agents. When the triage agent determines a user's request matches a specialist's domain, it invokes a handoff tool call. The Runner automatically transfers control to the target agent, which continues the conversation. Agents can hand back to the triage agent or to other agents, forming a directed graph of possible transitions. The pattern supports shared context across agents, handoff callbacks for initialization logic, and conversation history management during transfers.
Usage
Execute this workflow when building a customer service system, support bot, or any application where different domains of expertise require specialized agents. The handoff pattern is ideal when a single agent cannot handle all possible user intents and you need to route requests to domain-specific agents with their own tools and instructions.
Execution Steps
Step 1: Define Specialized Agents
Create multiple Agent instances, each with focused instructions and tools for a specific domain. Each agent should have a descriptive handoff_description that helps the triage agent decide when to route to it.
Key considerations:
- Each agent has its own instructions, tools, and optional output_type
- The handoff_description is critical as it tells the triage agent what this specialist handles
- Agents can share a typed context (generic parameter) for passing data between agents
Step 2: Configure Triage Agent with Handoffs
Create the triage agent with a handoffs list containing the specialized agents. The SDK automatically generates handoff tool definitions that the triage agent's model can invoke. Use the handoff() function for advanced configuration like on_handoff callbacks.
Key considerations:
- Handoffs can be direct Agent references or configured via the handoff() helper
- on_handoff callbacks execute when a handoff occurs (e.g., to initialize context data)
- The triage agent's instructions should explain its routing responsibilities
- Use RECOMMENDED_PROMPT_PREFIX from extensions.handoff_prompt for best practices
Step 3: Set Up Bidirectional Handoffs
Add handoff references back from specialized agents to the triage agent (or other agents) to allow re-routing when a user's request changes topic or the specialist cannot handle it.
Key considerations:
- Circular handoff references are supported (agent A hands to B, B hands back to A)
- Append handoffs after initial agent creation to avoid forward reference issues
- Each agent should instruct when to hand back (e.g., "if the question is unrelated, transfer back")
Define a Pydantic model for shared context that persists across agent handoffs. Initialize it before starting the run and pass it via the context parameter. Agents and tools can read and modify this context throughout the conversation.
Key considerations:
- Context is typed via the Agent generic parameter: Agent[MyContext]
- Tools access context via RunContextWrapper[MyContext] parameter
- Context persists across handoffs within a single run
Step 5: Conversation Loop Execution
Run the multi-agent system in a loop. For each user message, call Runner.run() with the current agent, accumulated input items, and shared context. After each run, update the current agent (result.last_agent) and input items (result.to_input_list()) for the next iteration.
Key considerations:
- result.last_agent tracks which agent finished the run (may differ from the starting agent)
- result.to_input_list() returns the full conversation history for the next turn
- result.new_items contains HandoffOutputItem entries showing agent transitions
- Wrap each iteration in a trace() context manager for observability
Step 6: Output Processing
Process the run result by iterating over new_items. Identify MessageOutputItem for agent messages, HandoffOutputItem for agent transitions, ToolCallItem for tool invocations, and ToolCallOutputItem for tool results. Display or log each item type appropriately.
Key considerations:
- Each item has an agent property identifying which agent generated it
- HandoffOutputItem has source_agent and target_agent properties
- Use ItemHelpers.text_message_output() to extract text from message items