DeepAgents的子智能体

为什么使用子智能体？

核心目的：为什么用子智能体？

简单说，解决「上下文膨胀」问题

1. 当主 AI（主智能体）调用工具（比如联网搜索、读取大文件、查数据库）时，工具会返回海量中间结果，大量日志、步骤、数据会直接占满主智能体的上下文窗口；
2. 子智能体相当于独立干活的 “打工人”：复杂的工具调用、中间步骤全部交给它处理，主智能体只接收最终精简结果，不用管繁琐的几十步工具调用，避免主 AI 被冗余信息干扰、内存过载。

适合用子智能体的 4 种场景

• 多步骤复杂任务：步骤太多，会让主智能体的上下文混乱、逻辑出错，拆分给子智能体分步执行；
• 垂直专业领域：比如代码、医疗、金融，需要专属指令 / 专用工具，单独给子智能体定制；
• 需要不同模型能力：比如一个任务既要写文案、又要分析数据、还要画图，不同子智能体用不同能力的模型；
• 主智能体只做统筹：主智能体负责整体规划、调度，子智能体负责落地干活，主 AI 专注高级决策。

不适合用子智能体的 3 种场景

• 简单单步任务：一句话就能完成，拆分出子智能体纯属多此一举；
• 需要保留中间上下文：必须看到完整执行过程、中间步骤不能省略（比如调试、复盘），子智能体屏蔽了中间过程，就不适用；
• 成本大于收益：搭建、调用子智能体本身有算力、时间成本，简单任务用它得不偿失。

---

简单总结：子智能体就是给主 AI 减负，专门处理脏活累活，适合复杂、多步骤、专业化的任务，简单任务千万别用。

使用SubAgent

示例代码

import os
from typing import Literal
# 导入DeepAgents框架创建智能体核心函数
from deepagents import create_deep_agent

# ---------------------- 1. 定义工具：联网搜索函数 ----------------------
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """
    模拟联网搜索工具
    :param query: 搜索关键词
    :param max_results: 返回结果条数
    :param topic: 搜索领域：通用/新闻/金融
    :param include_raw_content: 是否返回原始网页内容
    :return: 整理后的搜索结果
    """
    # 模拟真实搜索返回结构化内容（实际项目替换为真实联网接口）
    mock_result = f"""
    【{topic}领域搜索结果】
    关键词：{query}
    结果条数：{max_results}
    核心摘要：模拟深度调研后的精简结论，过滤冗余原始网页信息
    """
    return mock_result

# ---------------------- 2. 配置子智能体(SubAgent) ----------------------
research_subagent = {
    "name": "research-agent",
    "description": "专门负责深度网络调研、信息搜集、内容整理的子智能体",
    "system_prompt": "你是一个专业的研究人员，擅长深度信息搜集、联网调研，整理精简有效信息，只输出最终调研结论，不输出中间工具调用过程。",
    "tools": [internet_search],  # 子智能体独享搜索工具，主智能体不直接调用
    "model": "openai:gpt-4o",    # 子智能体独立使用GPT-4o，主智能体用Claude，实现多模型能力拆分
}
# 子智能体列表，可扩展多个子智能体（如代码子智能体、数据分析子智能体）
subagents = [research_subagent]

# ---------------------- 3. 创建主智能体，挂载子智能体 ----------------------
main_agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",  # 主智能体使用Claude，负责顶层决策、任务统筹
    subagents=subagents,                 # 绑定子智能体，自动调度
    system_prompt="你是任务总负责人，负责拆解任务，将调研类工作交给research-agent子智能体，仅接收子智能体的最终结果，整合输出最终答案"
)

# ---------------------- 4. 测试调用：主智能体发起任务 ----------------------
if __name__ == "__main__":
    # 主智能体接收用户问题，自动调用子智能体完成调研
    user_question = "请调研2025年AI智能体技术的最新发展趋势"
    result = main_agent.run(user_question)
    print("===== 最终输出 =====")
    print(result)

调用逻辑：完整任务链路

1. 用户提问 → 主智能体接收；
2. 主智能体识别是深度调研任务，自动下发给 research-agent；
3. 子智能体调用 internet_search 工具，完成多轮搜索、信息整理；
4. 子智能体返回精简最终结论给主智能体；
5. 主智能体整合结果，输出最终答案。

使用CompiledSubAgent

前面讲的普通 SubAgent 是简单配置式子智能体，而 CompiledSubAgent 是编译型 / 自定义可运行子智能体：

