Dynamic agent configuration
A single agent needs to switch prompts or available tools based on the current workflow state.
AI Agents · Const
Handoff
Handoffs use tools and state updates to change an agent's behavior or route execution to another agent. They can be implemented with middleware in one agent or with multiple agent subgraphs.
How it works
A handoff is implemented as a tool-driven state transition: the tool returns a Command that updates state and changes the next step or agent. For subgraph handoffs, Command.PARENT routes to another agent node, while the triggering AIMessage and an acknowledging ToolMessage keep the conversation history valid.
Syntax
new Command({ goto, update })Returns
A Command that updates state and triggers routing to a new step or agent.
Key points
- Handoffs let an agent alter its behavior according to persistent workflow state.
- The transition is driven by a tool whose result is a Command that changes state and execution.
- Updating state can move execution to another workflow step or agent.
- The documented designs are one agent with middleware or multiple agent subgraphs.
- The subgraph design models each specialist as its own graph node.
Common mistakes
- When a handoff tool updates messages, return an acknowledging ToolMessage with the same tool-call ID; otherwise the conversation history is malformed.
- Use Command.PARENT when routing between distinct agent subgraphs rather than routing only within the current graph.
Example: Route to another agent
import { Command } from "@langchain/langgraph";
const handoff = new Command({
goto: "specialist",
update: { active_agent: "specialist" },
});Creates a command that updates workflow state and routes execution to a specialist node.
When to use it
Specialist routing
A request must move from one specialist agent to another.
Multi-agent subgraphs
A workflow uses distinct graph-based agents and needs explicit control over the messages passed between them.
Related
CommandCommand.PARENTToolMessageAIMessagehandoffsmiddlewareagent subgraphs