Merge pull request #2033 from dgageot/board/tell-me-when-the-tool-run-background-age-da00ac7d

rumpl · web-flow · commit 8ad9626329fd · 2026-03-10T22:28:36.000+01:00
feat: make background_agents a standalone toolset
diff --git a/agent-schema.json b/agent-schema.json
@@ -801,7 +801,8 @@
             "lsp",
             "user_prompt",
             "openapi",
-            "model_picker"
+            "model_picker",
+            "background_agents"
           ]
         },
         "instruction": {
@@ -998,7 +999,8 @@
                 "a2a",
                 "lsp",
                 "user_prompt",
-                "model_picker"
+                "model_picker",
+                "background_agents"
               ]
             }
           }
@@ -1082,6 +1084,13 @@
               ]
             }
           ]
+        },
+        {
+          "properties": {
+            "type": {
+              "const": "background_agents"
+            }
+          }
         }
       ]
     },
diff --git a/docs/concepts/multi-agent/index.md b/docs/concepts/multi-agent/index.md
@@ -45,6 +45,50 @@ transfer_task(
 
 </div>
 
+## 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:
+
+```yaml
+agents:
+  root:
+    model: anthropic/claude-sonnet-4-0
+    description: Research coordinator
+    sub_agents: [researcher, analyst, writer]
+    toolsets:
+      - type: think
+      - type: background_agents
+```
+
+The coordinator can then:
+
+1. **Dispatch** several tasks at once with `run_background_agent` — each returns a task ID immediately
+2. **Monitor** progress with `list_background_agents` or `view_background_agent`
+3. **Collect** results once tasks complete
+4. **Cancel** tasks that are no longer needed with `stop_background_agent`
+
+```bash
+# Start two tasks in parallel
+run_background_agent(agent="researcher", task="Find recent papers on LLM agents")
+run_background_agent(agent="analyst", task="Analyze our current architecture")
+
+# Check on all tasks
+list_background_agents()
+
+# Read results when ready
+view_background_agent(task_id="agent_task_abc123")
+```
+
+<div class="callout callout-tip">
+<div class="callout-title">💡 When to use which
+</div>
+  <p><strong><code>transfer_task</code></strong> — simple, sequential delegation. Best when the coordinator needs the result before deciding what to do next.</p>
+  <p><strong><code>background_agents</code></strong> — parallel, async delegation. Best when multiple independent tasks can run simultaneously.</p>
+
+</div>
+
 ## Example: Development Team
 
 ```yaml
diff --git a/docs/configuration/tools/index.md b/docs/configuration/tools/index.md
@@ -180,6 +180,31 @@ toolsets:
 
 The `transfer_task` tool is automatically available when an agent has `sub_agents`. Allows delegating tasks to sub-agents. No configuration needed — it's enabled implicitly.
 
+### Background Agents
+
+Dispatch work to sub-agents concurrently and collect results asynchronously. Unlike `transfer_task` (which blocks until the sub-agent finishes), background agent tasks run in parallel — the orchestrator can start several tasks, do other work, and check on them later.
+
+```yaml
+toolsets:
+  - type: background_agents
+```
+
+| Operation                | Description                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------ |
+| `run_background_agent`   | Start a sub-agent task in the background; returns a task ID immediately                          |
+| `list_background_agents` | List all background tasks with their status and runtime                                          |
+| `view_background_agent`  | View live output or final result of a task by ID                                                 |
+| `stop_background_agent`  | Cancel a running task by ID                                                                      |
+
+No configuration options. Requires the agent to have `sub_agents` configured so the background tasks have agents to dispatch to.
+
+<div class="callout callout-tip">
+<div class="callout-title">💡 Tip
+</div>
+  <p>Use <code>background_agents</code> when your orchestrator needs to fan out work to multiple specialists in parallel — for example, researching several topics simultaneously or running independent code analyses side by side.</p>
+
+</div>
+
 ### LSP (Language Server Protocol)
 
 Connect to language servers for code intelligence: go-to-definition, find references, diagnostics, and more.
diff --git a/e2e/testdata/cassettes/TestA2AServer_MultiAgent.yaml b/e2e/testdata/cassettes/TestA2AServer_MultiAgent.yaml
diff --git a/examples/README.md b/examples/README.md
@@ -56,3 +56,4 @@ These examples are groups of agents working together. Each of them is specialize
 | [finance.yaml](finance.yaml)         | Financial research and analysis         |            |       |      | ✓     |        | [duckduckgo](https://hub.docker.com/mcp/server/duckduckgo/overview) | ✓          |
 | [shared-todo.yaml](shared-todo.yaml) | Shared todo item manager                |            |       | ✓    |       |        |                                                                                | ✓          |
 | [pr-reviewer-bedrock.yaml](pr-reviewer-bedrock.yaml) | PR review toolkit (Bedrock) | ✓          | ✓     |      |       |        |                                                                                | ✓          |
+| [background_agents.yaml](background_agents.yaml) | Parallel research with background agents |          |       |      | ✓     |        | [duckduckgo](https://hub.docker.com/mcp/server/duckduckgo/overview) | ✓          |
diff --git a/examples/background_agents.yaml b/examples/background_agents.yaml
@@ -0,0 +1,49 @@
+#!/usr/bin/env docker agent run
+
+# This example demonstrates the background_agents toolset, which lets a
+# coordinator dispatch work to multiple sub-agents in parallel rather than
+# waiting for each one sequentially.
+#
+# The coordinator fans out research tasks to two specialists at the same time,
+# monitors their progress, and synthesises a final answer once both are done.
+
+agents:
+  root:
+    model: anthropic/claude-sonnet-4-0
+    description: Research coordinator that dispatches work in parallel
+    instruction: |
+      You are a research coordinator. When the user asks a question:
+
+      1. Break the question into independent research tasks.
+      2. Dispatch each task to the appropriate sub-agent using
+         `run_background_agent` so they run in parallel.
+      3. Use `list_background_agents` or `view_background_agent` to check
+         progress and collect results.
+      4. Synthesise the findings into a clear, well-structured answer.
+
+      Always run independent tasks concurrently — do not wait for one to
+      finish before starting the next.
+    sub_agents: [web_researcher, code_analyst]
+    toolsets:
+      - type: think
+      - type: background_agents
+
+  web_researcher:
+    model: openai/gpt-4o
+    description: Searches the web for information and summarises findings
+    instruction: |
+      You are a web researcher. Use the search tools to find relevant,
+      up-to-date information. Provide concise summaries with sources.
+    toolsets:
+      - type: mcp
+        ref: docker:duckduckgo
+
+  code_analyst:
+    model: anthropic/claude-sonnet-4-0
+    description: Analyses local code and provides technical insights
+    instruction: |
+      You are a code analyst. Read the codebase to answer technical
+      questions. Reference specific files and line numbers in your answers.
+    toolsets:
+      - type: filesystem
+      - type: shell
diff --git a/pkg/config/latest/validate.go b/pkg/config/latest/validate.go
@@ -152,6 +152,8 @@ func (t *Toolset) validate() error {
 		if len(t.Models) == 0 {
 			return errors.New("model_picker toolset requires at least one model in the 'models' list")
 		}
+	case "background_agents":
+		// no additional validation needed
 	}
 
 	return nil
diff --git a/pkg/runtime/loop.go b/pkg/runtime/loop.go
@@ -24,27 +24,21 @@ import (
 	"github.com/docker/docker-agent/pkg/telemetry"
 	"github.com/docker/docker-agent/pkg/tools"
 	"github.com/docker/docker-agent/pkg/tools/builtin"
-	agenttool "github.com/docker/docker-agent/pkg/tools/builtin/agent"
 )
 
-// bgAgentHandler wraps a background-agent method as a ToolHandlerFunc.
-func (r *LocalRuntime) bgAgentHandler(fn func(context.Context, *session.Session, tools.ToolCall) (*tools.ToolCallResult, error)) ToolHandlerFunc {
-	return func(ctx context.Context, sess *session.Session, tc tools.ToolCall, _ chan Event) (*tools.ToolCallResult, error) {
-		return fn(ctx, sess, tc)
-	}
-}
-
 // registerDefaultTools wires up the built-in tool handlers (delegation,
 // background agents, model switching) into the runtime's tool dispatch map.
 func (r *LocalRuntime) registerDefaultTools() {
 	r.toolMap[builtin.ToolNameTransferTask] = r.handleTaskTransfer
 	r.toolMap[builtin.ToolNameHandoff] = r.handleHandoff
 	r.toolMap[builtin.ToolNameChangeModel] = r.handleChangeModel
 	r.toolMap[builtin.ToolNameRevertModel] = r.handleRevertModel
-	r.toolMap[agenttool.ToolNameRunBackgroundAgent] = r.bgAgentHandler(r.bgAgents.HandleRun)
-	r.toolMap[agenttool.ToolNameListBackgroundAgents] = r.bgAgentHandler(r.bgAgents.HandleList)
-	r.toolMap[agenttool.ToolNameViewBackgroundAgent] = r.bgAgentHandler(r.bgAgents.HandleView)
-	r.toolMap[agenttool.ToolNameStopBackgroundAgent] = r.bgAgentHandler(r.bgAgents.HandleStop)
+
+	r.bgAgents.RegisterHandlers(func(name string, fn func(context.Context, *session.Session, tools.ToolCall) (*tools.ToolCallResult, error)) {
+		r.toolMap[name] = func(ctx context.Context, sess *session.Session, tc tools.ToolCall, _ chan Event) (*tools.ToolCallResult, error) {
+			return fn(ctx, sess, tc)
+		}
+	})
 }
 
 // finalizeEventChannel performs cleanup at the end of a RunStream goroutine:
diff --git a/pkg/teamloader/registry.go b/pkg/teamloader/registry.go
@@ -20,6 +20,7 @@ import (
 	"github.com/docker/docker-agent/pkg/tools"
 	"github.com/docker/docker-agent/pkg/tools/a2a"
 	"github.com/docker/docker-agent/pkg/tools/builtin"
+	agenttool "github.com/docker/docker-agent/pkg/tools/builtin/agent"
 	"github.com/docker/docker-agent/pkg/tools/mcp"
 )
 
@@ -77,6 +78,7 @@ func NewDefaultToolsetRegistry() *ToolsetRegistry {
 	r.Register("user_prompt", createUserPromptTool)
 	r.Register("openapi", createOpenAPITool)
 	r.Register("model_picker", createModelPickerTool)
+	r.Register("background_agents", createBackgroundAgentsTool)
 	return r
 }
 
@@ -347,3 +349,7 @@ func createModelPickerTool(_ context.Context, toolset latest.Toolset, _ string,
 	}
 	return builtin.NewModelPickerTool(toolset.Models), nil
 }
+
+func createBackgroundAgentsTool(_ context.Context, _ latest.Toolset, _ string, _ *config.RuntimeConfig, _ string) (tools.ToolSet, error) {
+	return agenttool.NewToolSet(), nil
+}
diff --git a/pkg/teamloader/teamloader.go b/pkg/teamloader/teamloader.go
@@ -27,7 +27,6 @@ import (
 	"github.com/docker/docker-agent/pkg/team"
 	"github.com/docker/docker-agent/pkg/tools"
 	"github.com/docker/docker-agent/pkg/tools/builtin"
-	agenttool "github.com/docker/docker-agent/pkg/tools/builtin/agent"
 	"github.com/docker/docker-agent/pkg/tools/codemode"
 )
 
@@ -473,7 +472,7 @@ func getToolsForAgent(ctx context.Context, a *latest.AgentConfig, parentDir stri
 	}
 
 	if len(a.SubAgents) > 0 {
-		toolSets = append(toolSets, builtin.NewTransferTaskTool(), agenttool.NewToolSet())
+		toolSets = append(toolSets, builtin.NewTransferTaskTool())
 	}
 	if len(a.Handoffs) > 0 {
 		toolSets = append(toolSets, builtin.NewHandoffTool())
diff --git a/pkg/tools/builtin/agent/agent.go b/pkg/tools/builtin/agent/agent.go
@@ -384,23 +384,40 @@ func (h *Handler) StopAll() {
 	h.wg.Wait()
 }
 
-// toolSet is a lightweight ToolSet that returns just the tool definitions
-// without requiring a Runner. Used by teamloader to register tool schemas.
-type toolSet struct{}
+// RegisterHandlers adds all background agent tool handlers to the given
+// dispatch map, keyed by tool name.
+func (h *Handler) RegisterHandlers(register func(name string, fn func(context.Context, *session.Session, tools.ToolCall) (*tools.ToolCallResult, error))) {
+	register(ToolNameRunBackgroundAgent, h.HandleRun)
+	register(ToolNameListBackgroundAgents, h.HandleList)
+	register(ToolNameViewBackgroundAgent, h.HandleView)
+	register(ToolNameStopBackgroundAgent, h.HandleStop)
+}
 
-// NewToolSet returns a ToolSet for registering background agent tool definitions.
-// This does not require a Runner and is suitable for use in teamloader.
+// NewToolSet returns a lightweight ToolSet for registering background agent
+// tool definitions and instructions. It does not require a Runner and is
+// suitable for use in the teamloader registry.
 func NewToolSet() tools.ToolSet {
 	return &toolSet{}
 }
 
-func (t *toolSet) Tools(ctx context.Context) ([]tools.Tool, error) {
+// toolSet provides tool definitions and instructions without a Runner.
+type toolSet struct{}
+
+func (t *toolSet) Tools(context.Context) ([]tools.Tool, error) {
 	return backgroundAgentTools()
 }
 
-// Tools returns the four background agent tool definitions.
-func (h *Handler) Tools(ctx context.Context) ([]tools.Tool, error) {
-	return backgroundAgentTools()
+func (t *toolSet) Instructions() string {
+	return `# Background Agent Tasks
+
+Use background agent tasks to dispatch work to sub-agents concurrently.
+
+- **run_background_agent**: Start a command, returns task ID. The sub-agent runs with all tools pre-approved — use only with trusted sub-agents and well-scoped tasks.
+- **list_background_agents**: Show all tasks with status and runtime
+- **view_background_agent**: Get output and status of a task by task_id
+- **stop_background_agent**: Terminate a task by task_id
+
+**Notes**: Output capped at 10MB per task. All tasks auto-terminate when the agent stops.`
 }
 
 func backgroundAgentTools() ([]tools.Tool, error) {
diff --git a/pkg/tools/builtin/agent/agent_test.go b/pkg/tools/builtin/agent/agent_test.go
@@ -538,9 +538,9 @@ func TestHandler_ConcurrentAccess(t *testing.T) {
 
 // --- Tools ---
 
-func TestTools_ReturnsFourTools(t *testing.T) {
-	h := NewHandler(&mockRunner{})
-	toolsList, err := h.Tools(t.Context())
+func TestNewToolSet_ReturnsFourTools(t *testing.T) {
+	ts := NewToolSet()
+	toolsList, err := ts.Tools(t.Context())
 	require.NoError(t, err)
 	assert.Len(t, toolsList, 4)
 
@@ -553,3 +553,16 @@ func TestTools_ReturnsFourTools(t *testing.T) {
 	assert.Contains(t, names, ToolNameViewBackgroundAgent)
 	assert.Contains(t, names, ToolNameStopBackgroundAgent)
 }
+
+func TestNewToolSet_Instructions(t *testing.T) {
+	ts := NewToolSet()
+	instructable, ok := ts.(tools.Instructable)
+	require.True(t, ok, "NewToolSet should implement Instructable")
+
+	instructions := instructable.Instructions()
+	assert.NotEmpty(t, instructions)
+	assert.Contains(t, instructions, "run_background_agent")
+	assert.Contains(t, instructions, "list_background_agents")
+	assert.Contains(t, instructions, "view_background_agent")
+	assert.Contains(t, instructions, "stop_background_agent")
+}

Original file line number	Diff line number	Diff line change
`@@ -801,7 +801,8 @@`
`801`	`801`	`"lsp",`
`802`	`802`	`"user_prompt",`
`803`	`803`	`"openapi",`
`804`		`- "model_picker"`
	`804`	`+ "model_picker",`
	`805`	`+ "background_agents"`
`805`	`806`	`]`
`806`	`807`	`},`
`807`	`808`	`"instruction": {`
`@@ -998,7 +999,8 @@`
`998`	`999`	`"a2a",`
`999`	`1000`	`"lsp",`
`1000`	`1001`	`"user_prompt",`
`1001`		`- "model_picker"`
	`1002`	`+ "model_picker",`
	`1003`	`+ "background_agents"`
`1002`	`1004`	`]`
`1003`	`1005`	`}`
`1004`	`1006`	`}`
`@@ -1082,6 +1084,13 @@`
`1082`	`1084`	`]`
`1083`	`1085`	`}`
`1084`	`1086`	`]`
	`1087`	`+ },`
	`1088`	`+ {`
	`1089`	`+ "properties": {`
	`1090`	`+ "type": {`
	`1091`	`+ "const": "background_agents"`
	`1092`	`+ }`
	`1093`	`+ }`
`1085`	`1094`	`}`
`1086`	`1095`	`]`
`1087`	`1096`	`},`
Original file line number	Diff line number	Diff line change
`@@ -152,6 +152,8 @@ func (t *Toolset) validate() error {`
`152`	`152`	`if len(t.Models) == 0 {`
`153`	`153`	`return errors.New("model_picker toolset requires at least one model in the 'models' list")`
`154`	`154`	`}`
	`155`	`+ case "background_agents":`
	`156`	`+ // no additional validation needed`
`155`	`157`	`}`
`156`	`158`
`157`	`159`	`return nil`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@ import (`
`20`	`20`	`"github.com/docker/docker-agent/pkg/tools"`
`21`	`21`	`"github.com/docker/docker-agent/pkg/tools/a2a"`
`22`	`22`	`"github.com/docker/docker-agent/pkg/tools/builtin"`
	`23`	`+ agenttool "github.com/docker/docker-agent/pkg/tools/builtin/agent"`
`23`	`24`	`"github.com/docker/docker-agent/pkg/tools/mcp"`
`24`	`25`	`)`
`25`	`26`
`@@ -77,6 +78,7 @@ func NewDefaultToolsetRegistry() *ToolsetRegistry {`
`77`	`78`	`r.Register("user_prompt", createUserPromptTool)`
`78`	`79`	`r.Register("openapi", createOpenAPITool)`
`79`	`80`	`r.Register("model_picker", createModelPickerTool)`
	`81`	`+ r.Register("background_agents", createBackgroundAgentsTool)`
`80`	`82`	`return r`
`81`	`83`	`}`
`82`	`84`
`@@ -347,3 +349,7 @@ func createModelPickerTool(_ context.Context, toolset latest.Toolset, _ string,`
`347`	`349`	`}`
`348`	`350`	`return builtin.NewModelPickerTool(toolset.Models), nil`
`349`	`351`	`}`
	`352`	`+`
	`353`	`+func createBackgroundAgentsTool(_ context.Context, _ latest.Toolset, _ string, _ *config.RuntimeConfig, _ string) (tools.ToolSet, error) {`
	`354`	`+ return agenttool.NewToolSet(), nil`
	`355`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,6 @@ import (`
`27`	`27`	`"github.com/docker/docker-agent/pkg/team"`
`28`	`28`	`"github.com/docker/docker-agent/pkg/tools"`
`29`	`29`	`"github.com/docker/docker-agent/pkg/tools/builtin"`
`30`		`- agenttool "github.com/docker/docker-agent/pkg/tools/builtin/agent"`
`31`	`30`	`"github.com/docker/docker-agent/pkg/tools/codemode"`
`32`	`31`	`)`
`33`	`32`
`@@ -473,7 +472,7 @@ func getToolsForAgent(ctx context.Context, a *latest.AgentConfig, parentDir stri`
`473`	`472`	`}`
`474`	`473`
`475`	`474`	`if len(a.SubAgents) > 0 {`
`476`		`- toolSets = append(toolSets, builtin.NewTransferTaskTool(), agenttool.NewToolSet())`
	`475`	`+ toolSets = append(toolSets, builtin.NewTransferTaskTool())`
`477`	`476`	`}`
`478`	`477`	`if len(a.Handoffs) > 0 {`
`479`	`478`	`toolSets = append(toolSets, builtin.NewHandoffTool())`