Get Started

OpenAI Agents SDK: Handoffs, Guardrails, Tracing

OpenAI Agents SDK is the lightweight multi-agent framework built on the Responses API. Five primitives: Agent, Handoff, Guardrail, Session, Tracing. Handoffs are tools named transfer_to_<agent>. Guardrails trip on input or output. Tracing is on by default.

75 minutesLearn + BuildPython (stdlib)Free lesson

Learning Objectives

  • Name the five primitives of the OpenAI Agents SDK.
  • Explain handoffs: why they are modeled as tools, what name shape the model sees, and how context transfers.
  • Distinguish input guardrails, output guardrails, and tool guardrails; explain run_in_parallel vs blocking mode.
  • Implement a stdlib runtime with handoffs + guardrails + span-style tracing.

The Problem

Agents that cannot delegate cleanly end up stuffing everything into one prompt. Agents without guardrails ship PII, policy-violating output, or loop forever. OpenAI's SDK codifies the three primitives that make multi-agent work tractable.

The Concept

Five primitives

  1. Agent. LLM + instructions + tools + handoffs.
  2. Handoff. Delegation to another agent. Represented to the model as a tool named transfer_to_<agent_name>.
  3. Guardrail. Validation on input (first agent only), output (last agent only), or tool invocation (per function tool).
  4. Session. Automatic conversation history across turns.
  5. Tracing. Built-in spans for LLM generations, tool calls, handoffs, guardrails.

Handoffs as tools

The model sees transfer_to_billing_agent in its tool list. Calling it signals the runtime to:

  1. Copy the conversation context (or collapse it via nest_handoff_history beta).
  2. Initialize the target agent with its instructions.
  3. Continue the run with the target agent.

This is the supervisor pattern (Lesson 13 / Lesson 28) productized.

Guardrails

Three flavors:

  • Input guardrails. Run on the first agent's input. Reject unsafe or out-of-scope requests before any LLM call.
  • Output guardrails. Run on the last agent's output. Catch PII leaks, policy violations, malformed responses.
  • Tool guardrails. Run per-function-tool. Validate arguments, check permissions, audit execution.

Mode:

  • Parallel (default). Guardrail LLM runs alongside the main LLM. Lower tail latency. If tripped, the main LLM's work is discarded (token waste).
  • Blocking (run_in_parallel=False). Guardrail LLM runs first. If tripped, no tokens wasted on the main call.

Tripwires raise InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered.

Tracing

On by default. Every LLM generation, tool call, handoff, and guardrail emits a span. OPENAI_AGENTS_DISABLE_TRACING=1 opts out. add_trace_processor(processor) fans spans to your own backend alongside OpenAI's.

Sessions

Session stores conversation history in a backend (SQLite, Redis, custom). Runner.run(agent, input, session=session) auto-loads and appends.

Where this pattern goes wrong

  • Handoff drift. Agent A hands off to Agent B which hands back to Agent A. Add a hop counter.
  • Guardrail bypass. Tool guardrails only fire on function tools; built-in tools (file reader, web fetch) need separate policy.
  • Over-tracing. Sensitive content in spans. Pair with OTel GenAI content-capture rules (Lesson 23), store externally, reference by ID.

Build It

code/main.py implements the SDK shape in stdlib:

  • AgentFunctionToolHandoff (as a function tool with transfer semantics).
  • Runner with input/output/tool guardrails, handoff dispatch, and hop counter.
  • A simple span emitter to show the trace shape.
  • A triage agent that hands off to billing or support based on the user's query; guardrail trips on one input.

Run it:

Code
python3 code/main.py

The trace shows two successful handoffs, one input guardrail trip, and a span tree mirroring what the real SDK emits.

Use It

  • OpenAI Agents SDK for OpenAI-first products.
  • Claude Agent SDK (Lesson 17) for Claude-first products.
  • LangGraph (Lesson 13) when you want explicit state and durable resume.
  • Custom when you need exact control (voice, multi-provider, federated deployments).

Ship It

outputs/skill-agents-sdk-scaffold.md scaffolds an Agents SDK app with a triage agent, handoffs, input/output/tool guardrails, session store, and a trace processor.