你可以用其他框架（比如 LangChain）提前完整开发一个独立智能体（带复杂工作流、工具链、决策逻辑），再把它包装成子智能体，接入主智能体的调度体系。

简单说：独立智能体既能单独运行，也能作为子智能体帮主智能体干活，实现跨框架、复杂能力复用。

示例代码

from deepagents import create_deep_agent, CompiledSubAgent
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain.tools import tool

# 1. 模拟数据分析工具
@tool
def data_analysis_tool(data: str) -> str:
    """模拟数据分析工具，处理复杂数据"""
    return f"【数据分析结果】已完成数据{data}的清洗、统计、可视化分析"

specialized_tools = [data_analysis_tool]
your_model = ChatOpenAI(model="gpt-4o")

# 2. 创建LangChain自定义独立数据分析智能体
custom_graph = create_agent(
    model=your_model,
    tools=specialized_tools,
    prompt="你是一个专业的数据分析师，擅长处理复杂的数据分析任务。"
)

# 3. 包装为CompiledSubAgent
custom_subagent = CompiledSubAgent(
    name="data-analyzer",
    description="用于进行复杂数据分析任务的子智能体",
    runnable=custom_graph
)
subagents = [custom_subagent]

# 4. 定义主智能体的搜索工具
def internet_search(query: str) -> str:
    return f"搜索结果：{query}相关行业数据"

# 5. 创建主智能体，绑定子智能体
main_agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[internet_search],
    system_prompt="你是一个专业的研究人员，擅长深度研究，可调用data-analyzer进行数据分析",
    subagents=subagents
)

# 6. 测试调用
if __name__ == "__main__":
    res = main_agent.run("调研2025年AI行业数据，并做数据分析")
    print(res)

主智能体：用 Claude，负责整体统筹、联网搜索、任务规划

子智能体：独立的数据分析智能体，专门处理复杂数据计算、分析、建模

主智能体遇到数据分析任务，自动调度 data-analyzer 子智能体处理，隔离复杂内部逻辑，避免主智能体上下文膨胀

普通 SubAgent VS CompiledSubAgent（关键区别）

类型	实现方式	能力	适用场景
普通 SubAgent	字典配置（name/prompt/tools）	简单、轻量化，适合单工具、简单任务	搜索、文件读取等简单工具调用
CompiledSubAgent	外部完整智能体包装（LangChain 等）	可包含复杂流程图、多轮决策、复杂工具链	数据分析、代码执行、复杂业务流程等重度任务

核心设计思想总结

1. 解决复杂子智能体开发问题：简单子智能体用配置，复杂智能体用外部框架完整开发，再接入；
2. 跨框架兼容：LangChain、LlamaIndex 等写的 Agent 都能包装成子智能体，接入 DeepAgents；
3. 隔离上下文：复杂数据分析的内部多轮调用全部隔离在子智能体内部，主智能体只接收最终结果；
4. 复用性强：独立智能体可单兵作战单独运行，也可团队协作作为子智能体。

最佳实践

核心原则

主智能体依靠子智能体的 description 决定调用对象，描述越具体，调度越精准；越笼统，越容易调度出错。

类别	示例文本	优点 / 问题分析	通用优化公式
✅ 好的描述（推荐）	分析金融数据并生成带有置信评分的投资洞察	信息完整： 1. 明确领域：金融数据 2. 明确动作：分析 3. 明确输出格式：带置信评分 4. 明确最终产出：投资洞察主智能体可精准匹配任务场景	领域 + 核心动作 + 输出格式 + 最终用途
❌ 差的描述（不推荐）	进行金融数据分析	过于笼统： 1. 无边界，未说明输出形式 2. 主智能体无法区分简单统计 / 深度投资分析 3. 多子智能体场景易职责冲突	缺少输出、用途约束，调度稳定性差

保持系统提示详细

这是子智能体系统提示词（system_prompt）的最佳实践：

必须写得详细、可执行，明确告诉子智能体：怎么用工具、怎么处理信息、输出格式、字数约束，以此保证输出规范、精简，避免上下文膨胀。

示例代码

research_subagent = {
    "name": "research-agent",
    "description": "使用网络搜索进行深入研究并综合研究结果",
    "system_prompt": """你是一位严谨的研究员，职责如下：
1. 将研究问题拆分为可搜索的关键词
2. 使用 internet_search 检索相关信息
3. 将发现综合成简洁而全面的摘要
4. 引用来源时需给出链接

输出格式：
- 摘要（2-3 段）
- 关键发现（bullet 列表）
- 来源（含 URL）

回答请控制在 500 字以内，以保持上下文清爽。""",
    "tools": [internet_search],
}

