Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

06_HANDOFFS

Shared from "OpenAI Agents Python" on Inkdown

Handoffs - Comprehensive Deep Dive

Overview

Handoffs are the mechanism that enables multi-agent workflows in the OpenAI Agents SDK. A handoff occurs when one agent delegates a task to another agent. Think of handoffs as "transfer of control" or "referral" - just like a doctor might refer you to a specialist, agents can hand off tasks to other specialized agents.

Core Concepts

What is a Handoff?

A handoff is when an agent decides that another agent is better suited to handle the current task and transfers control to that agent. The handoff includes:

  • The target agent (who to hand off to)
  • The context/information to pass along
  • Optional filtering of what information to pass
  • Optional custom logic for the handoff
Why Handoffs Matter
  1. Specialization - Different agents can specialize in different domains
  2. Modularity - Build complex workflows from simple, focused agents
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • Efficiency - Route tasks to the most capable agent
  • Scalability - Add new capabilities by adding new agents
  • Clarity - Clear separation of concerns
    • Handoff vs Agent as Tool

    Handoffs and "agents as tools" both involve multiple agents, but they work differently:

    Handoffs:

    • The new agent receives the full conversation history
    • The new agent takes over the conversation
    • The original agent is no longer involved
    • Good for: Domain specialization, expertise routing

    Agent as Tool:

    • The new agent receives generated input (not full history)
    • The new agent runs as a tool and returns
    • The original agent continues the conversation
    • Good for: Subtasks, specific queries, calculations

    Handoff Class

    Handoff Structure
    Python
    Creating Handoffs

    The simplest way is using the handoff() helper:

    Python

    What happens:

    1. The handoff() function creates a Handoff object
    2. It generates a tool name (e.g., transfer_to_specialist)
    3. It generates a tool description
    4. It creates an empty JSON schema (no arguments by default)
    5. It sets up the invocation function to return the specialist agent

    Handoff Configuration

    Custom Tool Name

    Override the default tool name:

    Python
    Custom Tool Description

    Override the default description:

    Python
    Handoff with Input

    Pass structured input to the handoff:

    Python

    How it works:

    1. The LLM generates JSON arguments matching HandoffInput
    2. The arguments are validated against the schema
    3. The on_handoff function is called with the validated input
    4. The function can perform side effects (logging, tracking, etc.)
    5. The specialist agent is still returned
    Handoff Without Input

    Handoff without structured input (simpler):

    Python
    Input Filter

    Filter what information is passed to the next agent:

    Python

    HandoffInputData structure:

    Python
    Nested Handoff History

    Control how conversation history is passed:

    Python

    Options:

    • None (default) - Use run-level configuration
    • True - Collapse history into a single summary message
    • False - Pass full conversation history

    When to use:

    • True - For deep handoff chains to reduce token usage
    • False - When the next agent needs full context
    Dynamic Enablement

    Handoffs can be dynamically enabled or disabled:

    Python

    Use cases:

    • Feature flags
    • User tier-based access
    • Context-dependent availability
    • A/B testing

    Handoff Execution Flow

    Complete Handoff Flow
    Python

    Handoff History Management

    Default Behavior (Full History)

    By default, the full conversation history is passed to the next agent:

    Python

    Pros:

    • Full context preserved
    • No information loss
    • Agent can reference earlier conversation

    Cons:

    • Higher token usage
    • Potential for confusion in deep chains
    • Slower for long conversations
    Nested History (Collapsed)

    When nest_handoff_history=True, history is collapsed:

    Python

    Pros:

    • Lower token usage
    • Cleaner context for deep chains
    • Faster for long conversations

    Cons:

    • Some detail lost in summary
    • Agent can't reference specific earlier messages
    • Depends on quality of summary
    Custom History Mapping

    Provide a custom function to transform history:

    Python
    Input Filter for Fine-Grained Control

    Use input filters for precise control:

    Python

    Handoff Patterns

    1. Triage Pattern

    One agent routes to specialists:

    Python

    When to use:

    • Customer support systems
    • Help desk workflows
    • Multi-domain support
    2. Supervisor Pattern

    One agent supervises and delegates:

    Python

    When to use:

    • Complex task breakdown
    • Project management
    • Quality assurance
    3. Escalation Pattern

    Escalate from general to specialist:

    Python

    When to use:

    • Tiered support systems
    • Escalation workflows
    • Progressive problem solving
    4. Collaboration Pattern

    Agents collaborate on different aspects:

    Python

    When to use:

    • Content creation workflows
    • Multi-stage processes
    • Quality assurance pipelines
    5. Context Switching Pattern

    Switch context based on user request:

    Python

    When to use:

    • General-purpose assistants
    • Multi-domain bots
    • Context-aware routing

    Handoff and Sessions

    Session Continuity

    Handoffs maintain session continuity:

    Python
    Session History with Handoffs

    The session tracks which agent generated each item:

    Python
    Compaction with Handoffs

    For long conversations with many handoffs:

    Python

    Handoff Tracing

    Handoff Spans

    Handoffs create trace spans:

    Python
    Handoff Events

    Handoffs emit events during streaming:

    Python

    Handoff Best Practices

    1. Clear Handoff Descriptions

    Write clear descriptions for the LLM:

    Python
    2. Appropriate Handoff Granularity

    Design handoffs at the right level:

    Python
    3. Use Input Filters for Context

    Use input filters to control context:

    Python
    4. Handle Handoff Failures

    Handle cases where handoffs might fail:

    Python
    5. Test Handoff Paths

    Test all possible handoff paths:

    Python

    Common Handoff Issues

    1. Handoff Loops

    Problem: Agents hand off back and forth infinitely.

    Solution: Use handoff history tracking:

    Python
    2. Lost Context

    Problem: Important context is lost in handoff.

    Solution: Use appropriate history management:

    Python
    3. Ambiguous Handoffs

    Problem: LLM unsure which handoff to use.

    Solution: Clear descriptions and maybe input types:

    Python
    4. Too Many Handoffs

    Problem: Excessive handoffs slow down response.

    Solution: Consolidate similar agents:

    Python

    Handoff vs Agent as Tool Decision

    When to Use Handoffs

    Use handoffs when:

    • The new agent needs full conversation context
    • The new agent takes over the conversation
    • Domain expertise routing is needed
    • Long-running specialized tasks
    When to Use Agent as Tool

    Use agent as tool when:

    • The subtask is self-contained
    • The parent agent should continue the conversation
    • The subtask returns specific data
    • Parallel execution of multiple subtasks
    Example Comparison

    Handoff:

    Python

    Agent as Tool:

    Python

    Summary

    Handoffs enable powerful multi-agent workflows. Key takeaways:

    1. Handoffs transfer control from one agent to another
    2. handoff() helper creates handoff objects
    3. Tool name/description can be customized
    4. Structured input allows passing data to handoffs
    5. Input filters control what information is passed
    6. Nested history collapses conversation to save tokens
    7. Dynamic enablement allows context-dependent handoffs
    8. Full history preserves complete context
    9. Collapsed history reduces token usage
    10. Custom mappers provide fine-grained control
    11. Triage pattern routes to specialists
    12. Supervisor pattern delegates tasks
    13. Escalation pattern moves up tiers
    14. Collaboration pattern chains agents
    15. Context switching changes domains
    16. Sessions maintain continuity across handoffs
    17. Tracing tracks handoff events
    18. Clear descriptions help the LLM choose correctly
    19. Appropriate granularity avoids too many agents
    20. vs Agent as Tool - different use cases

    Handoffs are essential for building sophisticated multi-agent systems with clear separation of concerns.