Exercises

  1. Add a handoff hop counter: refuse after N transfers. Trace the behavior.
  2. Implement nest_handoff_history as an option, collapse prior messages into one summary before transferring.
  3. Write a blocking output guardrail. Compare latency on prompts that would trip it vs ones that pass.
  4. Wire add_trace_processor to a JSON logger. What shape does it emit per span?
  5. Read the SDK docs. Port your stdlib toy to openai-agents-python. What did you model wrong?

Key Terms

TermWhat people sayWhat it actually means
Agent"LLM + instructions"Agent type in the SDK; owns tools and handoffs
Handoff"Transfer"Tool the model calls to delegate to another agent
Guardrail"Policy check"Validation on input / output / tool invocation
Tripwire"Guardrail trip"Exception raised when guardrail rejects
Session"History store"Conversation memory persisted between runs
Tracing"Spans"Built-in observability over LLM + tool + handoff + guardrail
Blocking guardrail"Sequential check"Guardrail runs first; no token waste on trip
Parallel guardrail"Concurrent check"Guardrail runs alongside; lower latency, wastes tokens on trip

Further Reading

Check what you learned

7 questions. Answer each one to see why.

Question 1 of 70 correct

What are the five primitives of the OpenAI Agents SDK?

The full code

Every file for this lesson. Copy it, run it, then change it.

