diff --git a/docs/concepts/multi-agent/index.md b/docs/concepts/multi-agent/index.md index 05562a74e..a12e160f1 100644 --- a/docs/concepts/multi-agent/index.md +++ b/docs/concepts/multi-agent/index.md @@ -19,9 +19,33 @@ Complex tasks benefit from specialization. Instead of one monolithic agent tryin Each agent has its own model, tools, and instructions — optimized for its specific role. -## How Delegation Works +## Two Patterns: Delegation vs. Handoffs -Agents delegate tasks using the built-in `transfer_task` tool, which is automatically available to any agent with sub-agents. This smart delegation means agents can automatically route tasks to the most suitable specialist. +docker-agent supports two multi-agent patterns: + +| | **Delegation** (`sub_agents`) | **Handoffs** (`handoffs`) | +|---|---|---| +| **Topology** | Hierarchical (parent → child → parent) | Peer-to-peer graph (A → B → C → A) | +| **Session** | Child runs in a **sub-session** | Conversation stays in the **same session** | +| **Context** | Child gets a clean task description | Next agent sees the **full conversation history** | +| **Control flow** | Parent blocks until child finishes, then continues | Active agent switches — previous agent is no longer in the loop | +| **Tool** | `transfer_task` | `handoff` | +| **Best for** | Task delegation to specialists | Pipeline workflows, conversational routing | + +You can combine both patterns in the same configuration — an agent can have both `sub_agents` and `handoffs`. + +
+
💡 When to use which +
+

sub_agents — Use when a coordinator needs to send tasks to specialists and synthesize their results.

+

handoffs — Use when agents should take turns processing the same conversation (pipelines, routing).

+

background_agents — Use when multiple independent tasks can run simultaneously.

+ +
+ +## Delegation with `sub_agents` + +Agents delegate tasks using the built-in `transfer_task` tool, which is automatically available to any agent with `sub_agents`. The parent agent sends a task to a child agent, waits for the result, and then continues. 1. **User** sends a message to the root agent 2. **Root agent** analyzes the request and decides which sub-agent should handle it @@ -45,11 +69,89 @@ transfer_task( +## Handoffs Routing + +Handoffs are a peer-to-peer routing pattern where agents **hand off the entire conversation** to another agent. Unlike delegation, there is no sub-session — the conversation stays in a single session and the active agent simply switches. + +This pattern is ideal for: + +- **Pipeline workflows** — data flows through a chain of specialized agents +- **Conversational routing** — a coordinator routes the user to the right specialist, who can route back when done +- **Graph topologies** — agents can form cycles (A → B → C → A), enabling iterative workflows + +### How It Works + +1. **User** sends a message to the starting agent +2. **Agent A** processes the message, then calls `handoff` to route to **Agent B** +3. **Agent B** becomes the active agent and sees the **full conversation history** +4. **Agent B** can respond, use its own tools, or hand off to another agent +5. This continues until an agent responds directly without handing off + +```bash +# The handoff tool call looks like: +handoff( + agent="summarizer" +) +``` + +
+
ℹ️ Scoped Handoff Targets +
+

Each agent can only hand off to agents listed in its own handoffs array. The handoff tool is automatically injected — you don't need to add it manually.

+ +
+ +### Example + +A coordinator routes to a researcher, who hands off to a summarizer, who returns to the coordinator: + +``` +Root ──→ Researcher ──→ Summarizer ──→ Root +``` + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Coordinator that routes queries + instruction: | + Route research queries to the researcher. + handoffs: + - researcher + + researcher: + model: openai/gpt-4o + description: Web researcher + instruction: | + Search the web, then hand off to the summarizer. + toolsets: + - type: mcp + ref: docker:duckduckgo + handoffs: + - summarizer + + summarizer: + model: openai/gpt-4o-mini + description: Summarizes findings + instruction: | + Summarize the research results, then hand off + back to root. + handoffs: + - root +``` + +
+
💡 Full pipeline example +
+

