Code 中的 Subagent

为什么需要它

你已经知道子代理好用——但在 Code 模式下怎么定义它们？

文件位置

子代理的定义文件放在哪里？项目级和用户级两条路径

每个子代理位于自己的文件夹中，包含一个 AGENTS.md 文件：

# 项目级——随项目代码一起版本管理
.deepagents/agents/{subagent-name}/AGENTS.md

# 用户级——个人专属子代理，跨项目可用
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md

文件格式

YAML frontmatter 声明元数据，Markdown 正文作为系统提示词

一个完整的 AGENTS.md 文件由两部分组成：

---
name: researcher                                    # 子代理的唯一标识符
description: Research topics on the web before writing content  # 主代理据此决定何时委派
model: anthropic:claude-haiku-4-5-20251001          # 可选：指定小模型以降低成本
---

You are a research assistant with access to web search.

## Your Process
1. Search for relevant information
2. Summarize findings clearly

模型覆盖

用 model 字段为子代理指定不同的模型——省成本、提速度

model 是 AGENTS.md 特有的可选字段，使用 provider:model-name 格式：

---
name: general-purpose                                       # 与内置子代理同名，覆盖它
description: General-purpose agent for research and multi-step tasks
model: anthropic:claude-haiku-4-5-20251001                  # 使用 Haiku 降低成本
---

You are a general-purpose assistant.
Complete the task efficiently and return a concise summary.

覆盖内置代理

用 AGENTS.md 替换默认的 general-purpose 子代理——零代码实现

Deep Agents Code 内置了一个 general-purpose 子代理。你可以通过定义同名子代理来覆盖它：

---
name: general-purpose                                       # 与内置子代理同名，实现覆盖
description: General-purpose agent for research and multi-step tasks
model: anthropic:claude-haiku-4-5-20251001                  # 指定便宜的小模型
---

You are a general-purpose assistant.
Complete the task efficiently and return a concise summary.

当前限制

AGENTS.md 能做什么、不能做什么——了解边界才能用好它

实战演练

从零创建一个项目级子代理——三步搞定

# 第一步：创建子代理目录（目录名即子代理标识）
mkdir -p .deepagents/agents/researcher

# 第二步：创建 AGENTS.md 文件（YAML frontmatter + Markdown 正文）
cat > .deepagents/agents/researcher/AGENTS.md << 'EOF'
---
name: researcher
description: >
  Performs in-depth web research on technical topics.
  Use when you need comprehensive information requiring
  multiple searches and source verification.
model: anthropic:claude-haiku-4-5-20251001
---

You are a meticulous research assistant with access to web search tools.

## Your Workflow
1. Decompose the research question into searchable queries
2. Execute searches systematically
3. Cross-reference findings across sources
4. Synthesize a comprehensive but concise summary

## Output Format
- Executive Summary (2-3 sentences)
- Key Findings (bullet points with sources)
- Confidence Level (high/medium/low)
- Recommended Next Steps

Keep your response under 500 words to maintain context efficiency.
EOF

# 第三步：提交到 Git，让团队成员也能使用该子代理
git add .deepagents/agents/researcher/AGENTS.md
git commit -m "feat: add researcher subagent"

多代理组合

定义多个子代理，各司其职——完整的项目级配置示例

.deepagents/agents/
├── researcher/
│   └── AGENTS.md       # 深度调研，用便宜模型
├── code-reviewer/
│   └── AGENTS.md       # 代码审查，用强模型
├── translator/
│   └── AGENTS.md       # 文档翻译，用便宜模型
└── general-purpose/
    └── AGENTS.md       # 覆盖内置通用代理

# .deepagents/agents/code-reviewer/AGENTS.md
---
name: code-reviewer                                    # 子代理名称
description: >
  Reviews code changes for bugs, security issues,
  and best practices. Use for PR reviews and code audits.
model: anthropic:claude-opus-4-7                       # 代码审查需要强推理能力，用 Opus
---

You are a senior code reviewer. Focus on:
1. Correctness and edge cases
2. Security vulnerabilities
3. Performance implications
4. Code style and maintainability

Rate each finding as critical/warning/info.
Provide specific fix suggestions.

常见问题

子代理没加载？没被调用？模型没生效？逐个排查

本章回顾

AGENTS.md 是 Deep Agents Code 中定义子代理的声明式方案

延伸阅读