AI Agents · Function

handoff

Handoffs let tools change state so an agent can dynamically reconfigure itself or transfer control to another agent. They can be implemented with middleware for one agent or with separate agent subgraphs.

How it works

A handoff is a state-driven transfer of control. A tool changes a persistent state value and returns a Command, allowing middleware to reconfigure one agent or route execution among separate agent nodes; when messages are updated during a cross-agent handoff, the tool call and its acknowledging ToolMessage must both remain in the history.

Syntax

tool(async () => new Command({ goto: "agent_name", update: { active_agent: "agent_name" } }), options)

Returns

A Command that updates graph state and triggers a transition to another step or agent.

Key points

Handoffs make runtime behavior depend on state rather than requiring a fixed agent configuration.
A tool can persist the active step or agent across turns, giving later execution a routing signal.
The state can either reconfigure one agent or select a different agent.
The documented designs are a single agent with middleware and multiple agent subgraphs.
In the subgraph design, each distinct agent is represented as a graph node.

Common mistakes

When a handoff tool updates messages, include an acknowledging ToolMessage with the matching tool-call ID; otherwise the conversation history is malformed.
For separate subgraph agents, route back through the parent graph with Command.PARENT rather than treating the destination as a local node.
Cross-agent handoffs do not automatically define the shared context; choose which messages each receiving agent should see.

Example: Route with a handoff tool

import { createAgent } from "langchain";
import { tool } from "langchain";
import { Command } from "@langchain/langgraph";
import { z } from "zod";

const handoff = tool(
  async () =>
    new Command({
      goto: "specialist",
      update: { active_agent: "specialist" },
    }),
  {
    name: "transfer_to_specialist",
    description: "Transfer the conversation to the specialist agent.",
    schema: z.object({}),
  },
);

const agent = createAgent({
  model: "openai:gpt-4.1-mini",
  tools: [handoff],
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "I need specialist help." }],
});
console.log(result.messages.at(-1)?.content);

This illustrates the documented mechanism: a tool returns a Command that updates state and routes execution to another step or agent.

When to use it

Dynamic single-agent configuration

A single assistant needs to change its system prompt and available tools as the conversation moves between stages.

Specialist-agent delegation

Different specialists should own distinct graph nodes and receive control through explicit routing.

Stateful conversational routing

A workflow needs to retain the active stage across turns and use it to select subsequent behavior.

Interview questions

QWhat is the core mechanism of a handoff?

A handoff uses a tool to update state and return a Command. The updated state can change an agent’s configuration or route execution to another agent node.

Follow-up: How would you preserve history across separate agents? Include the AIMessage containing the handoff tool call and a matching ToolMessage acknowledging it.

QWhen should you use middleware versus multiple agent subgraphs?

Use middleware when one agent should dynamically change its prompt or tools based on state. Use multiple agent subgraphs when distinct agents should exist as separate graph nodes.

Follow-up: What is the main context-management difference? Middleware preserves the normal message flow, while separate agents require an explicit choice of messages passed between them.

QHow does a handoff move execution between agent nodes?

A handoff tool returns a Command that changes state and triggers a transition. For agent-node routing, the handoff uses Command.PARENT to identify the next node in the parent graph.

Follow-up: What history invariant must hold after the transfer? Every model tool call must have its corresponding tool response, including an artificial response for the handoff.

Command
Command.PARENT
ToolMessage
AIMessage
single agent with middleware
multiple agent subgraphs
active_agent
current_step

Source: Handoffs. Checked 2026-10-15.