Hand-off Patterns

Hand-offs are the critical juncture in multi-agent workflows. When Agent A completes its task and Agent B needs to continue, the quality of the hand-off determines whether Agent B succeeds or flounders. A good hand-off includes: what was done (summary of changes), what artifacts were produced (files modified, tests added), what decisions were made (and why), and what remains to be done (clear task for Agent B).

The OpenAI Agents SDK formalizes hand-offs as first-class primitives. In the SDK, a hand-off is a structured message that includes the source agent, the target agent, a context payload (what was done and what is needed), and trace metadata for debugging. Each hand-off is a trace event that you can inspect in the Agents SDK dashboard — essential for debugging when a multi-agent pipeline produces unexpected results.

from agents import Agent, handoff, Runner

# Define specialized agents
planner = Agent(
    name="planner",
    model="o3",
    instructions="Analyze the task and produce a detailed \
      implementation plan with file-by-file changes.",
)

implementer = Agent(
    name="implementer",
    model="codex-1",
    instructions="Implement the plan exactly as specified. \
      Do not deviate from the plan without explanation.",
    handoffs=[handoff(planner, "Escalate to planner \
      if the plan has gaps or contradictions")],
)

reviewer = Agent(
    name="reviewer",
    model="o3",
    instructions="Review the implementation for correctness, \
      security issues, and adherence to the plan.",
)

# Run the pipeline
result = Runner.run(
    planner,
    "Build a rate limiting middleware for the Express API",
)

1. Define the hand-off format Create a standard template: what was done, what files changed, what decisions were made, what is next. Every hand-off follows this format.
2. Include artifacts Hand-offs should reference specific files and line numbers, not vague descriptions. "Modified src/auth/jwt.ts lines 45-78" beats "updated the auth code."
3. Test the hand-off Have Agent B summarize the hand-off back before proceeding. If the summary is wrong, the hand-off was unclear — refine the format.