Delegating Work with Handoffs

Welcome to another lesson about agentic patterns! In the previous lesson, you mastered orchestrating agents as tools, where a central planner agent could dynamically delegate tasks to specialist agents and receive their results back. Today, we're exploring a fundamentally different approach called the handoff pattern, where agents can completely transfer control to other specialized agents rather than just calling them as tools.

In this lesson, you'll extend the Agent class constructor to support handoff targets, create a handoff tool schema that enables control transfers, and implement the core handoff logic that passes conversation context between agents. We'll build a practical example with a general assistant that can hand off mathematical problems to a specialized calculator assistant, demonstrating how agents make intelligent decisions about when to transfer control versus handling tasks themselves.

The handoff pattern represents a different philosophy of agent collaboration compared to the tool delegation approach you learned previously. When an agent uses another agent as a tool, it's essentially asking for help while maintaining responsibility for the final response. When an agent performs a handoff, it's saying, "this other agent is better equipped to handle this entire conversation from here on."

Consider the difference in conversation flow. In tool delegation, the user interacts with the orchestrator throughout: the user asks a question, the orchestrator calls a specialist tool, receives the result, and then provides its own response incorporating that information. The user never directly interacts with the specialist agent.

In the handoff pattern, the conversation flow changes completely. The user starts by talking to one agent, but that agent recognizes that another agent should take over. The first agent transfers not just the task, but the entire conversation context to the specialist. From that point forward, the specialist agent is directly responding to the user, and the original agent is no longer involved. This pattern is particularly powerful when you have agents with very different capabilities or when the nature of a request clearly falls into one agent's domain of expertise.

To implement handoffs, we need to extend our existing Agent class with the ability to transfer control to other agents. This requires adding a new parameter to track available handoff targets and creating a special handoff tool that agents can use to transfer control.

export interface AgentOptions {
  name: string;
  systemPrompt?: string;
  model?: string;
  tools?: Record<string, Function>;
  toolSchemas?: Array<Record<string, unknown>>;
  handoffs?: Agent[];  // New parameter for handoff targets
  maxTurns?: number;
  reasoningEffort?: "minimal" | "low" | "medium" | "high";
}

export class Agent {
  private static BASE_SYSTEM_PROMPT =
    "You are an autonomous agent that can take multiple tool-calling steps when helpful. " +
    "The user only sees your response when you stop using tools, not your tool usage or reasoning steps. " +
    "When you provide your answer without calling tools, make it complete and standalone.\n" +
    "Additional instructions:\n";

  private client: OpenAI;
  public name: string;
  private model: string;
  private systemPrompt: string;
  private maxTurns: number;
  private reasoningEffort: "minimal" | "low" | "medium" | "high";
  private tools: Record<string, Function>;
  private toolSchemas: Array<Record<string, unknown>>;
  private handoffs: Agent[];  // List of agents for handoffs
  private handoffSchema: Record<string, unknown>;

  constructor({
    name,
    systemPrompt = "You are a helpful assistant.",
    model = "gpt-5",
    tools = {},
    toolSchemas = [],
    handoffs = [],  // Default to empty array
    maxTurns = 10,
    reasoningEffort = "low"
  }: AgentOptions) {
    this.client = new OpenAI();
    this.name = name;
    this.model = model;
    this.systemPrompt = Agent.BASE_SYSTEM_PROMPT + systemPrompt;
    this.maxTurns = maxTurns;
    this.reasoningEffort = reasoningEffort;

    // Copy to isolate from external mutation
    this.tools = { ...tools };
    this.toolSchemas = [...toolSchemas];
    this.handoffs = [...handoffs];  // List of other agents to handoff the control
  }
}

The handoffs parameter accepts an array of other Agent instances to which this agent can transfer control. We store this as an array rather than an object because agents are identified by their name property, and we want to maintain the flexibility to search through available agents dynamically.

The reasoningEffort parameter controls how much computational effort the model invests in reasoning through problems. Setting it to "low" provides faster responses for straightforward tasks, while higher values like "medium" or "high" enable deeper analysis for complex problems. For handoff decisions and basic task routing, low reasoning effort is typically sufficient.

With the constructor updated, we need to create the handoff tool schema that will enable agents to request control transfers.

Next, we need to create a tool schema that allows the agent to request handoffs. This schema will be automatically added to the agent's available tools when handoff targets are provided.

