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 cleanly 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.

The handoffs parameter accepts an array of other Agent instances to which this agent can transfer control. TypeScript's object destructuring pattern in the constructor allows us to specify default values directly in the parameter list, making the API clean and intuitive. We use the spread operator (...) to create shallow copies of the arrays and objects, protecting against external mutation while maintaining the original data. 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.

The handoff 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 use TypeScript's template literals (backticks) to dynamically include the list of available agents in the description. We need both map() and JSON.stringify() for different reasons: map() extracts just the agent names from the Agent objects (otherwise we'd try to stringify entire Agent instances with all their methods and properties), transforming the handoffs array into a simple string array like ["calculator_assistant", "researcher_assistant"]. Then JSON.stringify() converts this array into a properly formatted string representation that includes brackets and quotes, making it clear to Claude that these are distinct string values rather than just comma-separated words. Now we need to make this handoff schema available to the agent alongside its other tools.

To make handoffs work seamlessly, we need to modify the buildRequestArgs method to include the handoff schema when handoff targets are available.

This modification ensures that the handoff tool is automatically available to any agent that has handoff targets configured, without requiring manual schema management. The method builds a complete list of available tools by combining regular tool schemas with the handoff schema when appropriate. TypeScript's explicit return type annotation (Anthropic.Messages.MessageCreateParams) provides compile-time type safety, ensuring we always return the correct structure for the API call. We use the spread operator with push() to add multiple tool schemas at once and check array lengths explicitly with .length > 0 rather than relying on truthy checks. 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.

The core of the handoff pattern lies in the callHandoff method, which handles the actual transfer of control from one agent to another. This method performs several critical operations and uses TypeScript's async/await pattern to handle the asynchronous agent execution:

The method executes the following steps in sequence:

1. Parameter extraction: Gets the target agent's name and handoff reason from the tool use input for logging and agent lookup. We use optional chaining (?.) to safely access potentially undefined properties.

2. Agent lookup: Uses TypeScript's find() method to search through the handoffs array for an agent matching the requested name. Unlike generator expressions, find() returns undefined if no match is found, which we explicitly check and handle.

3. Context cleaning: Removes the assistant message containing the handoff tool call so the target agent receives a clean conversation history without seeing the internal handoff mechanics. The logic first checks if the array is not empty () to prevent errors, then confirms the last message is from the assistant before using the method to create a new array without that last message.

The main execution loop in the run method needs to detect handoff tool 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.

This code creates two distinct execution paths based on handoff success:

Successful handoffs: When handoffSuccess is true, the method immediately returns the target agent's complete response using return handoffResult, bypassing all remaining tool processing and ending the current agent's involvement in the conversation. This is the key difference between handoffs and tool calls—handoffs transfer complete control rather than just collecting results.

Failed handoffs: When handoffSuccess is , the contains a tool result block with an error message like This gets pushed into the array just like any other tool result. Later in the tool processing loop, these results will be added to the messages array, which means Claude will see the error message in its next turn. The agent can then respond intelligently—perhaps by explaining the limitation to the user, suggesting alternatives, or attempting to handle the task itself instead of giving up.

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.

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. TypeScript's Record<string, Function> type annotation explicitly declares that mathTools is an object mapping string keys to function values, providing type safety when accessing tools. We use fs.readFileSync() to synchronously read the schemas file and JSON.parse() to convert the JSON string into a JavaScript object. The new Agent({ ... }) syntax with object literals makes the instantiation clean and self-documenting. 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.

We use let for the messages variable because we'll reassign it in the next test, and TypeScript's explicit type annotation (Anthropic.MessageParam[]) ensures type safety for the message array. The await keyword is essential since run() is an async method that returns a Promise. Array destructuring ([resultMessages, response]) cleanly unpacks the tuple returned by the agent, and we use console.log() to display the output.

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

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.

We reassign the messages variable with a new array containing the mathematical question, demonstrating TypeScript's mutable variable handling with let. The same async/await pattern and array destructuring syntax apply here, maintaining consistency with the previous test.

This test demonstrates the complete handoff process in action:

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
• Always clean conversation context by removing handoff tool calls before transferring
• 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.