deepagents：LangChain 官方 Agent harness，两个官方案例拆给你看
deepagents：LangChain 官方 Agent harness，两个官方案例拆给你看
示例代码是最好的文档，这两个例子值得逐行读。
结论：如果你要用 Python 搭一个多步骤、长周期的 Agent，又不想从 LangGraph 原语开始手搓文件系统、上下文压缩、子 Agent 调度，deepagents 是目前最省事的起点。它是 LangChain 官方的开源 harness（langchain-ai/deepagents，Python，MIT，2025 年 7 月建仓，现在 30.7k stars），README 里一句话定位：「The batteries-included agent harness」，并直言灵感来自 Claude Code。
上一篇我们聊了 LangChain 的公司级 harness 五组件，那是架构视角；这篇往下沉一层，看官方开源出来的底座到底怎么用，重点拆仓库里两个最有代表性的示例：deep_research 和 llm-wiki。前者教你怎么编排子 Agent 做并行调研，后者教你怎么让 Agent 把知识沉淀成一个会自我维护的 wiki。
本文提纲
- 十分钟上手：三行代码得到一个能规划、能读写文件的 Agent
- deepagents 在 LangChain 技术栈里的位置
- 案例一：deep_research，一个主 Agent 调度多个研究员
- deep_research 的三个设计细节
- 案例二：llm-wiki，让 Agent 维护一个持久知识库
- llm-wiki 的工程化手法：append-only 日志与 review/apply 两阶段
- 内置高级能力逐个点评
- 边界与代价
- 谁该用，从哪个示例抄起
十分钟上手
环境用 uv，一行依赖：
uv add deepagents最小可用的 Agent：
from deepagents import create_deep_agent
agent = create_deep_agent(
model="openai:gpt-6-astra",
system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})就这些。这个 Agent 开箱即带规划（TODO 列表）、文件读写编辑、上下文自管理能力，模型可以换成任何支持 tool calling 的：Anthropic、Google、OpenRouter 上的开源权重模型，或者 Ollama、vLLM、llama.cpp 本地模型。deep_research 示例默认用 claude-sonnet-4-5-20250929，换 Gemini 只要传入一个 LangChain model 对象：
from langchain.chat_models import init_chat_model
model = init_chat_model(model="anthropic:claude-sonnet-4-5-20250929", temperature=0.0)
agent = create_deep_agent(model=model)想带界面跑也很快。deep_research 示例目录下 uv sync 装好依赖，配好 ANTHROPIC_API_KEY、TAVILY_API_KEY，然后 langgraph dev，浏览器会打开 LangGraph Studio，可以直接提交调研问题、查看中间状态和文件；或者另 clone 官方的 deep-agents-ui（TypeScript，1.7k stars），它是专门为 deepagents 设计的聊天界面，能把 state 里的文件可视化出来。
deepagents 在 LangChain 技术栈里的位置
理解这个项目，先看清三层栈，这也是官方 FAQ 自己给的划分：
graph TB
A["Your product: research agent, coding agent, wiki bot"] --> B["deepagents: opinionated harness with filesystem, sub-agents, context management, skills"]
B --> C["LangChain create_agent: minimal harness, tool loop only"]
C --> D["LangGraph: graph runtime with streaming, persistence, checkpoints"]
D --> E["Any tool-calling LLM: frontier, open-weight, local"]
style B fill:#FF6B6B,color:#000000
style C fill:#4ECDC4,color:#000000
style D fill:#45B7D1,color:#000000
style E fill:#96CEB4,color:#000000
style A fill:#FFEAA7,color:#000000
linkStyle default stroke:#764ba2- LangGraph 是图运行时，负责流式、持久化、checkpoint，但不管你 Agent 长什么样
- LangChain 的
create_agent是跑在它上面的最小 harness，只有一个工具调用循环 - deepagents 再往上，是一个有强烈主见的 harness：子 Agent、可插拔文件系统、上下文压缩、shell、持久记忆、人审、skills 全部打包，任何一块都能覆盖或替换，不用 fork
关键点是三层可组合：任何 LangGraph 的 CompiledStateGraph 都能作为子 Agent 塞进 deepagents，所以你觉得默认循环不合适的那部分，可以自己画图替换，其他部分继续用默认。
案例一：deep_research，一个主 Agent 调度多个研究员
这个示例的目标是做出一个能跑深度调研的 Agent，产出不是一段聊天回复，而是带文件产出的研究报告。整个组装代码在 examples/deep_research/agent.py，核心就一次函数调用：
agent = create_deep_agent(
model=model,
tools=[tavily_search, think_tool],
system_prompt=INSTRUCTIONS,
subagents=[research_sub_agent],
)主 Agent 自己不直接上网搜索，它干的是规划和派活：接到问题后建 TODO，把调研任务拆成多块交给 research 子 Agent，子 Agent 带着隔离的上下文窗口去搜索，回来后由主 Agent 综合。指令里定义了一个 5 步工作流：保存请求 → 用 TODO 规划 → 委派子 Agent → 综合 → 回复。
为什么必须用子 Agent 而不是一个 Agent 自己搜到底？上下文窗口是硬约束。深度调研一个问题可能要读几十个网页，全塞一个对话里，后面的指令和早期的发现都会被淹没。子 Agent 每次搜索在自己的隔离上下文里完成，只把结论带回主上下文，主 Agent 看到的始终是压缩过的情报。这和公司里「主管带几个研究员」的分工是同一个道理。
示例对委派策略写得很具体，不是放任模型自己决定派多少：
- 简单问题派 1 个子 Agent
- 对比类问题，每个对比对象派 1 个
- 多面性调研，每个方面派 1 个
- 并发上限 3 个，迭代轮次上限 3 轮
研究员子 Agent 这边也有硬约束：简单问题搜 2-3 次，复杂问题最多 5 次，每次搜索后必须调用 think_tool 停下来反思进展、找信息缺口，达到停止条件就收工。这些数字看起来朴素，但它们是成本阀门：没有这些限制，一个模糊问题能让 Agent 自信地搜上几十轮，账单和延迟一起爆炸。
deep_research 的三个设计细节
第一，Tavily 只被当成 URL 发现引擎，不当摘要机。tavily_search 工具拿到候选 URL 后，用 httpx 带浏览器 User-Agent 自己去抓全文（避免 403），HTML 转 markdown 后原文返回，明确不做摘要。理由很扎实：搜索 API 的摘要会提前损失信息，而判断哪些信息有用是模型的活，工具不该替它做。这个选择的代价是 token 消耗大，但深度调研场景里信息完整性比省 token 重要。
第二，think_tool 是个不做任何外部操作的工具，它的全部作用是强制模型在两次搜索之间输出一段战略反思。这是用工具调用机制制造思考检查点：相比在 prompt 里写「请认真思考」，把反思做成 tool call 能让模型在结构化的步骤里真正停下来评估，执行率高得多。
第三，自定义指令是补充而非重复默认 middleware 指令。示例的 prompts.py 里有三套指令：5 步工作流、委派策略、研究员行为规范，每条都只定义 deepagents 默认提示里没有的研究专属规则。自己改 prompt 时最容易犯的错就是把默认指令抄一遍再改，结果版本一升级你的提示就和内置行为打架。
跑这个示例需要四个 key：Anthropic（或换 Gemini）、Google、Tavily（搜索，免费额度慷慨）、LangSmith（追踪，注册免费）。
案例二：llm-wiki，让 Agent 维护一个持久知识库
如果说 deep_research 是「一次性深度任务」的范式，llm-wiki 示范的是另一个越来越重要的方向：让 Agent 长期维护一份不断演化的知识资产。它是一个脚本优先（script-first）的示例，Agent 围绕一个 wiki 仓库做三种操作：ingest（吃进原料）、query（基于 wiki 回答）、lint（健康检查与修复），每次运行把变更同步到 LangSmith Context Hub，团队成员可以审阅、评论、晋升版本。
init 之后的工作区布局是整个设计的精华：
AGENTS.md：wiki 的 schema 和 ingest/query/lint 工作流规则，Agent 按它行事；重复运行 init 时保留你改过的版本raw/：不可变的原料区，文章、笔记、数据集扔进去wiki/：Agent 维护的正式知识页（实体、概念、摘要、综合页）wiki/index.md：按内容分类的目录，每页一行摘要，query 时第一个读它log.md：只追加的时间线日志
三种运行模式各有讲究。ingest 默认批量直接写入，加 --review 后变成人在环路的两阶段：review 阶段只读，输出要点、拟修改页、发现的矛盾和索引变更，你确认后 apply 阶段才真正动 wiki；你拒绝修改时，仍然记一条 outcome=canceled 并推送，时间线保持完整。query 自动分两段：先读 index 和最近日志、必要时参考历史 query 页做路由，展开正式页面后带引用回答；如果答案有长期价值，自动归档成 wiki/query/<slug>.md，下次类似问题直接复用。lint 是单次通过的维护动作：调和矛盾、标记过时内容、清理孤儿页、补交叉引用、刷新索引，最后返回剩余缺口和建议补充的问题。
llm-wiki 的工程化手法：append-only 日志与 review/apply 两阶段
这个示例最值得自研团队抄的，是它对「Agent 长期写文件」这件事的工程化约束，有三个手法。
一是 log.md 只追加、且人类不能信任模型来写。日志由 runner 程序追加，Agent 被明确禁止直接编辑它。每条记录有可被 shell 解析的固定表头：
# 查看最近 5 条时间线
grep "^## \[" log.md | tail -5
# 查看所有 query 的归档决策
grep "^## \[.*\] query.review |" log.md | tail -10一个长期自动演化的知识库，如果没有可审计的时间线，出了问题无法定位是哪次 ingest 引入了错误知识。append-only 加结构化表头，让「Agent 干过什么」可以用 grep 回答。
二是把读和写切成独立阶段。review/query 分析阶段只读，apply/filing 阶段才写，而且写入要过确认或满足「答案有长期价值」的条件。这比让 Agent 边读边写安全得多，也便宜得多：只读阶段可以用便宜模型跑。
三是 wiki 的页面结构本身是为检索设计的，不是为向量库设计的。query 的入口是人类和模型都能读的 index.md 目录页，query 历史页被明确定义为「路由提示而非一手证据」，正式知识页才是证据源。这套结构让知识沉淀在普通 Markdown 文件里，不绑定任何 embedding 服务，换模型、换框架都带得走。
运行门槛比 deep_research 高一点：Python 3.11+、带 sandbox 扩展的 langsmith、LANGSMITH_API_KEY，三个写操作模式都在 LangSmith Sandbox 里执行。
内置高级能力逐个点评
deepagents 打包的八块能力，按实际使用价值点评：
- 子 Agent（sub-agents）：核心卖点，deep_research 已经证明价值。隔离上下文是长任务能跑完的前提，注意自己设并发和轮次上限。
- 文件系统（filesystem）：后端可插拔，本地、沙箱、远程都可以，Agent 的 read/write/edit/search 工具不绑死存储。llm-wiki 跑在沙箱后端就是这个抽象的好处。
- 上下文管理（context management）：长线程自动摘要、工具输出卸载到磁盘。这是「batteries-included」里最隐形但最值钱的一块，自己实现要处理触发时机、摘要质量、文件引用回填一堆细节。
- shell 访问：在沙箱里跑命令，编码类任务必需。安全边界完全依赖你的沙箱配置。
- 持久记忆：state 和 store 后端可插拔，支持跨会话召回。和上一篇说的公司 harness 两层记忆相比，开源版只给原语，分层策略要自己写。
- 人在环路（HITL）：工具调用执行前可以批准、编辑、拒绝。llm-wiki 的 review 流程就是这个原语的应用范式，建议写操作默认开启。
- skills：按需加载的可复用行为，和 Claude Code 的 skills 概念对齐，适合把团队 SOP 打包进去。
- 工具与 MCP：自带函数或任意 MCP server 都能接，生态外摆，不重复造轮子。
边界与代价
几个必须知道的事实。
第一，安全模型是「trust the LLM」，README 的 Security 一节写得很直白：Agent 能做它的工具允许的任何事，不要指望模型自我约束，边界必须在工具和沙箱层面强制执行。这句话翻译过来就是：生产部署时文件系统和 shell 不给沙箱、不做网络白名单，等于把你的环境钥匙交给 prompt 注入。这不是缺陷，是明确的设计取舍，但你要按这个假设来配。
第二，抽象层有重量。deepagents 在 LangGraph 之上叠了 middleware、文件系统、提示词体系，出问题时要穿过三层排查，学习曲线比直接写 LangGraph 陡。如果你的 Agent 就是「收参数、调一次模型、返回」，用 create_agent 甚至裸 LangChain 更合适，harness 的默认行为对你全是负担。
第三，生态分层要认清：开源 deepagents 给原语；channels、cron、托管沙箱、两层记忆、身份这些公司级组件在 Managed Deep Agents（绑 LangSmith 云）里；官方还出了终端编码 Agent「Deep Agents Code」（curl -LsSf https://langch.in/dcode | bash）对标 Claude Code；JS/TS 版在独立仓库 deepagents.js。想数据不出内网，就只能基于开源版自建那五块。
第四，项目 2025 年 7 月才建仓，迭代很快，示例里的模型版本号（如 claude-sonnet-4-5-20250929、gemini-3-pro-preview）和 API 会变，跟版时以官方文档为准。
谁该用，从哪个示例抄起
适合用：要做长周期、多步骤、有文件产出的 Agent（调研、代码、知识管理）；希望子 Agent 编排、上下文压缩这些基础设施工艺开箱即用；技术栈已经在 LangChain/LangGraph 生态里。
不用也行：Agent 流程是简单一问一答；团队主栈是 TS（可以关注 deepagents.js，但成熟度目前落后 Python 版）；需要对 Agent 循环做非图状的极端定制，直接写 LangGraph 更干净。
上手路径建议：先跑最小示例理解默认行为，做调研类产品抄 deep_research 的「主 Agent 规划 + 隔离子 Agent + 硬上限 + think_tool」结构，做知识沉淀类产品抄 llm-wiki 的「index 目录 + append-only 日志 + 读写分阶段」结构。这两个示例几乎覆盖了当下严肃 Agent 应用的两大形态，读完代码再看自己的需求，要替换哪块心里就有数了。
参考文档与链接
- GitHub: langchain-ai/deepagents — 主仓库，Python，MIT，30k+ stars
- 示例一：deep_research README — 深度调研 Agent 完整示例
- 示例二：llm-wiki README — 持久 wiki 与 ingest/query/lint 工作流
- deepagents 官方文档：Overview — 概念总览
- deepagents：Going to production — 生产化指南
- LangChain 生态分层：products overview — LangGraph / create_agent / deepagents 的关系
- GitHub: langchain-ai/deep-agents-ui — 官方专用聊天与文件可视化 UI
- GitHub: langchain-ai/deepagentsjs — JavaScript/TypeScript 版本
- Deep Agents Code 文档 — 官方终端编码 Agent
- LangGraph 本地服务器 —
langgraph dev与 Studio - LangChain Academy：Deep Research 课程 — 示例配套免费课程
- uv 包管理器 — 示例统一使用的 Python 环境工具
- Tavily — 示例使用的搜索 API，免费额度
- 相关文章：LangChain 公司级 harness 五组件 — 本文的上一篇，托管层视角
- 相关文章：Deep Agents 架构深挖 — 早期架构层分析
- 相关文章：从零构建知识 Agent，不用 embeddings — 与 llm-wiki 思路呼应的文件式知识检索
deep_research 和 llm-wiki，你更想先抄哪个？或者你拿 deepagents 做过什么 Agent？评论区聊聊。
作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top
本文首发于 AI人工智能时代，转载请注明出处。
