Skip to main content
The handoff tool enables agents to pass the conversation to a different agent defined in the same configuration file. Unlike transfer_task — which delegates a sub-task and returns the result to the caller — a handoff transfers full conversational control. The receiving agent takes over and can hand off further. This pattern is useful for routing workflows, where a coordinator decides which specialist should own the conversation.

​
Configuration

Handoffs are configured at the agent level, not as a toolset. Add a handoffs list to declare which agents this agent can hand off to: 
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Search coordinator
    instruction: Route queries to the appropriate search agent.
    handoffs:
      - web_search
      - filesystem_search

  web_search:
    model: openai/gpt-4o
    description: Web search specialist
    instruction: Search the web and hand off to the summarizer.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
    handoffs:
      - summarizer

  summarizer:
    model: anthropic/claude-sonnet-4-5
    description: Presents search results clearly
    instruction: Summarize the findings and hand back to root.
    handoffs:
      - root
The handoff tool is automatically added to each agent that has a handoffs list. You do not add it manually as a toolset.

​
Handoff tool parameters

When the agent calls handoff, it passes:
ParameterTypeRequiredDescription
agentstringYesThe name of the agent to hand off to (must be in handoffs list).

​
Full example

The following example shows a multi-agent workflow where a coordinator routes between web search and filesystem search, with redaction, tabulation, and summarization steps:
handoff.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Search coordinator
    instruction: |
      Route queries to web_search or filesystem_search based on the user's request.
    handoffs:
      - web_search
      - filesystem_search

  web_search:
    model: openai/gpt-4o
    description: Web search specialist
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
    handoffs:
      - summarizer

  filesystem_search:
    model: openai/gpt-4o
    description: Filesystem search specialist
    toolsets:
      - type: filesystem
    handoffs:
      - tabulator
      - redactor

  redactor:
    model: openai/gpt-4o-mini
    description: Redacts sensitive information from file contents
    instruction: Replace API keys, passwords, and secrets with [REDACTED].
    handoffs:
      - tabulator

  tabulator:
    model: openai/gpt-4o-mini
    description: Formats data into markdown tables
    handoffs:
      - summarizer

  summarizer:
    model: anthropic/claude-sonnet-4-5
    description: Presents results clearly to the user
    handoffs:
      - root

​
Handoff vs. transfer task vs. background agents

handofftransfer_taskbackground_agents
Control flowTransfers ownership — calling agent exitsReturns result to callerCaller continues while sub-agent runs
Best forRouting workflows, pipelinesDelegating to a specialistFan-out parallel work
Configurationhandoffs list on the agentsub_agents listsub_agents list
See A2A Protocol for details on serving agents as A2A endpoints and connecting to remote agents via the handoff tool or a2a tool.

Transfer task

Delegate a task and receive the result.

A2A tool

Connect to remote agents via A2A.

Multi-agent

Multi-agent architecture patterns.

A2A protocol

Serve and consume A2A-compatible agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us