mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-05-28 19:43:43 +00:00
b61ce3527b
Agent-Logs-Url: https://github.com/bytedance/deer-flow/sessions/ff389ed8-31c9-430c-85ff-cc1b52b8239c Co-authored-by: foreleven <4785594+foreleven@users.noreply.github.com>
132 lines
5.0 KiB
Plaintext
132 lines
5.0 KiB
Plaintext
import { Callout, Cards } from "nextra/components";
|
|
|
|
# Subagents
|
|
|
|
<Callout type="info" emoji="👥">
|
|
Subagents are focused workers that the Lead Agent delegates subtasks to. They
|
|
run with isolated context, keeping the main conversation clean while handling
|
|
parallel or specialized work.
|
|
</Callout>
|
|
|
|
When a task is too broad for a single reasoning thread, or when parts of it can be done in parallel, the Lead Agent delegates work to **subagents**. A subagent is a self-contained agent invocation that receives a specific task, executes it, and returns the result.
|
|
|
|
## Why subagents matter
|
|
|
|
Subagents solve two key problems in long-horizon workflows:
|
|
|
|
1. **Context isolation**: a subagent only sees the information it needs for its piece of the task, not the entire parent conversation. This keeps each agent's working context focused and tractable.
|
|
2. **Parallelism**: multiple subagents can run concurrently, allowing independent parts of a task (e.g., researching multiple topics simultaneously) to be processed in parallel.
|
|
|
|
## Built-in subagents
|
|
|
|
DeerFlow ships with two built-in subagents:
|
|
|
|
### general-purpose
|
|
|
|
A general-purpose reasoning and execution agent. Suitable for delegating complex subtasks that require multi-step reasoning, web search, file operations, and artifact production.
|
|
|
|
- **Default timeout**: 900 seconds (15 minutes)
|
|
- **Default max turns**: 160
|
|
|
|
### bash
|
|
|
|
A subagent specialized for command-line task execution inside the sandbox. Suitable for scripting, data processing, file transformation, and environment setup tasks.
|
|
|
|
- **Default timeout**: 900 seconds (15 minutes)
|
|
- **Default max turns**: 80
|
|
- **Availability**: only exposed when the sandbox's `bash` tool is available (either `allow_host_bash: true` or a container sandbox is configured)
|
|
|
|
## Delegation flow
|
|
|
|
The Lead Agent delegates work to a subagent using the built-in `task` tool:
|
|
|
|
```
|
|
task(
|
|
agent="general-purpose",
|
|
task="Research the top 5 competitors of Acme Corp and summarize their pricing",
|
|
context="Focus on B2B SaaS pricing models"
|
|
)
|
|
```
|
|
|
|
The runtime then:
|
|
|
|
1. Looks up the subagent configuration from the registry, applying any `config.yaml` overrides.
|
|
2. Creates a new agent invocation with the subagent's own prompt and tools.
|
|
3. Runs the subagent to completion (or until timeout / max turns).
|
|
4. Returns the subagent's final output to the Lead Agent as the tool result.
|
|
|
|
## Configuration
|
|
|
|
Subagent timeouts and max turns are controlled through the `subagents:` section in `config.yaml`:
|
|
|
|
```yaml
|
|
subagents:
|
|
# Default timeout in seconds for all subagents (default: 900 = 15 minutes)
|
|
timeout_seconds: 900
|
|
|
|
# Optional: override max turns for all subagents
|
|
# max_turns: 120
|
|
|
|
# Optional: per-agent overrides
|
|
agents:
|
|
general-purpose:
|
|
timeout_seconds: 1800 # 30 minutes for complex tasks
|
|
max_turns: 160
|
|
bash:
|
|
timeout_seconds: 300 # 5 minutes for quick commands
|
|
max_turns: 80
|
|
```
|
|
|
|
Per-agent overrides take priority over the global `timeout_seconds` and `max_turns` settings.
|
|
|
|
## Concurrency limits
|
|
|
|
The `SubagentLimitMiddleware` controls how many subagents the Lead Agent can invoke in parallel in a single turn. This is controlled through the per-request configuration:
|
|
|
|
- `subagent_enabled`: whether subagent delegation is active for this session
|
|
- `max_concurrent_subagents`: maximum parallel task calls in one turn (default: 3)
|
|
|
|
If the agent tries to call more subagents than the limit allows, the middleware trims the excess calls.
|
|
|
|
## ACP agents (external agents)
|
|
|
|
In addition to the built-in subagents, DeerFlow supports delegating to external agents through the **Agent Connect Protocol (ACP)**. ACP allows DeerFlow to invoke agents running as separate processes (including third-party CLI tools wrapped with an ACP adapter).
|
|
|
|
Configure ACP agents in `config.yaml`:
|
|
|
|
```yaml
|
|
acp_agents:
|
|
claude_code:
|
|
command: npx
|
|
args: ["-y", "@zed-industries/claude-agent-acp"]
|
|
description: Claude Code for implementation, refactoring, and debugging
|
|
model: null
|
|
# auto_approve_permissions: false
|
|
# env:
|
|
# ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
|
|
|
|
codex:
|
|
command: npx
|
|
args: ["-y", "@zed-industries/codex-acp"]
|
|
description: Codex CLI for repository tasks and code generation
|
|
model: null
|
|
```
|
|
|
|
The Lead Agent invokes ACP agents through the `invoke_acp_agent` built-in tool.
|
|
|
|
<Callout type="tip">
|
|
ACP agents run as child processes managed by DeerFlow. They communicate over
|
|
the ACP wire protocol. The standard CLI tools (like the plain `claude` or
|
|
`codex` commands) are not ACP-compatible by default — use the adapter
|
|
packages listed above or a compatible ACP wrapper.
|
|
</Callout>
|
|
|
|
## Custom agents as subagents
|
|
|
|
Custom agents created through the DeerFlow App UI can also be invoked as subagents using the `task` tool. When you specify `agent="my-custom-agent"`, the runtime loads that agent's configuration (skills, tool groups, model) and runs it as a subagent for the delegated task.
|
|
|
|
<Cards num={2}>
|
|
<Cards.Card title="Sandbox" href="/docs/harness/sandbox" />
|
|
<Cards.Card title="MCP Integration" href="/docs/harness/mcp" />
|
|
</Cards>
|