整体结构

配置项	内容 & 作用
name	research-agent：子智能体名称
description	使用网络搜索进行深入研究并综合研究结果：给主智能体看的调用说明（遵循上一张图 “清晰描述” 的最佳实践）
system_prompt	核心！给子智能体自己看的执行手册，包含：职责步骤、工具用法、输出格式、字数限制
tools	[internet_search]：绑定搜索工具

system_prompt 详细设计拆解（表格）

模块	内容	设计目的（对应前面理论）
角色定位	你是一位严谨的研究员	明确子智能体身份，统一行为风格
执行步骤（工具使用规范）	1. 拆分搜索关键词2. 调用internet_search检索3. 综合信息生成摘要4. 引用来源 + 链接	强制子智能体规范调用工具，避免无效搜索、冗余调用，减少上下文垃圾信息
输出格式约束	- 2–3 段摘要- 要点列表- 来源 URL	统一输出结构，只返回最终整理结果，屏蔽中间搜索过程，防止主智能体上下文膨胀
字数约束	控制在 500 字以内	严格精简输出，进一步降低 token 消耗，保持上下文清爽

好坏对比（结合前面所有最佳实践

写法	示例	问题 / 优势
❌ 差写法（简略）	system_prompt: "你是研究员，帮我搜索信息"	无步骤、无格式、无字数限制输出杂乱、冗长，撑爆上下文
✅ 优写法（本图规范）	明确步骤、工具用法、输出格式、字数约束	输出结构化、精简、规范，完美解决上下文膨胀问题

核心总结（串联所有最佳实践）

1. description：写给主智能体，清晰具体，让主智能体知道什么时候调用；
2. system_prompt：写给子智能体，详细规范，约束工具调用、输出格式、字数；
3. 最终目的：子智能体只输出精简最终结果，隔离所有中间冗余信息，彻底解决上下文膨胀。

最小工具集

核心规则：只给子智能体提供必需工具，提升专注度与安全性

正确写法

# ✅ 好：专注的工具集
email_agent = {
  "name": "email-sender",
  "tools": [send_email, validate_email],  # 仅与电子邮件相关
}

错误写法

# ❌ 不好：工具过多
email_agent = {
  "name": "email-sender",
  "tools": [send_email, web_search, database_query, file_upload],  # 不够专注
}

对比说明

类型	核心说明
正确	工具仅保留邮件发送、邮箱校验，职责专一，无越权风险
错误	混入搜索、数据库、文件上传工具，冗余且存在安全隐患

根据任务选择模型

subagents = [
{"name": "contract-reviewer",
  "description": "审查法律文件和合同",
  "system_prompt": "你是一位专业的法律审查员...",
  "tools": [read_document, analyze_contract],
  "model": "claude-sonnet-4-5-20250929",  # 大上下文窗口适合处理长文档
},
{"name": "financial-analyst",
  "description": "分析金融数据和市场趋势",
  "system_prompt": "你是一位专业的金融分析师...",
  "tools": [get_stock_price, analyze_fundamentals],
  "model": "openai:gpt-5",  # 更适合数值分析
},
]

1. 核心原则

   为不同子智能体匹配擅长对应任务的大模型，发挥各模型专属优势，这是子智能体的最佳实践之一。

2. 两个子智能体拆解

   1. 合同审查子智能体（contract‑reviewer）

      • 任务：审查长文本法律合同、文档

      • 选用模型：claude‑sonnet‑4‑5‑20250929

      • 原因：Claude 拥有超大上下文窗口，擅长读取、理解超长文档、法律条文

   2. 金融分析子智能体（financial‑analyst）

      • 任务：股票价格、基本面、数值类金融数据分析
      • 选用模型：openai:gpt‑5
      • 原因：GPT 系列数值计算、逻辑分析能力更强，适合金融量化、数据研判

3. 结合前面所有最佳实践验证

   1. description：描述精准，主智能体可精准调度
   2. 最小工具集：每个子智能体仅挂载对应领域工具，无冗余
   3. 模型按需分配：不强制统一模型，专业任务匹配专业模型
   4. system_prompt：配置专属角色提示词，规范行为

4. 核心收益

   • 性能更强：每个垂直任务使用最优模型，结果更精准

   • 成本可控：不用统一使用最强最贵的模型，按需分配节省算力

   • 分工清晰：子智能体能力边界明确，避免任务混乱

