Skip to main content
The transfer_task tool allows an orchestrator agent to delegate a task to a specialized sub-agent and receive the result back. This is the primary mechanism for synchronous multi-agent orchestration. You do not need to add it manually as a toolset — transfer_task is automatically available on any agent that has a sub_agents list configured.

​
Configuration

Configure sub_agents on the orchestrator agent. The transfer_task tool is added automatically: 
agents:
  coordinator:
    model: openai/gpt-4o
    description: Coordinates work across specialists
    instruction: Analyze requests and delegate to the right specialist.
    sub_agents: [developer, researcher]

  developer:
    model: anthropic/claude-sonnet-4-0
    description: Expert software developer
    instruction: Write clean, production-ready code.
    toolsets:
      - type: filesystem
      - type: shell

  researcher:
    model: openai/gpt-4o
    description: Web researcher
    instruction: Search for information online.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
The coordinator agent automatically gets a transfer_task tool that can delegate to developer or researcher by name.

​
How it works

1

Orchestrator calls transfer_task

The orchestrator agent calls transfer_task with the sub-agent name and a task description.
2

Sub-agent executes the task

The sub-agent runs with its own tools and instructions to complete the task.
3

Result returned to orchestrator

The sub-agent’s final response is returned to the orchestrator as the tool result.
4

Orchestrator continues

The orchestrator uses the result to decide the next step.

​
Transfer task vs. background agents vs. handoff

transfer_taskbackground_agentshandoff
ExecutionSequential — waits for resultParallel — returns task ID immediatelyTransfers ownership — calling agent exits
ReturnsSub-agent’s resultTask ID for later pollingNothing — sub-agent takes over
Best forDelegating to one specialistFan-out parallel workRouting and pipeline workflows
Setupsub_agents listsub_agents listhandoffs list
For parallel task delegation to multiple sub-agents, see Background Agents. For routing the conversation to a different agent without returning, see Handoff.

Background agents

Dispatch work to multiple sub-agents in parallel.

Handoff

Transfer conversational control to another agent.

Multi-agent

Multi-agent architecture patterns.

Todo

Track tasks across a multi-agent workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us