Principle:Openai Openai agents python Bidirectional Handoffs
| Knowledge Sources | |
|---|---|
| Domains | AI_Agents, Multi_Agent, Orchestration, Handoffs |
| Page Type | Pattern Doc |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Bidirectional Handoffs is the theory of circular handoff patterns in the OpenAI Agents Python SDK, where agents can delegate back and forth between each other. In complex multi-agent systems, sub-agents may need to hand back to the triage agent or to peer agents, creating a bidirectional (or multi-directional) delegation graph rather than a simple tree.
Core Concepts
Circular Handoff Graphs
In a simple handoff configuration, the triage agent delegates to specialists, and the conversation ends when the specialist produces a final answer. However, many real-world scenarios require more complex routing:
- A billing specialist realizes the question is actually about account settings and needs to route back to triage.
- A technical support agent resolves the immediate issue but the user asks a follow-up question in a different domain.
- An escalation agent needs to hand back to the original agent after performing a privileged operation.
Bidirectional handoffs address these needs by allowing agents to reference each other in their handoffs lists, creating cycles in the delegation graph (e.g., Agent A can hand to Agent B, and Agent B can hand back to Agent A).
Python Mutable List Semantics
The pattern relies on Python's mutable list semantics. The handoffs field on an Agent is a standard Python list. Because lists are mutable and passed by reference, you can:
- Create all agents first with their initial handoff lists.
- After creation, append additional handoffs to create back-references.
This solves the forward-reference problem -- you cannot reference an agent that has not been created yet in the initial constructor, but you can append it to the handoffs list after both agents exist.
Run Loop Cycle Handling
The SDK's run loop handles cycles in the handoff graph naturally. When a handoff occurs, the run loop simply switches the active agent and continues processing. There is no special cycle detection or prevention. Instead, the max_turns parameter on Runner.run() serves as a safety mechanism to prevent infinite loops:
- Each model invocation counts as one turn.
- When
max_turnsis reached, the run terminates with aMaxTurnsExceededexception. - This provides a natural bound on how many times agents can hand back and forth.
Escalation Workflows
A common use of bidirectional handoffs is the escalation pattern:
- A specialist agent encounters a situation it cannot handle.
- It hands back to the triage agent with context about what was attempted.
- The triage agent routes to a different specialist or handles the request itself.
This pattern is especially powerful when combined with shared context (RunContextWrapper), where each agent can annotate the context with information about what it tried, enabling the next agent to avoid redundant work.
Direct Agent References vs. handoff() Helper
Bidirectional handoffs can be established in two ways:
- Direct agent references: Simply append the agent object to the handoffs list. The SDK auto-converts
Agentobjects toHandoffobjects internally. - Using handoff() helper: For more control (custom tool names, callbacks, input filters), use the
handoff()function to create configuredHandoffobjects before appending.
Both approaches work equally well for establishing bidirectional patterns.
Source Reference
Source: src/agents/handoffs/__init__.py:L211-320 (reuses handoff()), src/agents/agent.py:L252 (handoffs field)
Import:
from agents import Agent, handoff
Related Pages
- Implementation:Openai_Openai_agents_python_Bidirectional_Handoff_Pattern
- Implementation: Openai_Openai_agents_python_Bidirectional_Handoff_Pattern -- concrete code patterns for establishing bidirectional handoffs.
- Principle: Openai_Openai_agents_python_Handoff_Configuration -- foundational theory of handoff configuration.
- Implementation: Openai_Openai_agents_python_Handoff_Helper -- the
handoff()function used to create handoff objects. - Workflow: Openai_Openai_agents_python_Multi_Agent_Handoff -- end-to-end workflow demonstrating multi-agent handoff patterns.