// Define handoff tool schema
this.handoffSchema = {
  type: "function",
  name: "handoff",
  description:
    "Transfer control to another specialized agent. Use this when the user's request is better handled by a different agent.",
  parameters: {
    type: "object",
    properties: {
      name: {
        type: "string",
        description: `Name of the agent to handoff to. Available agents: ${JSON.stringify(
          this.handoffs.map((agent) => agent.name)
        )}`
      },
      reason: {
        type: "string",
        description: "Brief explanation of why this handoff is needed"
      }
    },
    required: ["name", "reason"],
    additionalProperties: false
  }
};

The handoff schema follows OpenAI's function calling format with a type of "function", a descriptive name, and a parameters object defining the expected inputs. The schema includes two required parameters: the name of the target agent and a reason for the handoff. The reason parameter serves both as documentation for debugging and as a way to help the agent think through whether a handoff is truly necessary.

Notice how we dynamically include the list of available agents in the description using JSON.stringify(), helping the model understand which handoff options are available. The additionalProperties: false constraint ensures that only the specified parameters can be passed, preventing unexpected inputs. Now we need to make this handoff schema available to the agent alongside its other tools.

To make handoffs work seamlessly, we need to build a complete list of available tools that includes both regular tool schemas and the handoff schema when appropriate. Unlike some agent frameworks that use a separate method for building request arguments, our implementation constructs the tool list directly within the run method before each API call.

public async run(
  inputMessages: Array<Record<string, unknown>>
): Promise<[Array<Record<string, unknown>>, string]> {
  // Create a copy of the input messages to avoid modifying the original
  const messages = [...inputMessages];

  // Initialize turn counter to track iterations
  let turn = 0;

  // Loop until the model returns a final answer or the max turns is reached
  while (turn < this.maxTurns) {
    // Increment the turn
    turn++;

    // Build the complete tool schemas list
    const allTools: Array<Record<string, unknown>> = [];

    // Add regular tool schemas if they exist
    if (this.toolSchemas.length > 0) {
      allTools.push(...this.toolSchemas);
    }

    // Add handoff schema if handoffs are available
    if (this.handoffs.length > 0) {
      allTools.push(this.handoffSchema);
    }

    const response = await this.client.responses.create({
      model: this.model,
      instructions: this.systemPrompt,
      input: messages,
      tools: allTools,
      reasoning: { effort: this.reasoningEffort },
      store: false
    });
  }
}

This approach builds the allTools array fresh for each turn by first spreading any regular tool schemas into it, then pushing the handoff schema if handoff targets are configured. The array is passed directly to responses.create() as the tools parameter. This inline construction ensures that the handoff tool is automatically available to any agent that has handoff targets configured, without requiring separate schema management methods.

With the handoff tool now available to agents, we need to implement the logic that actually performs the control transfer when this tool is called.

Now, let's build the callHandoff method. This is the core logic that performs the actual transfer of control from our current agent to another. We need this method to parse the model's request, locate the target agent, and safely execute the handoff.

private async callHandoff(
  functionCall: FunctionCallItem,
  messages: Array<Record<string, unknown>>
): Promise<
  [boolean, [Array<Record<string, unknown>>, string] | Record<string, unknown>]
> {
  // Extract the agent name from the handoff tool input
  const args = JSON.parse(functionCall.arguments || "{}");
  const agentName = args.name;
  const reason = args.reason || "No reason provided";

  console.log(`🔄 Handoff to: ${agentName}`);
  console.log(`📝 Reason: ${reason}`);

  try {
    // Find the agent with the given name
    const targetAgent = this.handoffs.find((agent) => agent.name === agentName);

    if (!targetAgent) {
      throw new Error(`Agent '${agentName}' not found`);
    }

    // Handoff the control to the other agent
    return [true, await targetAgent.run(messages)];
  } catch (error: any) {
    // Any error during handoff execution
    return [
      false,
      {
        type: "function_call_output",
        call_id: functionCall.call_id,
        output: JSON.stringify({
          result: `Handoff failed: ${error.message}. Available agents: ${JSON.stringify(
            this.handoffs.map((agent) => agent.name)
          )}`
        })
      }
    ];
  }
}

Here is how we are structuring this logic:

1. Extracting Parameters: Since the model sends functionCall.arguments as a JSON string, we start by using JSON.parse() to retrieve the agentName and the reason. Logging the reason is a great practice here—it helps us debug exactly why our agent decided to pass the baton.
2. Locating the Target: We use Array.find() to search through our handoffs array for an agent whose name matches the requested input. If the model hallucinated a name or requested an unavailable agent, we throw an error immediately to enter our catch block.
3. Transferring Control: This is the crucial step. We call the target agent's run method, passing in the entire messages history. By doing this, we effectively hand over the "steering wheel" of the conversation to the new agent.
4. Returning Success: We return a tuple starting with true. This boolean acts as a flag for our main loop, signaling that a handoff occurred and we should return the new agent's response directly to the user.
5. Graceful Fallbacks: If something goes wrong—like the agent not being found—we don't want the whole system to crash. Instead, we return false along with a standard function_call_output. This allows the current agent to see the error message, understand which agents are actually available, and try a different approach in the next turn.

