Principle:Openai Openai agents python Bidirectional Handoffs

Knowledge Sources	OpenAI Agents Python Agents SDK Docs
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:

1. Create all agents first with their initial handoff lists.
2. 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_turns is reached, the run terminates with a MaxTurnsExceeded exception.
• 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:

1. A specialist agent encounters a situation it cannot handle.
2. It hands back to the triage agent with context about what was attempted.
3. 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 Agent objects to Handoff objects internally.
• Using handoff() helper: For more control (custom tool names, callbacks, input filters), use the handoff() function to create configured Handoff objects 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.

GitHub URL

Source: handoffs/__init__.py