返回简洁的结果

data_analyst = {
  "system_prompt": """分析数据并返回：
1. 关键洞察（3-5个要点）
2. 整体置信度评分
3. 建议的后续行动

不要包含：
- 原始数据
- 中间计算过程
- 详细的工具输出

保持回复在300字以内。"""
}

1. 最佳实践核心

   强制子智能体只返回精简摘要 / 结论，屏蔽原始数据、中间过程，从根源解决主智能体上下文膨胀问题。

2. system_prompt 设计拆解

   要求返回内容（正向约束）

   1. 关键洞察：提炼 3-5 个核心结论
   2. 置信度评分：给出结果可靠性
   3. 后续行动：给出可执行建议 → 只输出最终可用成果

   禁止返回内容（反向约束）

   • 原始数据

   • 中间计算过程

   • 工具调用详细输出 → 完全隔离冗余中间信息，不让主智能体接收无效内容

   字数约束

   • 300字以内，严格控制输出长度，进一步降低 Token 消耗。

3. 与整套体系的关联，和前面所有实践形成闭环：

   1. 清晰描述：主智能体精准调度
   2. 最小工具集：子智能体专注本职
   3. 匹配专属模型：垂直任务最优性能

4. 精简结果输出：隔离冗余，保护主智能体上下文

常见模式

多个专门子能体

为不同领域创建专门的子能体

from deepagents import create_deep_agent

subagents = [
{
    "name": "data-collector",
    "description": "从各种来源收集原始数据",
    "system_prompt": "收集关于该主题的全面数据",
    "tools": [web_search, api_call, database_query],
},
{
    "name": "data-analyzer",
    "description": "分析收集的数据以获取洞察",
    "system_prompt": "分析数据并提取关键洞察",
    "tools": [statistical_analysis],
},
{
    "name": "report-writer",
    "description": "根据分析撰写精美的报告",
    "system_prompt": "根据洞察创建专业报告",
    "tools": [format_document],
},
]

tagent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    system_prompt="你协调数据分析和报告。使用子智能体执行专业任务。",
    subagents=subagents
)

模式名称：多个专门子智能体（流水线分工模式）

将一个完整任务拆分为串行的专业步骤，每个步骤由独立垂直子智能体负责，类似流水线作业。

3 个子智能体分工（严格遵循前面所有最佳实践）

子智能体	职责	工具特点
data‑collector 数据收集器	全网搜索、接口、数据库拉取原始数据	工具多，负责信息采集
data‑analyzer 数据分析器	对数据做统计、提取核心洞察	仅统计分析工具，专注计算
report‑writer 报告撰写器	基于洞察生成格式化专业报告	仅文档格式化工具，专注输出

• 每个子智能体都使用了最小化工具集，职责完全隔离
• 每个description描述清晰，主智能体可精准调度

标准工作流程

1. 主智能体创建整体计划
2. 委托数据收集器采集原始数据
3. 交给数据分析器提炼洞察
4. 交给报告撰写器生成最终报告
5. 主智能体整合输出最终结果

核心优势

1. 上下文隔离：每个子智能体只处理自己环节的信息，互不干扰，主智能体只接收最终报告，彻底避免上下文膨胀
2. 高度专业化：每个智能体只干一件事，精准度更高
3. 可复用：数据收集、分析、撰写模块可在其他项目直接复用
4. 易维护：某一环节出错，只需要修改对应子智能体，不影响整体流程

故障排除

子智能体未被调用

现象：主智能体不调用子智能体，自己硬扛复杂任务，会造成上下文膨胀、结果质量差。

1. 两套解决方案

   • 方案 1：把子智能体的 description 写得更具体

     • 好示例：明确能力范围、使用时机，主智能体一看就知道什么时候该交给它

     • 差示例：描述太笼统模糊，主智能体识别不出什么时候调用

     # ✅ 好的描述
     {"name": "research-specialist", "description": "使用网络搜索对特定主题进行深入研究。当您需要需要多次搜索的详细信息时使用。"}
     
     # ❌ 不好的描述
     {"name": "helper", "description": "帮助处理事务"}

• 方案 2：在主智能体的 system_prompt 强制要求委托

  • 直接命令主智能体：复杂任务必须用工具把任务交给子智能体，以此强制分工，避免主智能体大包大揽。

  # 主智能体强制委托配置
  agent = create_deep_agent(
      system_prompt="""...你的指令...
  重要提示：对于复杂任务，请使用task()工具将任务委托给你的子智能体。
  这可以保持你的上下文清晰并提高结果质量。""",
      subagents=[...]
  )

