Handoffs and Guardrails in the OpenAI Agents SDK

Build a triage agent that hands work to specialists, and wrap the entry agent with input/output guardrails so off-policy traffic fails closed.

Summary

Use Agent.handoffs (or handoff(...)) so the model transfers control via synthetic tools, and attach @input_guardrail / @output_guardrail (plus tool guardrails) so policy checks raise tripwire exceptions when they fail.

Recipe

1. Define specialist agents with clear instructions and optional handoff_description.
2. Put those specialists on a triage agent's handoffs list (or wrap with handoff() for filters and callbacks).
3. Add recommended handoff prompt guidance so the model understands transfer tools.
4. Implement input guardrails for the first agent in the chain (cheap model checks work well).
5. Implement output guardrails on the agent that produces the final output when needed.
6. Use tool guardrails for per-tool checks on custom function_tool calls inside the workflow.
7. Catch InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered at the host boundary.
8. Prefer blocking input guardrails (run_in_parallel=False) when you must avoid tool side effects on bad input (verify API for your version).

Working Example

import asyncio
from pydantic import BaseModel
from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    Runner,
    function_tool,
    handoff,
    input_guardrail,
    RunContextWrapper,
)
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
 
# --- tools for specialists ---
@function_tool
def lookup_order(order_id: str) -> str:
    """Return a demo order status string."""
    return f"Order {order_id}: shipped, ETA 2 days"
 
# --- specialists ---
billing_agent = Agent(
    name="Billing agent",
    handoff_description="Invoices, charges, payment methods",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
    You handle billing questions. Be precise about money and dates.""",
)
 
refund_agent = Agent(
    name="Refund agent",
    handoff_description="Refunds, returns, chargebacks",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
    You handle refund eligibility and next steps. Never invent policy.""",
    tools=[lookup_order],
)
 
# --- input guardrail (runs on first agent) ---
class PolicyCheck(BaseModel):
    is_disallowed: bool
    reasoning: str
 
guardrail_agent = Agent(
    name="Policy guard",
    instructions="Flag requests that ask for illegal activity or credential theft.",
    output_type=PolicyCheck,
)
 
@input_guardrail
async def policy_input_guardrail(
    ctx: RunContextWrapper[None],
    agent: Agent,
    input: str | list,
) -> GuardrailFunctionOutput:
    result = await Runner.run(guardrail_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_disallowed,
    )
 
triage = Agent(
    name="Support triage",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
    Route billing vs refund questions to the right specialist.
    Answer only trivial FAQ yourself.""",
    handoffs=[
        billing_agent,
        handoff(refund_agent),  # customize further if needed
    ],
    input_guardrails=[policy_input_guardrail],
)
 
async def main() -> None:
    try:
        result = await Runner.run(
            triage,
            "I need a refund for order A-100. It never arrived.",
        )
        print(result.final_output)
        print("finished on:", result.last_agent.name)
    except InputGuardrailTripwireTriggered:
        print("Blocked by input guardrail")
 
asyncio.run(main())

• Handoffs are exposed to the LLM as tools (default names like transfer_to_refund_agent).
• Input guardrails on triage run because it is the first agent.
• Output guardrails (not shown) run only on the agent that emits the final output.

Deep Dive

Handoffs vs agents-as-tools

Start with handoffs for support-style routing. Switch to agents-as-tools when the parent must merge partial answers without giving up the floor.

Customizing handoff()

Useful knobs (verify names at build):

• tool_name_override / tool_description_override
• on_handoff callback for logging or prefetch
• input_type for model-supplied metadata (reason, priority)
• input_filter to reshape history the next agent sees
• is_enabled for dynamic routing allowlists

Example metadata pattern:

from pydantic import BaseModel
from agents import handoff, RunContextWrapper
 
class EscalationData(BaseModel):
    reason: str
 
async def on_escalation(ctx: RunContextWrapper[None], data: EscalationData):
    print("escalating:", data.reason)
 
escalation = Agent(name="Escalation agent", instructions="Handle escalations.")
esc_handoff = handoff(
    agent=escalation,
    on_handoff=on_escalation,
    input_type=EscalationData,
)

input_type does not choose the destination; register one handoff per destination.

Guardrail boundaries (easy to misuse)

Handoffs do not re-run the first agent's input guardrails on later specialists. If each specialist needs checks, put tool guardrails on risky tools or add host-level policy around Runner.run.

Parallel vs blocking input guardrails

• Parallel (default): lower latency; agent may start (and spend tokens) before a tripwire cancels.
• Blocking: guardrail finishes first; failed checks never start the expensive agent path.

Use blocking when tools have side effects you cannot unwind.

History hygiene on handoff

By default the next agent often sees prior conversation items. If tool spam pollutes context, apply an input_filter (for example agents.extensions.handoff_filters.remove_all_tools) or nest history via run config options when you deliberately want summaries (beta/options vary - verify at build).

Gotchas

1. Assuming every agent runs its input guardrails. Only the first agent in the chain does.
2. Assuming output guardrails run on intermediate specialists. Only the final output agent does.
3. Forgetting handoff prompt guidance. Models route more reliably with the recommended handoff prefix.
4. Putting authorization only in prompts. Guardrails help; real auth still belongs in tools and backends.
5. Letting full tool transcripts flood specialists. Use input filters when history is noisy.
6. Treating tripwires as soft warnings. They raise exceptions; handle them at the API boundary with a user-safe message.
7. Expecting tool guardrails on hosted tools / handoff tools. They target custom function_tool paths.

Alternatives

FAQs

Related

• OpenAI Agents SDK Basics - install, tools, first triage pattern
• Native MCP Support in the OpenAI Agents SDK - external tool servers
• Prompt Injection & Guardrails Basics - broader security framing
• Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - architecture view
• OpenAI Agents SDK & Native Primitives Best Practices - production checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.