With the handoff mechanics built, we just need to wire them into our main execution loop so the agent knows when to trigger this method.

The main execution loop in the run method needs to detect handoff function calls and handle them differently from regular tools. When a handoff succeeds, it should immediately return the target agent's response rather than continuing the current agent's execution.

public async run(
  inputMessages: Array<Record<string, unknown>>
): Promise<[Array<Record<string, unknown>>, string]> {
  const messages = [...inputMessages];
  let turn = 0;

  while (turn < this.maxTurns) {
    turn++;

    const allTools: Array<Record<string, unknown>> = [];

    if (this.toolSchemas.length > 0) {
      allTools.push(...this.toolSchemas);
    }

    // Add handoff schema if handoffs are available
    if (this.handoffs.length > 0) {
      allTools.push(this.handoffSchema);
    }

    const response = await this.client.responses.create({
      model: this.model,
      instructions: this.systemPrompt,
      input: messages,
      tools: allTools,
      reasoning: { effort: this.reasoningEffort },
      store: false
    });

    const functionCalls = response.output.filter(
      (item): item is FunctionCallItem => item.type === "function_call"
    );

    if (functionCalls.length > 0) {
      const functionOutputs: Array<Record<string, unknown>> = [];
      for (const functionCall of functionCalls) {
        // If the tool use is a handoff
        if (functionCall.name === "handoff") {
          // Try to transfer control to another agent
          const [handoffSuccess, handoffResult] = await this.callHandoff(
            functionCall,
            messages
          );
          // If handoff was successful, return the result from the other agent
          if (handoffSuccess) {
            return handoffResult as [Array<Record<string, unknown>>, string];
          }
          // If handoff failed, treat it as a regular tool result
          else {
            functionOutputs.push(handoffResult as Record<string, unknown>);
          }
        } else {
          messages.push({
            type: "function_call",
            name: functionCall.name,
            arguments: functionCall.arguments,
            call_id: functionCall.call_id
          });
          const toolResult = await this.callTool(functionCall);
          functionOutputs.push(toolResult);
        }
      }

      messages.push(...functionOutputs);
    } else {
      messages.push({
        role: "assistant",
        content: response.output_text
      });

      return [messages, response.output_text];
    }
  }

  throw new Error("Max turns reached");
}

The key difference from the previous tool delegation pattern is how we handle function calls once detected. We continue to filter response.output using a type guard to identify function calls, but now we check if functionCall.name === "handoff" to distinguish handoff requests from regular tool calls.

For handoff calls, we attempt the control transfer using destructuring syntax const [handoffSuccess, handoffResult] = await this.callHandoff(...) and immediately return if successful, bypassing normal tool result processing. This is what makes handoffs different from tool calls: instead of collecting the result and continuing the conversation, a successful handoff ends the current agent's involvement and returns the target agent's complete response.

For regular tools, we add the function call to messages, execute the tool, and collect the result. All function outputs (both from failed handoffs and regular tools) are then added to the message history using the spread operator for the next turn.

With all the handoff mechanics in place, let's create a complete example to test the system.

Let's create a complete example that demonstrates how agents make intelligent handoff decisions. We'll set up a general assistant that can hand off mathematical problems to a specialized calculator assistant.

import fs from "fs";
import { Agent } from "./agent";
import {
  sumNumbers,
  multiplyNumbers,
  subtractNumbers,
  divideNumbers,
  power,
  squareRoot
} from "./functions";

// Load tool schemas (OpenAI Responses API format)
const schemasJson = fs.readFileSync("schemas.json", "utf-8");
const toolSchemas = JSON.parse(schemasJson);

// Build specialist agents
const calculatorAssistant = new Agent({
  name: "calculator_assistant",
  systemPrompt:
    "You are a calculator assistant. You specialize in mathematical calculations and solving equations. " +
    "Always use your available tools to compute.",
  tools: {
    sum_numbers: sumNumbers,
    multiply_numbers: multiplyNumbers,
    subtract_numbers: subtractNumbers,
    divide_numbers: divideNumbers,
    power: power,
    square_root: squareRoot
  },
  toolSchemas: toolSchemas
});

