Principle:Openai Openai agents python Handoff Configuration

Knowledge Sources	OpenAI Agents Python Agents SDK Docs
Domains	AI_Agents, Multi_Agent, Orchestration, Handoffs
Last Updated	2026-02-11 15:00 GMT

Overview

Handoff Configuration is the theory of agent-to-agent delegation in the OpenAI Agents Python SDK. In a multi-agent system, a triage agent can delegate tasks to specialized sub-agents using handoff objects. The handoff() helper function creates Handoff objects that appear as callable tools to the LLM, enabling the model to transfer control between agents during a run.

Core Concepts

Separation of Concerns

Handoffs enable a clean separation of concerns in multi-agent architectures. Rather than building a single monolithic agent that handles every domain, the system is composed of specialized agents, each responsible for a distinct area of expertise (e.g., billing, technical support, account management). The triage agent acts as a router, determining which specialist is best suited to handle the current user request.

This pattern provides several advantages:

• Each agent can have focused, domain-specific instructions that reduce prompt complexity.
• Tools can be scoped to only the agents that need them, reducing the LLM's decision space.
• Agents can be developed, tested, and iterated on independently.
• The handoff_description field on each agent informs the triage agent about what the specialist handles.

Handoffs as Tools

When handoffs are configured on an agent, the SDK automatically generates tool definitions that the LLM can invoke. For example, if an agent has a handoff to a billing agent, the LLM sees a tool called transfer_to_billing (or a custom name via tool_name_override). When the LLM calls this tool, the run loop intercepts the call and switches the active agent to the target agent.

The key mechanism is:

1. The SDK converts each Handoff into a tool schema that is included in the model's tool list.
2. The LLM decides when to invoke a handoff tool based on the tool description and current conversation.
3. The run loop detects the handoff tool call, executes any configured callback, and switches the active agent.
4. The new agent continues the conversation from where the previous agent left off.

The on_handoff Callback

An optional on_handoff callback can be attached to a handoff. This callback runs when the handoff is invoked, before the new agent begins processing. Callbacks can be used for:

• Initializing state in the shared context for the target agent.
• Logging or analytics when agent transitions occur.
• Validating preconditions before allowing the handoff to proceed.

The callback can optionally accept a typed input parameter, allowing the LLM to pass structured data (e.g., a reason string or category) when invoking the handoff.

Conversation History Filtering

The input_filter parameter controls what conversation history the target agent receives after a handoff. By default, the new agent sees the full conversation history. However, in some cases it is desirable to:

• Remove previous tool call results that are irrelevant to the new agent.
• Summarize earlier conversation turns to reduce token usage.
• Strip sensitive information before passing context to a less-privileged agent.

The input_filter receives a HandoffInputData object and returns a modified version, giving full control over the conversation state that the new agent sees.

Dynamic Enablement

The is_enabled parameter controls whether a handoff is available to the LLM at any given time. It can be a static boolean or a callable that receives the run context and agent, allowing dynamic decisions about whether a handoff should be offered based on runtime conditions.

Source Reference

Source: src/agents/handoffs/__init__.py:L211-320

Import:

from agents import handoff, Handoff

Related Pages

• Implementation:Openai_Openai_agents_python_Handoff_Helper
• Implementation: Openai_Openai_agents_python_Handoff_Helper -- full signature and usage of the handoff() helper function.
• Principle: Openai_Openai_agents_python_Bidirectional_Handoffs -- theory of circular handoff patterns.
• Workflow: Openai_Openai_agents_python_Multi_Agent_Handoff -- end-to-end workflow for building multi-agent systems.

GitHub URL

Source: handoffs/__init__.py