Claude Code 中的子 Agent 派生实现：Task Tool 完全指南

📍 导航指南

根据你的需求，选择合适的阅读路径：

🎯 想了解 Task tool？ → [Task Tool 核心机制](#Task Tool 核心机制 "#task-tool-core") - Claude Code 的实际实现
🔧 想看代码实现？ → 完整代码示例 - 从零构建派生系统
⚡ 关注性能优化？ → 并行执行机制 - 获得 2-3x 加速
📚 深入理解原理？ → 架构设计解析 - 设计思想和权衡

什么是子 Agent 派生？

子 Agent 派生（Sub-Agent Delegation） 是一种高效的架构模式，旨在通过分而治之的策略处理复杂任务。在此模式中，主 Agent (Controller) 扮演指挥官角色，负责解析用户需求并动态生成子任务计划；随后，系统会采用半动态机制（固定角色模板 + 动态任务内容）来激活对应的子 Agent，这些 Agent 接收定制化的任务参数后独立执行。这种机制既保证了执行的稳定性（通过预设模板），又兼顾了任务的灵活性（通过动态内容），最后由主 Agent 汇总所有结果。

核心工作流程

arduino 复制代码

用户复杂请求（如："写一篇技术博客"）
    ↓
主 Agent 动态制定委派计划
    ↓
任务分解为专业化子任务
    ├─ Research Agent：研究主题
    ├─ Writing Agent：撰写内容
    └─ QA Agent：质量审核
    ↓
主 Agent 聚合结果生成最终报告

一个真实的例子

假设用户请求："帮我写一篇关于 Python 装饰器的技术博客"

硬编码方式（传统）：

python 复制代码

def write_blog_hardcoded(topic):
    # 固定流程：研究 → 写作 → 审核
    research = research_agent.run(topic)
    article = writing_agent.run(research)
    final = qa_agent.run(article)
    return final

问题：

❌ 简单任务也走完整流程（浪费资源）
❌ 复杂任务可能流程不够（输出质量差）
❌ 所有任务用相同参数（无法专业化）

派生方式（Claude Code）：

python 复制代码

# 主 Agent 动态决定需要哪些步骤
plan = main_agent.create_plan(user_request)

# 可能的计划 1：简单任务
# [writing_agent]  # 直接写作，跳过研究

# 可能的计划 2：标准任务
# [research_agent, writing_agent, qa_agent]

# 可能的计划 3：深度任务
# [research_agent, analysis_agent, code_examples_agent,
#  writing_agent, seo_agent, qa_agent]

results = execute_dynamic_plan(plan)
return aggregate(results)

优势：

✅ 智能适应：根据任务复杂度自动调整
✅ 专业化：每个 Agent 针对性优化（温度、工具、提示词）
✅ 高质量：复杂任务得到充分处理
✅ 高效率：简单任务快速响应

为什么需要派生而非硬编码？

很多开发者会问："我知道任务需要研究、写作、审核三步，为什么不直接写死流程？"

硬编码的三大失败场景

场景 1：任务复杂度差异巨大

python 复制代码

# 硬编码方案
def write_blog_hardcoded(topic):
    research = research_agent.execute(topic)  # 固定调用
    article = writing_agent.execute(research)
    return qa_agent.execute(article)

# ❌ 问题 1：简单任务浪费资源
user_input = "总结一下 Python 装饰器是什么（50字）"
# → 不需要研究，但仍会执行完整流程
# → 浪费时间 + token，用户体验差

# ❌ 问题 2：复杂任务处理不足
user_input = "写一篇关于量子计算在密码学应用的综述论文"
# → 需要：文献调研 → 理论分析 → 算法研究 → 安全分析 → 撰写 → 学术审核
# → 硬编码的 3 步流程根本不够用

场景 2：领域专业化需求

python 复制代码

# 硬编码：所有任务用同一套 Agent
def analyze_hardcoded(data):
    return general_agent.analyze(data)  # 通用 Agent

# ❌ 数据分析：需要统计方法、可视化
# ❌ 法律分析：需要法规检索、风险评估
# ❌ 代码分析：需要性能分析、算法优化
# → 通用 Agent 什么都会一点，但什么都不精通

动态派生的专业化：

python 复制代码

# 数据分析请求 → 数据专家团队
plan_data = [data_cleaning_agent, statistical_analysis_agent,
             visualization_agent, insight_generation_agent]

# 法律分析请求 → 法律专家团队
plan_legal = [legal_research_agent, risk_identification_agent,
              compliance_check_agent, recommendation_agent]

# 每个领域都有专门的 Agent，输出质量远超通用 Agent

场景 3：动态依赖变化

python 复制代码

# 硬编码：固定的执行顺序
def create_marketing(product):
    research = research_agent.execute(product)      # 步骤 1
    analysis = analysis_agent.execute(research)     # 步骤 2
    copy = writing_agent.execute(analysis)          # 步骤 3
    seo = seo_agent.execute(copy)                  # 步骤 4
    return seo

# ❌ 用户已经有研究报告怎么办？
# → 仍会重复执行研究步骤，浪费资源

# ❌ 用户不需要 SEO 优化怎么办？
# → 无法跳过，必须执行完整流程

动态派生的灵活性：

python 复制代码

# 场景 1：用户提供了研究报告
user_request = "我已经有了市场研究报告（见附件），请帮我写营销文案"
# → 主 Agent 识别后跳过研究，直接从写作开始
plan = [copywriting_agent, seo_agent, review_agent]

# 场景 2：用户只要快速文案
user_request = "快速写一个产品介绍（100字）"
# → 主 Agent 识别简单任务，跳过所有分析环节
plan = [quick_writing_agent]

# 场景 3：完整营销方案
user_request = "为新产品制定完整营销策略"
# → 主 Agent 生成完整流程
plan = [market_research_agent, competitor_analysis_agent,
        positioning_agent, copywriting_agent, seo_agent,
        social_media_agent, review_agent]

核心差异总结

维度	硬编码方案 ❌	动态派生 ✅
适应性	一套流程应对所有场景	根据任务动态调整
效率	简单任务也走完整流程	简单任务快速响应
专业性	通用 Agent 什么都不精	专门 Agent 输出高质量
可扩展	新需求需要修改代码	无需修改，自动适配
维护成本	需求越多，代码越乱	核心逻辑不变，易维护
用户体验	无法个性化响应	智能理解用户意图

何时可以硬编码？

也不是完全不能硬编码，以下场景可以使用：

✅ 适合硬编码的场景：

流程极其固定：如发票生成（步骤永远不变）
性能要求极高：如实时推荐系统（毫秒级响应，无法承受动态规划开销）
合规性要求：如金融交易流程（必须严格按规定顺序）

但对于 AI Agent 场景，几乎都不满足以上条件！

Claude Code 中的实现方式

Claude Code 实现了一套完整的子 Agent 派生框架，核心是 Task Tool。

Task Tool 的设计理念

python 复制代码

# Task Tool 的核心接口（简化版）
def task_tool(
    description: str,        # 任务描述（3-5 词）
    prompt: str,            # 详细任务说明
    subagent_type: str,     # Agent 类型
    model: str = "sonnet",  # 可选模型
    run_in_background: bool = False,  # 是否后台运行
    resume: str = None      # 恢复之前的 Agent
):
    """
    启动一个专门化的子 Agent 来处理特定任务

    核心特点：
    1. 动态派生：根据需求创建专业 Agent
    2. 后台运行：支持并行执行
    3. 可恢复：支持从中断点继续
    4. 隔离执行：失败不影响其他 Agent
    """
    pass

可用的 SubAgent Types

Claude Code 预定义了多种专业化的 Agent 类型：

SubAgent Type	专长领域	温度	工具	适用场景
general-purpose	通用任务	0.5	All	复杂多步骤任务
Explore	代码探索	0.3	Glob, Grep, Read	代码库搜索、结构分析
Plan	方案设计	0.4	All	实现规划、架构设计
claude-code-guide	Claude Code 文档	0.5	WebFetch, WebSearch	Claude Code 使用指南
ollama-code-analyzer	代码审查	0.2	Code analysis	Bug、性能、安全分析
ollama-architect	架构设计	0.6	Design tools	技术选型、方案对比

一个真实的使用示例

python 复制代码

# 场景：分析代码库并生成优化建议

# Step 1: 使用 Explore Agent 探索代码结构
explore_result = task_tool(
    description="探索代码库结构",
    prompt="""
    探索这个 Python 项目的代码结构：
    1. 找到所有 Python 文件
    2. 识别主要模块和依赖关系
    3. 标记潜在的性能瓶颈
    """,
    subagent_type="Explore"
)

# Step 2: 使用 Code Analyzer Agent 深度分析
analyze_result = task_tool(
    description="深度代码分析",
    prompt=f"""
    基于以下代码结构进行深度分析：
    {explore_result}

    请识别：
    1. 性能问题
    2. 安全漏洞
    3. 代码异味
    """,
    subagent_type="ollama-code-analyzer",
    run_in_background=True  # 后台运行，不阻塞
)

# Step 3: 使用 Architect Agent 设计优化方案
plan_result = task_tool(
    description="设计优化方案",
    prompt=f"""
    基于分析结果设计优化方案：
    {analyze_result}

    请提供：
    1. 优化策略
    2. 技术选型
    3. 实施步骤
    """,
    subagent_type="ollama-architect"
)

Task Tool 核心机制

让我们深入了解 Claude Code Task Tool 的实现原理。

数据模型设计

1. SubTask 模型

python 复制代码

from pydantic import BaseModel, Field
from typing import List, Literal, Optional

class SubTask(BaseModel):
    """
    子任务数据模型

    定义了从复杂用户请求中拆解出来的独立工作单元。
    每个子任务都被分配给特定类型的专家 Agent 执行。
    """
    task_id: str  # 任务唯一标识符 (例如: "task_01")
    description: str  # 任务的详细执行说明和目标
    agent_type: Literal[
        "research",   # 信息调研与收集
        "analysis",   # 数据分析与处理
        "writing",    # 内容创作与撰写
        "coding",     # 代码开发与实现
        "planning",   # 计划制定与设计
        "qa"          # 质量检查与审核
    ]
    priority: int = Field(ge=1, le=5, default=3)  # 优先级（1最低，5最高）
    dependencies: List[str] = Field(default_factory=list)  # 前置依赖任务 ID

    # 执行配置
    temperature: Optional[float] = None  # 覆盖默认温度
    tools: Optional[List[str]] = None    # 指定可用工具

设计亮点：

✅ 使用 Literal 限制 agent_type，避免拼写错误
✅ 使用 Field 添加验证规则（优先级 1-5）
✅ 支持温度和工具的细粒度控制
✅ 默认值和工厂函数确保安全性

2. SubAgentResult 模型

python 复制代码

from datetime import datetime

class SubAgentResult(BaseModel):
    """子 Agent 执行结果"""
    task_id: str                    # 对应的任务 ID
    agent_type: str                 # 执行的 Agent 类型
    success: bool                   # 执行是否成功
    output: str                     # 执行结果内容
    error_message: Optional[str] = None  # 错误信息（如果失败）
    execution_time: float = 0.0     # 执行耗时（秒）
    timestamp: str = Field(
        default_factory=lambda: datetime.now().isoformat()
    )

    # 元数据
    model_used: Optional[str] = None     # 使用的模型
    tokens_used: Optional[int] = None    # 消耗的 tokens
    confidence: Optional[float] = None   # 结果置信度（0-1）

3. DelegationPlan 模型

python 复制代码

class DelegationPlan(BaseModel):
    """委派计划"""
    sub_tasks: List[SubTask]          # 子任务列表
    execution_order: List[str]        # 任务 ID 的执行顺序（拓扑排序后）
    rationale: str                    # 计划制定的理由

    # 执行策略
    parallel_groups: Optional[List[List[str]]] = None  # 可并行执行的任务组
    estimated_time: Optional[float] = None             # 预估总耗时

    def validate_dependencies(self) -> bool:
        """验证依赖关系是否有效"""
        task_ids = {t.task_id for t in self.sub_tasks}
        for task in self.sub_tasks:
            for dep in task.dependencies:
                if dep not in task_ids:
                    raise ValueError(f"任务 {task.task_id} 依赖的 {dep} 不存在")
        return True

    def detect_circular_dependency(self) -> Optional[List[str]]:
        """检测循环依赖"""
        # DFS 实现
        visited = set()
        rec_stack = set()

        def has_cycle(task_id: str) -> bool:
            visited.add(task_id)
            rec_stack.add(task_id)

            task = next(t for t in self.sub_tasks if t.task_id == task_id)
            for dep in task.dependencies:
                if dep not in visited:
                    if has_cycle(dep):
                        return True
                elif dep in rec_stack:
                    return True

            rec_stack.remove(task_id)
            return False

        for task in self.sub_tasks:
            if task.task_id not in visited:
                if has_cycle(task.task_id):
                    return list(rec_stack)
        return None

4. DelegationState 模型

python 复制代码

class DelegationState(BaseModel):
    """全局状态对象，在工作流的所有节点间传递"""

    # 输入
    user_request: str                # 用户原始需求（只读）

    # 规划阶段
    delegation_plan: Optional[DelegationPlan] = None  # 委派计划

    # 执行阶段
    sub_agent_results: Dict[str, SubAgentResult] = Field(
        default_factory=dict
    )  # 执行结果（task_id -> result）
    completed_tasks: List[str] = Field(
        default_factory=list
    )  # 已完成任务 ID 列表
    failed_tasks: List[str] = Field(
        default_factory=list
    )  # 失败任务 ID 列表

    # 聚合阶段
    final_report: Optional[str] = None  # 最终整合报告

    # 元数据
    workflow_start_time: Optional[str] = None
    workflow_end_time: Optional[str] = None
    total_tokens_used: int = 0

6 种 SubAgent Type 详解

每种 SubAgent 类型都经过专门优化，针对特定领域。

1. Research Agent - 信息调研专家

配置：

python 复制代码

RESEARCH_AGENT_CONFIG = {
    "temperature": 0.5,  # 平衡精确性和多样性
    "tools": ["web_search", "arxiv_search", "file_read"],
    "system_prompt": """
你是一位专业的研究员，擅长信息收集和整理。

你的职责：
1. 深入研究给定主题
2. 收集权威来源的信息
3. 整理关键发现
4. 提供引用来源

研究方法：
- 使用 web_search 查找最新信息
- 使用 arxiv_search 查找学术论文
- 使用 file_read 阅读本地文档
- 交叉验证多个来源
- 标注信息的可信度

输出格式：
## 研究主题
[主题描述]

## 关键发现
1. [发现 1]
   - 来源：[URL/文献]
   - 可信度：[高/中/低]

2. [发现 2]
   ...

## 参考资料
- [来源 1]
- [来源 2]
"""
}

使用场景：

技术调研（"研究 Python 装饰器的最佳实践"）
市场分析（"调研 AI Agent 市场现状"）
文献综述（"总结量子计算最新进展"）
竞品分析（"分析主要 LLM 框架的特点"）

实际示例：

python 复制代码

research_task = SubTask(
    task_id="task_research_1",
    description="研究 LangGraph 的核心概念和最佳实践",
    agent_type="research",
    priority=5,
    dependencies=[]
)

# Research Agent 的输出示例
result = """
## 研究主题
LangGraph 的核心概念和最佳实践

## 关键发现
1. **StateGraph 是核心抽象**
   - 来源：https://langchain-ai.github.io/langgraph/
   - 可信度：高（官方文档）
   - StateGraph 通过节点和边定义工作流
   - 每个节点是一个函数，接收和返回状态

2. **状态管理机制**
   - 来源：LangGraph Tutorial
   - 可信度：高
   - 使用 TypedDict 或 Pydantic Model 定义状态
   - 状态在节点间传递，支持增量更新

3. **最佳实践**
   - 来源：社区实践总结
   - 可信度：中
   - 使用 Pydantic Model 获得更好的类型检查
   - 节点函数保持纯函数特性
   - 使用条件边实现动态路由

## 参考资料
- https://langchain-ai.github.io/langgraph/
- https://github.com/langchain-ai/langgraph/examples
"""

2. Analysis Agent - 数据分析专家

配置：

python 复制代码

ANALYSIS_AGENT_CONFIG = {
    "temperature": 0.3,  # 更低温度，强调精确性
    "tools": ["python_repl", "data_visualization", "statistical_analysis"],
    "system_prompt": """
你是一位专业的数据分析师，擅长数据处理和洞察提炼。

你的职责：
1. 分析给定数据或信息
2. 识别模式和趋势
3. 进行统计计算
4. 提供数据支持的洞察

分析方法：
- 使用 python_repl 进行数据处理
- 使用 pandas 处理结构化数据
- 使用 numpy 进行数值计算
- 使用 matplotlib/seaborn 可视化
- 应用统计方法验证假设

输出格式：
## 分析目标
[目标描述]

## 数据概览
- 数据来源：[...]
- 样本量：[N]
- 时间范围：[...]

## 关键指标
1. [指标 1]：[值] (同比 +X%)
2. [指标 2]：[值] (环比 -Y%)

## 深度分析
### [分析维度 1]
[发现和解释]

### [分析维度 2]
[发现和解释]

## 洞察与建议
1. [洞察 1] → [建议 1]
2. [洞察 2] → [建议 2]
"""
}

使用场景：

用户行为分析（"分析用户留存率下降的原因"）
性能分析（"分析系统性能瓶颈"）
代码分析（"分析代码复杂度和可维护性"）
趋势预测（"预测下季度的增长趋势"）

3. Writing Agent - 内容创作专家

配置：

python 复制代码

WRITING_AGENT_CONFIG = {
    "temperature": 0.7,  # 更高温度，强调创造性
    "tools": ["grammar_check", "readability_score", "style_guide"],
    "system_prompt": """
你是一位资深作家，擅长内容创作和表达。

你的职责：
1. 撰写高质量的内容
2. 确保逻辑清晰、表达流畅
3. 适配目标受众
4. 保持一致的风格和语气

写作原则：
- 清晰：简洁明了，避免冗余
- 连贯：逻辑流畅，过渡自然
- 准确：事实正确，引用可靠
- 吸引：开头引人，结尾有力
- 适配：符合受众背景和需求

输出格式：
根据内容类型调整格式：
- 技术博客：标题 → 引言 → 正文（多级标题） → 总结
- 技术文档：概述 → 详细说明 → 示例 → 注意事项
- 营销文案：痛点 → 方案 → 优势 → 行动号召
"""
}

使用场景：

技术博客（"撰写关于 React Hooks 的教程"）
技术文档（"编写 API 使用文档"）
营销文案（"撰写产品介绍"）
报告撰写（"生成季度业务报告"）

4. Coding Agent - 代码开发专家

配置：

python 复制代码

CODING_AGENT_CONFIG = {
    "temperature": 0.2,  # 极低温度，确保代码准确
    "tools": ["code_executor", "linter", "formatter", "test_runner"],
    "system_prompt": """
你是一位高级软件工程师，擅长编写高质量代码。

你的职责：
1. 实现给定的功能需求
2. 编写清晰、可维护的代码
3. 遵循最佳实践和编码规范
4. 编写必要的注释和文档

编码原则：
- DRY (Don't Repeat Yourself)
- SOLID 原则
- 清晰命名
- 适当注释
- 错误处理
- 性能考虑
- 安全意识

输出格式：
## 功能说明
[功能描述]

## 代码实现
```python
[代码]

使用示例

python 复制代码

[示例代码]

注意事项

$注意点 1$
$注意点 2\] """ }$

使用场景：

功能实现（"实现用户登录功能"）
Bug 修复（"修复内存泄漏问题"）
代码重构（"重构这段代码提升可读性"）
脚本编写（"编写数据迁移脚本"）

5. Planning Agent - 计划制定专家

配置：

python 复制代码

PLANNING_AGENT_CONFIG = {
    "temperature": 0.4,  # 平衡创造性和结构性
    "tools": ["diagram_generator", "timeline_creator"],
    "system_prompt": """
你是一位项目规划专家，擅长任务分解和计划制定。

你的职责：
1. 分析复杂需求
2. 分解为可执行的子任务
3. 识别任务间的依赖关系
4. 制定合理的执行计划

规划原则：
- MECE 原则（相互独立，完全穷尽）
- 由粗到细，逐步细化
- 明确依赖关系
- 考虑风险因素
- 预留缓冲时间

输出格式：
## 需求分析
[需求概述]

## 任务分解
1. [任务 1]
   - 目标：[...]
   - 产出：[...]
   - 依赖：[...]

2. [任务 2]
   ...

## 执行计划
阶段 1：[名称]
├─ 任务 A
├─ 任务 B
└─ 任务 C

阶段 2：[名称]
...

## 风险评估
- [风险 1] → [应对措施]
- [风险 2] → [应对措施]
"""
}

使用场景：

项目规划（"规划新功能的开发计划"）
学习计划（"制定 Python 学习路线"）
迁移计划（"规划系统架构迁移步骤"）
优化计划（"制定性能优化方案"）

6. QA Agent - 质量审核专家

配置：

python 复制代码

QA_AGENT_CONFIG = {
    "temperature": 0.3,  # 低温度，确保严格审核
    "tools": ["grammar_check", "fact_check", "plagiarism_check", "code_review"],
    "system_prompt": """
你是一位质量审核专家，擅长发现问题和提出改进建议。

你的职责：
1. 审核内容质量
2. 识别错误和问题
3. 评估符合度
4. 提供改进建议

审核维度：
- 准确性：事实是否正确
- 完整性：是否遗漏重要内容
- 一致性：风格和术语是否统一
- 可读性：是否清晰易懂
- 合规性：是否符合要求

输出格式：
## 审核摘要
- 审核对象：[...]
- 审核标准：[...]
- 总体评分：[X/10]

## 发现的问题
### 严重问题（Must Fix）
1. [问题描述]
   - 位置：[...]
   - 影响：[...]
   - 建议：[...]

### 一般问题（Should Fix）
...

### 优化建议（Nice to Have）
...

## 修改后的版本
[修改后的完整内容]
"""
}

使用场景：

内容审核（"审核技术博客的质量"）
代码审查（"审查代码的安全性和性能"）
文档审核（"审核 API 文档的完整性"）
合规检查（"检查内容是否符合规范"）

Agent 配置对比表

Agent 类型	温度	主要工具	输出特点	典型耗时
Research	0.5	web_search, arxiv	信息丰富，来源可靠	20-40s
Analysis	0.3	python_repl, visualization	数据驱动，洞察深刻	15-30s
Writing	0.7	grammar_check, style_guide	流畅易读，结构清晰	10-25s
Coding	0.2	code_executor, linter	准确可靠，规范标准	15-35s
Planning	0.4	diagram_generator	结构完整，逻辑清晰	10-20s
QA	0.3	fact_check, plagiarism	严格细致，建议具体	10-20s

温度设置的原理：

低温度（0.2-0.3）：输出更确定、更一致，适合代码、分析、审核
中温度（0.4-0.5）：平衡创造性和准确性，适合研究、规划
高温度（0.6-0.7）：输出更多样、更创造性，适合写作、头脑风暴

状态管理与上下文传递

子 Agent 派生系统通过 DelegationState 对象管理全局状态。

状态演进时间线

python 复制代码

# t0: 初始化
state = DelegationState(
    user_request="写一篇关于 Python 装饰器的技术博客",
    delegation_plan=None,
    sub_agent_results={},
    completed_tasks=[],
    final_report=None
)

# t1: 规划阶段完成
state.delegation_plan = DelegationPlan(
    sub_tasks=[
        SubTask(task_id="task_1", agent_type="research", ...),
        SubTask(task_id="task_2", agent_type="writing", ...),
        SubTask(task_id="task_3", agent_type="qa", ...)
    ],
    execution_order=["task_1", "task_2", "task_3"],
    rationale="先研究收集信息，再基于研究结果撰写内容，最后进行质量审核"
)

# t2: 第一个子任务完成
state.sub_agent_results["task_1"] = SubAgentResult(
    task_id="task_1",
    agent_type="research",
    success=True,
    output="[研究结果：装饰器的原理、用法、最佳实践...]",
    execution_time=25.3
)
state.completed_tasks = ["task_1"]

# t3: 第二个子任务完成
state.sub_agent_results["task_2"] = SubAgentResult(
    task_id="task_2",
    agent_type="writing",
    success=True,
    output="[文章内容：# Python 装饰器完全指南\n\n...]",
    execution_time=18.7
)
state.completed_tasks = ["task_1", "task_2"]

# t4: 第三个子任务完成
state.sub_agent_results["task_3"] = SubAgentResult(
    task_id="task_3",
    agent_type="qa",
    success=True,
    output="[审核结果：发现 2 处问题，已修正...]",
    execution_time=12.5
)
state.completed_tasks = ["task_1", "task_2", "task_3"]

# t5: 聚合阶段完成
state.final_report = """
# Python 装饰器完全指南

[整合了研究、写作、审核的最终高质量内容...]
"""

上下文传递机制

方式 1：通过状态对象传递

python 复制代码

def execute_sub_agents_node(state: DelegationState) -> DelegationState:
    """执行子 Agent 节点"""

    for task_id in state.delegation_plan.execution_order:
        task = find_task_by_id(task_id, state.delegation_plan.sub_tasks)

        # 构建上下文：包含前置任务的结果
        context = {
            "user_request": state.user_request,
            "previous_results": {}
        }

        # 添加依赖任务的结果
        for dep_id in task.dependencies:
            dep_result = state.sub_agent_results.get(dep_id)
            if dep_result and dep_result.success:
                context["previous_results"][dep_id] = dep_result.output

        # 执行任务，传入上下文
        agent = get_agent(task.agent_type)
        result = agent.execute(task, context)

        # 更新状态
        state.sub_agent_results[task_id] = result
        if result.success:
            state.completed_tasks.append(task_id)

    return state

方式 2：在提示词中嵌入上下文

python 复制代码

class WritingAgent:
    def execute(self, task: SubTask, context: Dict) -> SubAgentResult:
        # 提取前置任务的结果
        research_result = context["previous_results"].get("task_research_1", "")

        # 构建提示词，包含上下文
        prompt = f"""
你是一位资深技术作家。

用户需求：
{context["user_request"]}

当前任务：
{task.description}

研究成果（来自 Research Agent）：
{research_result}

请基于以上研究成果，撰写一篇高质量的技术博客文章。

要求：
1. 结构清晰，逻辑流畅
2. 包含代码示例
3. 适合中级开发者阅读
4. 长度 2000-3000 字
"""

        response = self.llm.invoke([HumanMessage(content=prompt)])

        return SubAgentResult(
            task_id=task.task_id,
            agent_type="writing",
            success=True,
            output=response.content.strip()
        )

依赖解析与执行顺序

子 Agent 派生系统使用 拓扑排序 算法自动计算任务的执行顺序。

依赖解析引擎

python 复制代码

from collections import defaultdict, deque
from typing import List, Dict

class DependencyEngine:
    """依赖解析引擎"""

    def resolve_execution_order(
        self,
        tasks: List[SubTask]
    ) -> List[str]:
        """
        基于任务依赖关系计算执行顺序
        使用拓扑排序算法（Kahn's Algorithm）

        算法步骤：
        1. 构建依赖图和入度表
        2. 找到所有入度为 0 的任务（无依赖）
        3. 依次处理这些任务，更新依赖它们的任务的入度
        4. 重复直到所有任务都被处理

        Returns:
            List[str]: 任务 ID 的执行顺序

        Raises:
            ValueError: 如果检测到循环依赖
        """
        # 构建依赖图
        graph = defaultdict(list)  # task_id -> [dependent_task_ids]
        in_degree = defaultdict(int)  # task_id -> 入度（依赖数量）

        # 初始化
        for task in tasks:
            if task.task_id not in in_degree:
                in_degree[task.task_id] = 0

            in_degree[task.task_id] += len(task.dependencies)

            for dep in task.dependencies:
                graph[dep].append(task.task_id)

        # 拓扑排序
        queue = deque([
            task.task_id
            for task in tasks
            if in_degree[task.task_id] == 0
        ])
        execution_order = []

        while queue:
            current = queue.popleft()
            execution_order.append(current)

            # 更新依赖当前任务的所有任务
            for next_task in graph[current]:
                in_degree[next_task] -= 1
                if in_degree[next_task] == 0:
                    queue.append(next_task)

        # 检测循环依赖
        if len(execution_order) != len(tasks):
            raise ValueError("检测到循环依赖，无法执行")

        return execution_order

    def analyze_parallel_groups(
        self,
        tasks: List[SubTask]
    ) -> List[List[str]]:
        """
        分析哪些任务可以并行执行

        算法：
        1. 按执行顺序分组
        2. 同一组内的任务可以并行

        Returns:
            List[List[str]]: 任务组列表，每组内的任务可并行
        """
        execution_order = self.resolve_execution_order(tasks)
        task_map = {t.task_id: t for t in tasks}

        groups = []
        processed = set()

        for task_id in execution_order:
            if task_id in processed:
                continue

            # 找到所有依赖已满足且未处理的任务
            current_group = []
            for tid in execution_order:
                if tid in processed:
                    continue

                task = task_map[tid]
                # 检查依赖是否都已完成
                if all(dep in processed for dep in task.dependencies):
                    current_group.append(tid)

            if current_group:
                groups.append(current_group)
                processed.update(current_group)

        return groups

依赖解析示例

python 复制代码

# 定义任务
tasks = [
    SubTask(
        task_id="task_1",
        description="研究 Python 装饰器的基本概念",
        agent_type="research",
        dependencies=[]  # 无依赖
    ),
    SubTask(
        task_id="task_2",
        description="分析装饰器的高级用法",
        agent_type="analysis",
        dependencies=["task_1"]  # 依赖 task_1
    ),
    SubTask(
        task_id="task_3",
        description="编写装饰器的代码示例",
        agent_type="coding",
        dependencies=["task_1"]  # 依赖 task_1
    ),
    SubTask(
        task_id="task_4",
        description="撰写技术博客",
        agent_type="writing",
        dependencies=["task_2", "task_3"]  # 依赖 task_2 和 task_3
    ),
    SubTask(
        task_id="task_5",
        description="质量审核",
        agent_type="qa",
        dependencies=["task_4"]  # 依赖 task_4
    )
]

# 解析执行顺序
engine = DependencyEngine()
execution_order = engine.resolve(tasks)
# 结果: ["task_1", "task_2", "task_3", "task_4", "task_5"]

# 分析并行组
parallel_groups = engine.analyze_parallel_groups(tasks)
# 结果: [
#     ["task_1"],           # 第一批：无依赖
#     ["task_2", "task_3"], # 第二批：依赖 task_1，可并行
#     ["task_4"],           # 第三批：依赖 task_2 和 task_3
#     ["task_5"]            # 第四批：依赖 task_4
# ]

可视化依赖关系

erlang 复制代码

task_1 (research) ──────┐
   │                     │
   ├─→ task_2 (analysis) ┤
   │                     ├─→ task_4 (writing) ──→ task_5 (qa)
   └─→ task_3 (coding) ──┘

执行策略：
批次 1: task_1              (1 个任务)
批次 2: task_2, task_3      (2 个任务并行)
批次 3: task_4              (1 个任务)
批次 4: task_5              (1 个任务)

总耗时（串行）: T1 + T2 + T3 + T4 + T5
总耗时（并行）: T1 + max(T2, T3) + T4 + T5
加速比: ~1.5x (假设 T2 ≈ T3)

循环依赖检测

python 复制代码

# 错误示例：循环依赖
bad_tasks = [
    SubTask(task_id="A", agent_type="research", dependencies=["B"]),
    SubTask(task_id="B", agent_type="analysis", dependencies=["C"]),
    SubTask(task_id="C", agent_type="writing", dependencies=["A"])  # 循环！
]

try:
    engine.resolve_execution_order(bad_tasks)
except ValueError as e:
    print(f"错误: {e}")
    # 输出: "错误: 检测到循环依赖，无法执行"

第三部分：代码实现 💻

现在让我们动手实现一个完整的子 Agent 派生系统。

环境准备

安装依赖

bash 复制代码

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装核心依赖
pip install langchain-core langchain-openai langchain-ollama
pip install langgraph pydantic python-dotenv

配置环境变量

创建 .env 文件：

bash 复制代码

# 使用 OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4o-mini

# 或使用 Ollama（本地）
# LLM_PROVIDER=ollama
# OLLAMA_MODEL=llama3.1:8b
# OLLAMA_BASE_URL=http://localhost:11434

LLM 初始化工具函数

python 复制代码

# utils/llm_helper.py
import os
from langchain_openai import ChatOpenAI
from langchain_ollama import ChatOllama
from dotenv import load_dotenv

def get_llm(temperature: float = 0.3):
    """
    获取 LLM 实例（支持 OpenAI 和 Ollama）

    Args:
        temperature: 温度参数（0-1）

    Returns:
        LLM 实例
    """
    load_dotenv()
    provider = os.getenv("LLM_PROVIDER", "").lower()

    if provider == "ollama":
        return ChatOllama(
            model=os.getenv("OLLAMA_MODEL", "llama3.1:8b"),
            base_url=os.getenv("OLLAMA_BASE_URL", "http://localhost:11434"),
            temperature=temperature
        )
    else:
        return ChatOpenAI(
            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
            api_key=os.getenv("OPENAI_API_KEY"),
            temperature=temperature
        )

SubAgent 实现

基础 SubAgent 类

python 复制代码

# agents/base_agent.py
from abc import ABC, abstractmethod
from typing import Dict, Optional
from pydantic import BaseModel
from langchain_core.messages import HumanMessage, SystemMessage
import time

class SubAgent(ABC):
    """SubAgent 基类"""

    def __init__(self, agent_type: str, temperature: float, system_prompt: str):
        self.agent_type = agent_type
        self.temperature = temperature
        self.system_prompt = system_prompt
        self.llm = get_llm(temperature)

    def execute(self, task: SubTask, context: Dict) -> SubAgentResult:
        """
        执行任务的标准化方法

        Args:
            task: 子任务对象
            context: 上下文信息（包含前置任务结果）

        Returns:
            SubAgentResult: 执行结果
        """
        start_time = time.time()

        try:
            # 构建提示词
            prompt = self._build_prompt(task, context)

            # 调用 LLM
            messages = [
                SystemMessage(content=self.system_prompt),
                HumanMessage(content=prompt)
            ]
            response = self.llm.invoke(messages)

            # 计算耗时
            execution_time = time.time() - start_time

            return SubAgentResult(
                task_id=task.task_id,
                agent_type=self.agent_type,
                success=True,
                output=response.content.strip(),
                execution_time=execution_time,
                model_used=self.llm.model_name if hasattr(self.llm, 'model_name') else "unknown"
            )

        except Exception as e:
            execution_time = time.time() - start_time
            return SubAgentResult(
                task_id=task.task_id,
                agent_type=self.agent_type,
                success=False,
                output="",
                error_message=str(e),
                execution_time=execution_time
            )

    @abstractmethod
    def _build_prompt(self, task: SubTask, context: Dict) -> str:
        """构建针对性的提示词（子类实现）"""
        pass

6 种具体 Agent 实现

python 复制代码

# agents/research_agent.py
class ResearchAgent(SubAgent):
    """研究型 Agent"""

    def __init__(self):
        super().__init__(
            agent_type="research",
            temperature=0.5,
            system_prompt="""你是一位专业的研究员，擅长信息收集和整理。

你的职责：
1. 深入研究给定主题
2. 收集权威来源的信息
3. 整理关键发现
4. 提供引用来源

输出格式：
## 研究主题
[主题描述]

## 关键发现
1. [发现 1]
   - 来源：[URL/文献]
   - 可信度：[高/中/低]

## 参考资料
- [来源 1]
"""
        )

    def _build_prompt(self, task: SubTask, context: Dict) -> str:
        prompt = f"""
用户需求：{context['user_request']}

当前任务：{task.description}

请进行深入研究，提供详细、可靠的信息。
"""
        return prompt


# agents/analysis_agent.py
class AnalysisAgent(SubAgent):
    """分析型 Agent"""

    def __init__(self):
        super().__init__(
            agent_type="analysis",
            temperature=0.3,
            system_prompt="""你是一位专业的数据分析师，擅长数据处理和洞察提炼。

输出格式：
## 分析目标
[目标描述]

## 关键指标
1. [指标 1]：[值]

## 深度分析
[分析内容]

## 洞察与建议
1. [洞察] → [建议]
"""
        )

    def _build_prompt(self, task: SubTask, context: Dict) -> str:
        # 获取前置任务结果
        previous_results = context.get("previous_results", {})
        context_text = "\n\n".join([
            f"## {task_id} 的结果：\n{result}"
            for task_id, result in previous_results.items()
        ])

        prompt = f"""
用户需求：{context['user_request']}

当前任务：{task.description}

前置信息：
{context_text}

请基于以上信息进行深度分析。
"""
        return prompt


# agents/writing_agent.py
class WritingAgent(SubAgent):
    """写作型 Agent"""

    def __init__(self):
        super().__init__(
            agent_type="writing",
            temperature=0.7,
            system_prompt="""你是一位资深作家，擅长内容创作和表达。

写作原则：
- 清晰：简洁明了，避免冗余
- 连贯：逻辑流畅，过渡自然
- 准确：事实正确，引用可靠
- 吸引：开头引人，结尾有力

输出格式：
# [标题]

## [章节 1]
[内容]

## [章节 2]
[内容]
"""
        )

    def _build_prompt(self, task: SubTask, context: Dict) -> str:
        previous_results = context.get("previous_results", {})
        context_text = "\n\n".join([
            f"## 参考材料 {i+1}：\n{result}"
            for i, (task_id, result) in enumerate(previous_results.items())
        ])

        prompt = f"""
用户需求：{context['user_request']}

当前任务：{task.description}

参考材料：
{context_text}

请基于以上材料，撰写高质量的内容。
"""
        return prompt


# agents/coding_agent.py
class CodingAgent(SubAgent):
    """编码型 Agent"""

    def __init__(self):
        super().__init__(
            agent_type="coding",
            temperature=0.2,
            system_prompt="""你是一位高级软件工程师，擅长编写高质量代码。

编码原则：
- DRY (Don't Repeat Yourself)
- SOLID 原则
- 清晰命名
- 适当注释
- 错误处理

输出格式：
## 功能说明
[功能描述]

## 代码实现
```python
[代码]

使用示例

python 复制代码

[示例]

""" )

python 复制代码

def _build_prompt(self, task: SubTask, context: Dict) -> str:
    previous_results = context.get("previous_results", {})
    context_text = "\n\n".join([
        f"## {task_id} 的输出：\n{result}"
        for task_id, result in previous_results.items()
    ])

    prompt = f"""

用户需求：{context['user_request']}

当前任务：{task.description}

agents/planning_agent.py

class PlanningAgent(SubAgent): """规划型 Agent"""

ini 复制代码

def __init__(self):
    super().__init__(
        agent_type="planning",
        temperature=0.4,
        system_prompt="""你是一位项目规划专家，擅长任务分解和计划制定。

规划原则：

MECE 原则（相互独立，完全穷尽）
由粗到细，逐步细化
明确依赖关系

输出格式：

需求分析

需求概述

任务分解

任务 1
- 目标：[...]
- 依赖：[...]

执行计划

计划详情\] """ ) ```php def _build_prompt(self, task: SubTask, context: Dict) -> str: prompt = f""" ``` 用户需求：{context\['user_request'\]} 当前任务：{task.description} 请制定详细的执行计划。 """ return prompt ## agents/qa_agent.py class QAAgent(SubAgent): """质量审核 Agent""" ```ini def __init__(self): super().__init__( agent_type="qa", temperature=0.3, system_prompt="""你是一位质量审核专家，擅长发现问题和提出改进建议。 ``` 审核维度： * 准确性：事实是否正确 * 完整性：是否遗漏重要内容 * 一致性：风格和术语是否统一 * 可读性：是否清晰易懂 输出格式： ### 审核摘要 * 总体评分：\[X/10

Claude Code 中的子 Agent 派生实现：Task Tool 完全指南