// General assistant that can hand off to the calculator
const helpfulAssistant = new Agent({
  name: "helpful_assistant",
  systemPrompt:
    "You are a helpful assistant. You can assist with various tasks, but should always handoff specific tasks to specialist agents.",
  handoffs: [calculatorAssistant]
});

Notice how we create the calculator assistant first without any handoffs, then create the general assistant with the calculator in its handoffs array. This creates a clear hierarchy where the general assistant can transfer control to the specialist, but not vice versa.

Now let's test the system with different types of questions to see how it makes handoff decisions.

Let's test the system with a general knowledge question to see how the agent decides whether to handle the task itself or perform a handoff.

// Example 1: General knowledge (no handoff expected)
let messages: Array<Record<string, unknown>> = [
  { role: "user", content: "What is the capital of France?" }
];
let [, response] = await helpfulAssistant.run(messages);
console.log(response);

When we run this test, the general assistant recognizes that this is a straightforward factual question that doesn't require mathematical expertise:

Paris.

The agent handled this question directly without any handoffs or tool calls, demonstrating that it can distinguish between tasks it should handle itself and those requiring specialist expertise. Now let's test with a mathematical problem that should trigger a handoff to see the complete control transfer process in action.

Now let's test with a mathematical problem that should trigger a handoff to demonstrate the complete control transfer process.

// Example 2: Math problem (handoff expected to calculator assistant)
messages = [{ role: "user", content: "Solve x^2 - 5x + 6 = 0." }];
[, response] = await helpfulAssistant.run(messages);

console.log("\n=== Final Response ===\n");
console.log(response);

This test demonstrates the complete handoff process in action:

🔄 Handoff to: calculator_assistant
📝 Reason: Solve the quadratic equation accurately and efficiently.
🔧 Tool called: power({"base":-5,"exponent":2})
🔧 Tool called: multiply_numbers({"a":4,"b":6})
🔧 Tool called: subtract_numbers({"a":25,"b":24})
🔧 Tool called: square_root({"number":1})

=== Final Response ===

The solutions are x = 2 and x = 3. 
(Factors: x^2 − 5x + 6 = (x − 2)(x − 3) = 0)

The execution trace shows the complete handoff process: the general assistant recognized that this was a mathematical problem requiring specialist expertise, initiated a handoff to the calculator assistant with a clear reason, and then the calculator assistant took complete control of the conversation. The calculator assistant used its mathematical tools to solve the equation step by step and provided the final response directly to the user.

Understanding when to apply each pattern is crucial for building effective agent systems.

Use agents as tools when you need an orchestrating agent to maintain control and synthesize multiple specialist inputs into a unified response. This works well for complex tasks requiring coordination across different domains, like planning a trip that involves flights, hotels, and restaurants.

Use handoffs when a specialist is clearly better equipped to handle the entire conversation from a certain point forward. This is ideal when the task falls entirely within one domain of expertise and the specialist can provide more value through direct interaction than filtered through an orchestrator.

The key question: Does the task require orchestration and synthesis, or does it need deep specialization with direct user interaction? Choose accordingly.

When implementing handoffs, success depends heavily on designing clear decision boundaries and robust error handling. The most effective handoff systems define explicit criteria in agent prompts, helping agents make confident transfer decisions rather than hesitating between options. For example, your general assistant should know precisely when mathematical problems warrant a calculator handoff versus when they can provide basic arithmetic directly.

Key practices for reliable handoffs include:

• Define clear handoff criteria in agent prompts so agents know exactly when to transfer control
• Implement robust error handling for failed handoffs with graceful fallbacks
• Use descriptive handoff reasons for debugging and system transparency
• Design handoff chains with clear direction to avoid circular transfers

The biggest pitfall to avoid is creating circular handoffs where agents pass control back and forth indefinitely. Design your handoff chains with clear directionality and avoid giving agents too many transfer options, which can lead to decision paralysis. Remember that handoffs should feel like natural conversation flows, similar to being transferred to the right department in a well-organized company rather than bouncing between confused representatives.

You've now mastered the handoff pattern, a powerful approach for building agent systems where specialists can take complete control of conversations when their expertise is needed. This pattern differs fundamentally from agent-as-tool delegation because it transfers not just the task, but the entire conversation ownership to the most appropriate agent.

In your upcoming practice exercises, you'll build multi-agent systems with complex handoff chains, where agents can intelligently route conversations through multiple specialists based on the evolving needs of each interaction. This foundation will enable you to create sophisticated agent ecosystems that can handle diverse, complex tasks while maintaining clear specialization and efficient resource utilization.