For a more complex handoff graph with branching and multiple processing stages, see examples/handoff.yaml.

+ +
+ ## Parallel Delegation with Background Agents `transfer_task` is **sequential** — the coordinator waits for the sub-agent to finish before continuing. When you need to fan out work to multiple agents at the same time, use the `background_agents` toolset instead. -Add it to your coordinator’s toolsets: +Add it to your coordinator's toolsets: ```yaml agents: @@ -81,14 +183,6 @@ list_background_agents() view_background_agent(task_id="agent_task_abc123") ``` -
-
💡 When to use which -
-

transfer_task — simple, sequential delegation. Best when the coordinator needs the result before deciding what to do next.

-

background_agents — parallel, async delegation. Best when multiple independent tasks can run simultaneously.

- -
- ## Example: Development Team ```yaml @@ -213,6 +307,7 @@ toolsets: - **Give minimal tools** — Only give each agent the tools it needs for its specific role - **Use the think tool** — Give coordinators the think tool so they reason about delegation - **Use the right model** — Use capable models for complex reasoning, cheap models for simple tasks +- **Choose the right pattern** — Use `sub_agents` for hierarchical task delegation, `handoffs` for pipeline workflows and conversational routing
ℹ️ Beyond docker-agent diff --git a/docs/configuration/agents/index.md b/docs/configuration/agents/index.md index 63c31506a..ad8b0a8df 100644 --- a/docs/configuration/agents/index.md +++ b/docs/configuration/agents/index.md @@ -35,7 +35,7 @@ agents: commands: # Optional: named prompts name: "prompt text" welcome_message: string # Optional: message shown at session start - handoffs: [list] # Optional: list of A2A handoff agents + handoffs: [list] # Optional: agent names this agent can hand off to hooks: # Optional: lifecycle hooks pre_tool_use: [list] post_tool_use: [list] @@ -77,7 +77,7 @@ agents: | `skills` | boolean | ✗ | Enable automatic skill discovery from standard directories. | | `commands` | object | ✗ | Named prompts that can be run with `docker agent run config.yaml /command_name`. | | `welcome_message` | string | ✗ | Message displayed to the user when a session starts. Useful for providing context or instructions. | -| `handoffs` | array | ✗ | List of A2A agent configurations this agent can delegate to. See [A2A Protocol]({{ '/features/a2a/' | relative_url }}). | +| `handoffs` | array | ✗ | List of agent names this agent can hand off the conversation to. Enables the `handoff` tool. See [Handoffs Routing]({{ '/concepts/multi-agent/#handoffs-routing' | relative_url }}). | | `hooks` | object | ✗ | Lifecycle hooks for running commands at various points. See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | | `structured_output` | object | ✗ | Constrain agent output to match a JSON schema. See [Structured Output]({{ '/configuration/structured-output/' | relative_url }}). | diff --git a/docs/guides/tips/index.md b/docs/guides/tips/index.md index b3ee8080e..c19b2f8cd 100644 --- a/docs/guides/tips/index.md +++ b/docs/guides/tips/index.md @@ -259,18 +259,20 @@ Understand the difference between `sub_agents` and `handoffs`:

sub_agents (transfer_task)

-

Delegates task to a child, waits for result, then continues. The parent remains in control.

+

Delegates task to a child in a sub-session, waits for result, then continues. Hierarchical — the parent remains in control.

sub_agents: [researcher, writer]
-

handoffs (A2A)

-

Transfers control entirely to another agent (possibly remote). One-way handoff.

+

handoffs (peer-to-peer)

+

Hands off the entire conversation to another agent in the same session. The active agent switches and sees the full history. Agents can form cycles.

handoffs:
   - specialist
-  - namespace/remote-agent
+ - summarizer
+See Multi-Agent Systems for a detailed comparison. + ### Give Sub-Agents Clear Descriptions The root agent uses descriptions to decide which sub-agent to delegate to: