Skip to main content

​
Agent Handoff

Agent Handoff enables seamless mid-conversation transfers between agents. When a user’s request falls outside the current agent’s expertise, it can transfer to a specialist agent while carrying over the full conversation context.

​
Quick Start

import { Agent, openai } from "@radaros/core";

const billing = new Agent({
  name: "billing",
  model: openai("gpt-4o-mini"),
  instructions: "You are a billing specialist.",
});

const support = new Agent({
  name: "support",
  model: openai("gpt-4o-mini"),
  instructions: "You are a tech support agent.",
});

const frontDesk = new Agent({
  name: "front-desk",
  model: openai("gpt-4o"),
  instructions: "Route the user to the right specialist.",
  handoff: {
    targets: [
      { agent: billing, description: "Billing, invoices, payments" },
      { agent: support, description: "Technical issues, debugging" },
    ],
    maxHandoffs: 3,
  },
});

const result = await frontDesk.run("I need help with my invoice");
// Automatically transfers to billing agent

​
How It Works

  1. The agent receives a transfer_to_agent tool based on the configured targets
  2. When the LLM decides a handoff is needed, it calls the tool with the target agent name
  3. The HandoffManager catches the signal and transfers the conversation
  4. The target agent receives the full conversation history and continues naturally

​
Configuration

interface HandoffConfig {
  targets: HandoffTarget[];       // Specialist agents
  maxHandoffs?: number;           // Prevent infinite loops (default: 5)
  carryMessages?: boolean;        // Pass conversation history (default: true)
  carrySessionState?: boolean;    // Pass session state (default: true)
}

interface HandoffTarget {
  agent: Agent;
  description: string;            // LLM sees this to decide when to handoff
  onHandoff?: (ctx: RunContext) => Promise<void>;  // Hook before handoff
}

​
Team Handoff Mode

For managed teams, use TeamMode.Handoff: 
import { Team, TeamMode } from "@radaros/core";

const team = new Team({
  name: "support-team",
  mode: TeamMode.Handoff,
  model: openai("gpt-4o"),
  members: [frontDesk, billing, support],
  maxRounds: 5,
});

const result = await team.run("I need to upgrade my plan");

​
Events

EventPayload
handoff.transfer{ runId, fromAgent, toAgent, reason }
handoff.complete{ runId, chain: string[], finalAgent }