系列导读 | 《Deep Agents 实战笔记》 基于 deepagents (Python) 官方文档，参考版本 v0.7+ 原文：https://docs.langchain.com/oss/python/deepagents/overview

面向"做过 LLM 应用、用过 LangChain，想系统掌握 Deep Agents"的开发者的 13 篇实战笔记——从跑通第一个深度研究 Agent，到把 Deep Agent 稳稳推上生产。

如果你已经能熟练调用模型 API、接过工具调用，甚至手写过 ReAct 循环，却在实际项目里反复遇到"上下文装不下、任务一多就失控、Agent 跑完就忘"这些问题，这个系列就是为你写的。

目标读者与前置知识

  • 你：写过 LLM 应用（调过 API、接过工具调用），最好用过 LangChain 或手写过 ReAct 循环；
  • 前置知识：Python 基础、大模型 API 的基本概念（上下文窗口、function calling）。不要求懂 LangGraph，系列中用到时会随文讲解；
  • 你将得到：一套可运行、可上线的 Deep Agents (Python) 完整知识体系，每篇附官方文档链接与可运行代码。

目录（13 篇）

主线脉络：认知（1-2）→ 核心机制（3-7）→ 安全与体验（8-10）→ 实战（11-12）→ 生产（13）

编号标题一句话简介核心机制难度
01为什么 Agent 需要文件系统和子代理上下文窗口不够用、任务一多就失控——两个"老派"设计解决 Agent 两大顽疾Agent Harness 总览★☆☆☆☆
02十分钟跑通你的第一个深度研究 Agent一个搜索工具 + 一行 create_deep_agent，得到会自己拆任务、写报告的研究助手create_deep_agent、工具封装★★☆☆☆
03架构深拆：Deep Agents 的五大内置能力规划、文件系统、子代理、记忆、技能——读懂这五张牌才算入门todo 规划、总结压缩、工具裁剪★★★☆☆
04Backend：把文件系统做成「外接大脑」同一个 Agent API，内存态、真实磁盘、云端存储随意切换，还能按路径路由StateBackend、StoreBackend、CompositeBackend★★★★☆
05子代理（上）：上下文隔离与任务委派主代理不亲自动手，"外包"给各有专长的子代理——控制上下文膨胀的关键武器task 工具、独立上下文、description 设计★★★★☆
06子代理（下）：异步与动态编排从"派一个等一个"到"派出去就不管"，再到"用代码批量编排"的三段进化异步子代理、解释器派发、fanout 模式★★★★☆
07上下文工程：长任务不崩的秘密Agent 跑一小时就"失忆"？系统提示、运行时 context、总结压缩、大结果落盘四板斧上下文四层来源、offload、自动总结★★★★☆
08记忆与技能：让 Agent 越用越聪明记忆让 Agent 记住"你是谁"，技能让它学会"怎么做"——两者都是 Markdown 文件长期记忆、SKILL.md 渐进式披露★★★☆☆
09沙箱与解释器：让 Agent 放心跑代码让 Agent 放心跑代码的三种姿势：本地 shell、远程沙箱、轻量解释器沙箱生命周期、PTC 解释器、选型对比★★★☆☆
10安全围栏：声明式权限与人机协同（HITL）声明式权限规则 + 敏感操作人工审批，让 Agent 在生产环境"权限最小化"文件权限规则、interrupt 审批★★★☆☆
11实战一：复刻 Deep Research 深度研究代理官方教程完整走一遍：多子代理分工 + 联网搜索 + 结构化报告多子代理协作、流式运行★★★★☆
12实战二：Agentic RAG——当检索遇上深度智能体传统 RAG 检索一次答一次，Deep Agents 让它检索、批判、再检索，直到达标分块 offload、rubric 评分迭代★★★★☆
13走向生产：容错、部署与可观测性从 demo 到生产要补的课：限流重试、模型回退、持久化部署、LangSmith 可观测容错中间件、部署形态、记忆作用域★★★★☆

系列知识路线图

flowchart TB
    subgraph S1["认知"]
        A1["01 为什么需要文件系统和子代理"]
        A2["02 跑通第一个研究 Agent"]
    end
    subgraph S2["核心机制"]
        A3["03 五大内置能力"]
        A4["04 Backend 外接大脑"]
        A5["05 子代理上：委派"]
        A6["06 子代理下：异步编排"]
        A7["07 上下文工程"]
    end
    subgraph S3["安全与体验"]
        A8["08 记忆与技能"]
        A9["09 沙箱与解释器"]
        A10["10 权限与 HITL"]
    end
    subgraph S4["实战"]
        A11["11 复刻 Deep Research"]
        A12["12 Agentic RAG"]
    end
    subgraph S5["生产"]
        A13["13 容错部署与可观测性"]
    end
    A1 --> A2 --> A3
    A3 --> A4 --> A5 --> A6 --> A7
    A7 --> A8 --> A9 --> A10
    A10 --> A11 --> A12 --> A13
    style S1 fill:#f4effb,color:#4a2170,stroke:#8b52c9
    style S2 fill:#eef4ff,color:#1a3a8b,stroke:#4a72d9
    style S3 fill:#fbf3e6,color:#6b4a12,stroke:#c99a3d
    style S4 fill:#f0f7f0,color:#1d4a1d,stroke:#4a9e4a
    style S5 fill:#fdeef0,color:#701d2a,stroke:#c94a5e

正在渲染图表…

阅读路线建议

主线（推荐顺序）：01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11 → 12 → 13。五级台阶逐级而上，适合想完整掌握的读者。

按需支线：

  • 只想快速上手：01 → 02 → 11，拿到能跑的研究 Agent 再说；
  • 做多代理协作应用：02 → 05 → 06 → 11，委派与编排是主菜；
  • 长任务总是崩：03 → 07 → 04，上下文管理三板斧；
  • 准备上线：08 → 10 → 13，记忆作用域、权限护栏、容错部署一个不能少；
  • 做 RAG 产品：04 → 07 → 12，文件系统 + 上下文工程 + Agentic RAG。

如果只读三篇：02（跑通上手）、07（上下文工程，最独门的机制）、13（生产收官）。

版本说明

Deep Agents 迭代较快，各篇开头都会注明所依据的版本与官方文档链接（例如第 8 篇涉及的 rt.server_info 模式需要 deepagents>=0.5.0）。内容可能随版本演进过期，请以官方文档为准。

全系列的示例代码可以参考官方仓库 deepagents/examples，每篇的实战作业（如"实现最小自定义 Backend""写一个团队写作规范技能"）都可以作为练习项目。

下一篇：从"为什么 Agent 需要文件系统和子代理"开始。