🤖 OpenAI Agents SDK & Multi-Agent Handoff Patterns

The OpenAI Agents SDK provides an ergonomic framework for orchestrating single-agent ReAct loops and multi-agent topologies (Swarm pattern).

🏗️ Core Primitives

                             ┌────────────────┐
                             │     Runner     │ (Executes ReAct Loop)
                             └───────┬────────┘
                                     │
                 ┌───────────────────┴───────────────────┐
                 ▼                                       ▼
       ┌───────────────────┐                   ┌───────────────────┐
       │   Parent Agent    │─ ─ ─ Handoff ─ ─ ─►│ Specialist Agent  │
       │ (Triage / Router) │ (handoff_descr.)  │ (Domain Expert)   │
       └─────────┬─────────┘                   └─────────┬─────────┘
                 │                                       │
                 ▼                                       ▼
       [@function_tool A]                      [@function_tool B]

1. Defining Tools (@function_tool)

The @function_tool decorator automatically inspects Python type annotations and docstrings to generate JSON schemas for the model:

from agents import function_tool

@function_tool
def check_inventory(sku: str, warehouse_id: str = "main") -> str:
    """
    Checks real-time inventory stock for a given product SKU in a specific warehouse.
    
    Args:
        sku: The unique product stock keeping unit ID.
        warehouse_id: The target warehouse identifier (default: 'main').
    """
    # Tool execution logic
    stock = 42
    return f"SKU {sku} has {stock} units available in {warehouse_id}."

2. Multi-Agent Handoffs (handoff_description)

Handoffs transfer dialogue ownership from a primary triage agent to a specialist agent.

from agents import Agent, Runner

# 1. Specialist Agent
billing_agent = Agent(
    name="Billing Specialist",
    instructions="You handle invoice disputes, refunds, and subscription upgrades.",
    tools=[check_inventory],
    handoff_description="Handles all billing issues, payments, refunds, and invoice inquiries."
)

# 2. Primary Triage Agent
triage_agent = Agent(
    name="Customer Support Triage",
    instructions="Determine customer intent. If their request involves billing or refunds, hand off to the Billing Specialist.",
    handoffs=[billing_agent]
)

# 3. Runner Orchestration
result = Runner.run_sync(triage_agent, "I need a refund for my last invoice!")
print(result.final_output)

3. Delegation Topologies: Handoffs vs. Manager Pattern

4. Guardrails & Tripwires

Enforce safety policies before inputs reach the agent or before outputs are returned to users.

from agents import GuardrailFunctionOutput

def validate_input_guardrail(ctx, agent, input_message) -> GuardrailFunctionOutput:
    forbidden_terms = ["system_prompt", "ignore instructions", "jailbreak"]
    if any(term in input_message.lower() for term in forbidden_terms):
        return GuardrailFunctionOutput(
            tripwire_triggered=True,
            output_info="Security Violation: Input flagged by safety guardrail."
        )
    return GuardrailFunctionOutput(tripwire_triggered=False, output_info=input_message)