Background Agents Tool
Dispatch work to sub-agents concurrently and collect results asynchronously.
Overview
The background agents tool lets an orchestrator 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.
Available Tools
| Tool | Description |
|---|---|
run_background_agent |
Start a sub-agent task in the background; returns a task ID |
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 |
Configuration
toolsets:
- type: background_agents
No configuration options. Requires the agent to have sub_agents configured so the background tasks have agents to dispatch to.
Example
agents:
coordinator:
model: openai/gpt-4o
description: Orchestrates parallel research
instruction: Fan out research tasks and synthesize results.
sub_agents: [researcher]
toolsets:
- type: background_agents
- type: think
researcher:
model: openai/gpt-4o
description: Web researcher
instruction: Research topics thoroughly.
toolsets:
- type: mcp
ref: docker:duckduckgo
💡 When to Use
Use background_agents 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.