1. 核心原理

​ 主智能体是靠子智能体的描述判断要不要调用；描述越精准、约束越强，调用越稳定。

​ 同时可以在顶层直接下达强制指令，兜底避免不调用的问题。

上下文仍然膨胀

即使已经使用了子智能体，但返回的内容还是太长、冗余信息过多，依旧撑爆主智能体上下文窗口。

1. 两套解决方案

   • 方案 1：强制子智能体精简输出

     • 约束：只给摘要，禁止原始数据、中间搜索过程、工具详情

     • 硬性字数限制：500 字以内

     • 目的：直接压缩子智能体返回给主智能体的内容体量

     # 方案1：指示子智能体返回简洁结果
     system_prompt="""
     重要提示：只返回必要的摘要。
     不要包含原始数据、中间搜索结果或详细的工具输出。
     你的回复应控制在500字以内。"""

• 方案 2：海量数据落地到文件

  针对超大批量数据：

  1. 子智能体把原始海量数据直接写入本地文件，不往对话上下文里塞
  2. 只把精简后的分析摘要返回给主智能体
  3. 原始数据通过文件持久化存储，完全不占用上下文 token

  # 方案2：使用文件系统存储大数据
  system_prompt="""当你收集大量数据时：
  1. 将原始数据保存到/data/raw_results.txt
  2. 处理和分析数据
  3. 只返回分析摘要
  
  这可以保持上下文清晰。"""

1. 核心逻辑

   • 子智能体解决的是工具调用步骤隔离
   • 这一步解决的是子智能体输出内容本身的冗余
   • 超大数据直接落文件，是终极兜底方案，彻底避免上下文被海量原始数据填

选择了错误的子智能体

主智能体在处理任务时，调用了不匹配、不合适的子智能体，比如简单事实查询调用深度调研子智能体，或复杂报告调用快速搜索子智能体，导致效率低、结果错误。

subagents = [
{
    "name": "quick-researcher",
    "description": "用于需要1-2次搜索的简单、快速研究问题。当你需要基本事实或定义时使用。",
},
{
    "name": "deep-researcher",
    "description": "用于需要多次搜索、综合和分析的复杂、深入研究。用于编写综合报告。",
}
]

1. 核心解决方案

   在子智能体的 description 描述里，明确区分各自适用场景、使用边界，让主智能体能精准判断该调用哪一个。

2. 两个子智能体边界清晰划分

   | 子智能体名称 | 适用场景 | 调用时机 |
   | :————————————— | :——————- | :—————————————————— |
   | quick‑researcher 快速研究员 | 简单、单次查询 | 查基础事实、名词定义，仅需 1-2 次搜索 |
   | deep‑researcher 深度研究员 | 复杂、深度任务 | 多次搜索、综合分析、撰写完整报告 |

3. 设计核心逻辑

   • 给每个子智能体写排他性、差异化描述，明确什么场景用谁、什么场景不用谁

   • 主智能体通过描述的差异，自动区分调用对象，避免匹配错误

   • 本质还是贯彻前面的最佳实践：描述越具体，调度越精准

总结

子智能体核心优势

1. 保持主智能体上下文清晰

   隔离工具调用、中间过程、原始数据，解决上下文膨胀、Token 过载问题。

2. 实现任务专业化

   按领域拆分垂直子智能体（调研、分析、报告、法律、金融等），分工明确、执行精准。

3. 优化模型使用

   不同子智能体匹配适配任务的专属模型，长文档用 Claude、数值分析用 GPT，算力成本最优。

4. 提高系统可维护性

   模块独立，修改、调试、复用更简单，适合流水线式复杂任务。

核心开发关键建议

1. 为复杂任务使用子智能体

   简单单步任务不用；多步骤、多工具、长流程任务，必须拆分。

2. 保持子智能体专注

   遵循最小工具集原则，只给完成本职必需的工具，避免越权、混乱。

3. 编写清晰的描述和提示

   • description：精准、具体，明确适用场景，让主智能体正确调度；

   • system_prompt：详细约束步骤、工具用法、输出格式。

4. 优化返回结果简洁性

   强制子智能体只输出摘要 / 结论，屏蔽原始数据、中间计算；超大原始数据落地到文件存储。

最终价值

合理使用子智能体，可搭建高效、可扩展、易维护的多智能体系统，全程保障上下文干净、逻辑可控。