01 DeepAgents 框架速览

学习理念：DeepAgents 是尚硅谷自研的多 Agent 编排框架，位于 LangGraph 之上的更高层次抽象。它提供了 SubAgent、HITL、Backend、Permissions、Skills 等开箱即用的能力。虽然这不是行业标准框架，但它解决的是真实的多 Agent 工程问题——子智能体嵌套、人工审批流程、多后端切换、权限控制、技能注册。理解这些概念，任何多 Agent 框架都能快速上手。

海外对标：OpenAI Swarm（Agent 嵌套）、LangGraph（子图）、CrewAI（多 Agent 协作）

---

📖 阅读优先级

等级	章节	说明
🟡 理解即可	核心概念	SubAgent/HITL/Skill 思想通用，框架本身非行业标准
🔴 值得了解	HITL 人机交互	实际 Agent 项目中经常需要"人工审批"环节
🟢 了解即可	day02 深度搜索项目	完整的 DeepAgents 项目示例

---

一、DeepAgents 是什么

DeepAgents 是尚硅谷自研的多智能体编排框架。它在 LangGraph 的基础上，提供了更高层次的抽象：

能力	说明
SubAgent	子智能体集成——Agent 里嵌套 Agent
HITL（Human-in-the-Loop）	人机交互——执行到关键步骤暂停等人工确认
Backend	多后端支持（OpenAI、Qwen 等）
Permissions	权限控制——限制 Agent 的操作范围
Skills	技能注册——可复用的能力模块

---

二、核心概念

2.1 SubAgent——Agent 里嵌套 Agent

🟡【理解即可】 一个复杂的 Agent 可以拆成多个子 Agent，每个子 Agent 负责一个特定能力。

主 Agent（编排者）
    ├── SubAgent A: 联网搜索
    ├── SubAgent B: 数据库查询
    └── SubAgent C: 报告生成

# SubAgent 示例（伪代码）
from deep_agents import SubAgent, Agent

# 定义子智能体
search_agent = SubAgent(
    name="search_agent",
    system_prompt="你是一个搜索助手，负责联网查找信息",
    tools=[web_search_tool]
)

db_agent = SubAgent(
    name="db_agent",
    system_prompt="你是一个数据查询助手，负责查数据库",
    tools=[db_query_tool]
)

# 主智能体编排子智能体
main_agent = Agent(
    name="main_agent",
    system_prompt="你是主调度员，根据用户问题分发给对应的子智能体",
    sub_agents=[search_agent, db_agent]
)

2.2 HITL——人机交互

🔴【值得了解】 HITL 让 Agent 在执行到关键步骤时暂停，等待人工确认后再继续。这在需要"人工审批"的业务场景中非常有用。

# HITL 示例（伪代码）
from deep_agents import Agent, HITLConfig

agent = Agent(
    name="refund_agent",
    hitl_config=HITLConfig(
        require_approval=True,  # 需要人工审批
        pause_on_actions=["execute_refund"],  # 执行退款前暂停
        timeout_minutes=30  # 等待超时
    )
)

# 执行流程：
# 1. Agent 收集退款信息
# 2. 到 execute_refund 步骤 → 暂停 → 等待人工确认
# 3. 人工确认后 → 继续执行
# 4. 人工拒绝 → 取消操作

HITL 的模式有三种：

模式	说明
等待确认	暂停执行，等人工点"确认/拒绝"
编辑修改	人工可以修改 Agent 生成的中间结果再继续
流式干预	在流式输出过程中随时中断或修正

2.3 Backend——多后端支持

🟢【了解即可】 DeepAgents 支持切换不同的 LLM 后端，方便在不同模型间切换。

from deep_agents import Backend

# OpenAI 后端
backend = Backend.openai(api_key="...", model="gpt-4o")

# Qwen 后端
backend = Backend.qwen(api_key="...", model="qwen-max")

2.4 Permissions——权限控制

🟢【了解即可】 限制 Agent 能做什么、不能做什么。

from deep_agents import Agent, Permission

agent = Agent(
    name="safe_agent",
    permissions=[
        Permission.allow("read"),      # 允许读
        Permission.deny("write_db"),   # 禁止写数据库
        Permission.allow_with_approval("send_email")  # 发邮件需审批
    ]
)

2.5 Skills——技能注册

🟡【理解即可】 和之前 Ch24 VibeCoding 的 Skill 概念一致——把常用的能力封装成可复用的 Skill。

from deep_agents import Skill
from deep_agents.skills import CodeReviewSkill, PRDSkill

# 注册技能
agent.register_skill(CodeReviewSkill())
agent.register_skill(PRDSkill())

# 使用
agent.run("帮我 Review 一下这个 PR 的代码")

---

三、day02：深度搜索项目实战

🟢【了解即可】 day02 是一个完整的项目实战，用 DeepAgents 框架构建了一个深度搜索系统。

3.1 项目结构

deep_agent_project_1020/
├── agent/                 Agent 定义
│   └── subagents/         子智能体（联网搜索、数据库查询）
├── api/                   FastAPI 接口
├── ragflow/               RAGFlow 集成
├── tools/                 工具定义（7 个）
├── utils/                 工具函数
└── prompt/                Prompt 模板

3.2 架构

用户请求 → API → 主 Agent
    │
    ├── SubAgent: 联网搜索（调用搜索 API）
    ├── SubAgent: 数据库查询（查询业务 DB）
    ├── RAGFlow 集成（文档检索）
    └── 汇总 → 返回结果

---

四、对 Agent 开发的价值

能力	实际意义	是否值得深入
SubAgent	多 Agent 嵌套的设计思路通用	🟡 理解即可
HITL	实际项目中"人工审批"需求常见	🔴 值得了解
Backend	切换模型是日常操作	🟢 简单
Permissions	安全控制需要考虑	🟢 了解即可
Skills	和 skills/ 目录一致	🟡 已熟悉
DeepAgents 框架	自研框架，非行业标准	🟢 了解即可

---

五、本阶段文件索引

优先级	文件	路径
🟡 P1	01~14_deep_agents_*.py	day01_deepagents串讲/代码/base/
🟢 P2	deep_agent_project_1020/	day02_deepagents应用深度搜索串讲/代码/