Handoff protocol

Handoffs transfer control from one agent to another. The handoff carries:

• target agent — which specialist to invoke
• context — accumulated conversation state
• instructions — what the target should focus on
• metadata — routing reason, priority, constraints

// OpenAI Agents SDK handoff definition
import { Agent, handoff } from "@openai/agents";

const researchAgent = new Agent({
  name: "research_agent",
  instructions: "You find and summarize relevant information.",
  tools: [webSearch, docRetrieval],
});

const codeAgent = new Agent({
  name: "code_agent",
  instructions: "You write and review code based on research findings.",
  tools: [fileWrite, linter, testRunner],
});

const triageAgent = new Agent({
  name: "triage_agent",
  instructions: \`Classify the user request:
- If it needs research → hand off to research_agent
- If it needs code → hand off to code_agent
- If unclear → ask a clarifying question\`,
  handoffs: [handoff(researchAgent), handoff(codeAgent)],
});

State management patterns

┌─────────────┐     context      ┌─────────────────┐
│   Router     │ ──────────────> │  Specialist A    │
│   Agent      │                 │  (research)      │
└──────┬───── ┘                 └────────┬─────────┘
       │                                  │ result
       │    ┌─────────────────────────────┘
       ▼    ▼
┌─────────────┐     context      ┌─────────────────┐
│ Orchestrator │ ──────────────> │  Specialist B    │
│   (merge)    │                 │  (code)          │
└──────┬──────┘                 └────────┬─────────┘
       │                                  │ result
       ▼                                  ▼
┌─────────────────────────────────────────────────┐
│                 Guardrail Agent                   │
│            (validate final output)                │
└──────────────────────────────────────────────────┘

Shared state approaches:

Workflow

Step 1: Define your agent graph

Map out which agents exist and how control flows between them.

// Agent graph as config
const agentGraph = {
  entrypoint: "triage",
  agents: {
    triage: {
      handoffs: ["research", "code", "clarify"],
      tools: [],
    },
    research: {
      handoffs: ["code", "triage"],
      tools: ["web_search", "doc_retrieval"],
    },
    code: {
      handoffs: ["review"],
      tools: ["file_write", "shell_exec", "test_run"],
    },
    review: {
      handoffs: ["code", "triage"],
      tools: ["lint", "test_run"],
    },
  },
  guardrails: ["safety_check", "pii_redact"],
};

Step 2: Implement agents with focused instructions

import { Agent, run } from "@openai/agents";

const reviewAgent = new Agent({
  name: "review_agent",
  instructions: \`You review code changes for:
1. Correctness — does it solve the stated problem?
2. Security — any injection, auth bypass, or data leak?
3. Performance — unnecessary loops, missing indexes, N+1?
4. Style — consistent with project conventions?

If issues found, hand back to code_agent with specific feedback.
If approved, return the final result to the user.\`,
  handoffs: [handoff(codeAgent)],
  tools: [lintTool, testRunTool],
});

Step 3: Run the orchestration loop

import { run } from "@openai/agents";

async function orchestrate(userMessage: string) {
  const result = await run(triageAgent, userMessage, {
    maxTurns: 15,
    stream: true,
  });

  for await (const event of result) {
    if (event.type === "agent_handoff") {
      console.log(\`Handoff: \${event.from} → \${event.to}\`);
    }
    if (event.type === "tool_call") {
      console.log(\`Tool: \${event.name}(\${JSON.stringify(event.args)})\`);
    }
    if (event.type === "message") {
      yield event.content;
    }
  }
}

Step 4: Add guardrails

import { Agent, InputGuardrail, OutputGuardrail } from "@openai/agents";

const safetyGuardrail: InputGuardrail = {
  name: "safety_check",
  execute: async (input) => {
    const result = await classifySafety(input);
    if (result.category === "unsafe") {
      return { blocked: true, reason: result.reason };
    }
    return { blocked: false };
  },
};

const triageAgent = new Agent({
  name: "triage",
  instructions: "Route user requests to the right specialist.",
  inputGuardrails: [safetyGuardrail],
  handoffs: [handoff(researchAgent), handoff(codeAgent)],
});

Examples

Example 1: Customer support pipeline

const supportTriage = new Agent({
  name: "support_triage",
  instructions: \`Classify the support ticket:
- billing → billing_agent
- technical → tech_agent
- account → account_agent
- unknown → ask clarifying question\`,
  handoffs: [
    handoff(billingAgent),
    handoff(techAgent),
    handoff(accountAgent),
  ],
});

// Each specialist has domain-specific tools
const billingAgent = new Agent({
  name: "billing_agent",
  instructions: "Handle billing inquiries. You can look up invoices and issue refunds.",
  tools: [lookupInvoice, issueRefund, updateSubscription],
});

Example 2: Code generation with review loop

async function codeWithReview(task: string) {
  let result = await run(codeAgent, task);
  let attempts = 0;

  while (attempts < 3) {
    const review = await run(reviewAgent, result.output);
    if (review.output.includes("APPROVED")) break;
    result = await run(codeAgent, \`Fix these issues:\n\${review.output}\`);
    attempts++;
  }

  return result.output;
}

Example 3: Anthropic tool_use with agent routing

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function anthropicAgentRouter(userMessage: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    system: \`You are a router. Analyze the request and call the
appropriate agent tool. Always provide a clear routing reason.\`,
    tools: [
      {
        name: "dispatch_to_agent",
        description: "Route to a specialist agent",
        input_schema: {
          type: "object" as const,
          properties: {
            agent: { type: "string", enum: ["research", "code", "review"] },
            context: { type: "string" },
            priority: { type: "string", enum: ["low", "medium", "high"] },
          },
          required: ["agent", "context"],
        },
      },
    ],
    messages: [{ role: "user", content: userMessage }],
  });

  return response;
}

Decision tree

Is one LLM call enough?
├── Yes → Single agent with tools (no orchestration needed)
└── No
    ├── Is the flow linear (A → B → C)?
    │   ├── Yes → Pipeline pattern (chain agents sequentially)
    │   └── No
    │       ├── Does routing depend on input classification?
    │       │   ├── Yes → Router + Specialists pattern
    │       │   └── No
    │       │       ├── Do agents need to iterate (code → review → fix)?
    │       │       │   ├── Yes → Loop pattern with max iterations
    │       │       │   └── No → Parallel fan-out pattern
    │       │       └── Need human approval mid-flow?
    │       │           ├── Yes → Add approval gates between stages
    │       │           └── No → Fully autonomous pipeline
    └── Need guardrails?
        ├── Yes → Wrap entry/exit with guardrail agents
        └── No → Direct orchestration

Edge cases and gotchas

• Infinite loops: Always set maxTurns — agents handing off to each other can loop forever
• Context bloat: Each handoff passes the full conversation; for long chains, summarize before handoff
• Error propagation: If a specialist fails, the orchestrator must handle the error — don't let it silently drop
• Model mismatch: Router agents can use cheaper/faster models; specialists may need more capable ones
• Streaming across handoffs: The stream must indicate which agent is currently responding
• Tool overlap: If two specialists share a tool, ensure they don't conflict on shared state
• Latency multiplication: Each handoff adds a full LLM round-trip; budget 2-5s per hop
• Guardrail ordering: Input guardrails run before the agent; output guardrails after — both can block

Evaluation criteria