main.py
"""OpenAI Agents SDK-shaped runtime in stdlib.

Five primitives: Agent, FunctionTool, Handoff, Guardrail, Tracing.
Handoffs are tools named transfer_to_<agent>. Guardrails trip on input/output.
A span tree mirrors what the real SDK emits.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Callable


class GuardrailTripped(Exception):
    def __init__(self, which: str, reason: str) -> None:
        super().__init__(f"{which}: {reason}")
        self.which = which
        self.reason = reason


@dataclass
class FunctionTool:
    name: str
    description: str
    fn: Callable[..., str]


@dataclass
class Handoff:
    target: "Agent"

    @property
    def tool_name(self) -> str:
        return f"transfer_to_{self.target.name}"


@dataclass
class Agent:
    name: str
    instructions: str
    policy: Callable[[str], dict[str, Any]]
    tools: list[FunctionTool] = field(default_factory=list)
    handoffs: list[Handoff] = field(default_factory=list)


@dataclass
class InputGuardrail:
    name: str
    check: Callable[[str], tuple[bool, str]]


@dataclass
class OutputGuardrail:
    name: str
    check: Callable[[str], tuple[bool, str]]


@dataclass
class Span:
    name: str
    attributes: dict[str, Any] = field(default_factory=dict)
    children: list["Span"] = field(default_factory=list)


@dataclass
class Runner:
    input_guardrails: list[InputGuardrail] = field(default_factory=list)
    output_guardrails: list[OutputGuardrail] = field(default_factory=list)
    max_hops: int = 3
    trace: Span = field(default_factory=lambda: Span(name="run"))

    def run(self, agent: Agent, user_input: str) -> str:
        for guard in self.input_guardrails:
            ok, reason = guard.check(user_input)
            span = Span(name=f"input_guardrail.{guard.name}",
                        attributes={"passed": ok, "reason": reason})
            self.trace.children.append(span)
            if not ok:
                raise GuardrailTripped("input", reason)

        current_agent = agent
        current_input = user_input
        final_output = ""
        for hop in range(self.max_hops):
            agent_span = Span(name=f"agent.{current_agent.name}",
                              attributes={"hop": hop,
                                          "instructions": current_agent.instructions[:40]})
            self.trace.children.append(agent_span)

            policy_output = current_agent.policy(current_input)
            kind = policy_output["kind"]

            if kind == "final":
                final_output = policy_output["text"]
                agent_span.children.append(
                    Span(name="llm_generation",
                         attributes={"output": final_output[:60]})
                )
                break
            if kind == "tool":
                tool_name = policy_output["tool"]
                args = policy_output.get("args", {})
                tool = next((t for t in current_agent.tools if t.name == tool_name),
                            None)
                if tool is None:
                    agent_span.children.append(
                        Span(name="tool_error",
                             attributes={"tool": tool_name,
                                         "reason": "unknown tool"})
                    )
                    final_output = f"error: unknown tool {tool_name}"
                    break
                result = tool.fn(**args)
                agent_span.children.append(
                    Span(name=f"tool.{tool_name}",
                         attributes={"args": args, "result": result[:40]})
                )
                current_input = f"tool {tool_name} returned: {result}"
                continue
            if kind == "handoff":
                target_name = policy_output["to"]
                handoff = next((h for h in current_agent.handoffs
                                if h.target.name == target_name), None)
                if handoff is None:
                    final_output = f"error: no handoff to {target_name}"
                    break
                agent_span.children.append(
                    Span(name=f"handoff.{handoff.tool_name}",
                         attributes={"from": current_agent.name,
                                     "to": target_name})
                )
                current_agent = handoff.target
                current_input = policy_output.get("input", current_input)
                continue
            final_output = f"error: unknown policy kind {kind}"
            break

        for guard in self.output_guardrails:
            ok, reason = guard.check(final_output)
            span = Span(name=f"output_guardrail.{guard.name}",
                        attributes={"passed": ok, "reason": reason})
            self.trace.children.append(span)
            if not ok:
                raise GuardrailTripped("output", reason)

        return final_output


def _print_span(span: Span, indent: int = 0) -> None:
    prefix = "  " * indent
    attrs = " ".join(f"{k}={v!r}" for k, v in span.attributes.items())
    print(f"{prefix}{span.name}  {attrs}")
    for child in span.children:
        _print_span(child, indent + 1)


def _triage_policy(user_input: str) -> dict[str, Any]:
    t = user_input.lower()
    if "refund" in t or "billing" in t or "invoice" in t:
        return {"kind": "handoff", "to": "billing", "input": user_input}
    if "error" in t or "crash" in t or "bug" in t:
        return {"kind": "handoff", "to": "support", "input": user_input}
    return {"kind": "final", "text": "i'm not sure how to help with that"}


def _billing_policy(user_input: str) -> dict[str, Any]:
    return {"kind": "final", "text": f"billing handled: {user_input[:40]}"}


def _support_policy(user_input: str) -> dict[str, Any]:
    return {"kind": "final", "text": f"support handled: {user_input[:40]}"}


def _pii_check(text: str) -> tuple[bool, str]:
    if "ssn" in text.lower():
        return False, "refuses to process social security numbers"
    return True, "ok"


def _length_check(text: str) -> tuple[bool, str]:
    return len(text) < 200, f"output {len(text)} chars"


def main() -> None:
    print("=" * 70)
    print("OPENAI AGENTS SDK SHAPE — Phase 14, Lesson 16")
    print("=" * 70)

    billing = Agent(name="billing", instructions="handle refunds and invoices",
                    policy=_billing_policy)
    support = Agent(name="support", instructions="handle bugs and errors",
                    policy=_support_policy)
    triage = Agent(
        name="triage", instructions="route queries to the right specialist",
        policy=_triage_policy,
        handoffs=[Handoff(target=billing), Handoff(target=support)],
    )

    runner = Runner(
        input_guardrails=[InputGuardrail("pii_block", _pii_check)],
        output_guardrails=[OutputGuardrail("length_cap", _length_check)],
    )

    cases = [
        "I need a refund for invoice 4711",
        "the CLI crashes on ctrl-c",
        "share my ssn with the team",
    ]
    for case in cases:
        print(f"\n--- case: {case} ---")
        runner.trace = Span(name="run", attributes={"user_input": case[:40]})
        try:
            out = runner.run(triage, case)
            print(f"final: {out}")
        except GuardrailTripped as e:
            print(f"GUARDRAIL: {e}")
        print("span tree:")
        _print_span(runner.trace, indent=1)

    print()
    print("every handoff is a tool named transfer_to_<agent>.")
    print("every guardrail trip is a structured exception, not a crash.")


if __name__ == "__main__":
    main()