如何将 Deep Agents 用于开源项目：实操指南
之前为了自动化维护开源项目，我写了一大堆 Python 脚本，结果把自己坑惨了。我急需一个能自动给 issue 分类、更新文档、跑测试，还能提交 PR 的工具——而且得能在一次长时间运行中搞定所有事，不能干到一半就把上下文给忘了。我试过不少 Agent 框架，它们要么一遇到多步任务就拉胯，要么就得让我从头开始自己搭上下文管理、任务规划和子 Agent 委派。后来我发现了 Deep Agents，这是 LangChain 专门为长程任务打造的开源 Agent 框架。下面是我把它跑起来过程中积累的一些经验。
缘起：我遇到了什么问题
我维护着一个中等规模的开源项目，积压了一堆没处理的 issue、过时的文档，还有一直挂掉的 CI 检查。我想要一个 Agent 能帮我：
- 读一遍未解决的 issue 并给它们分类
- 根据最近的代码改动更新文档
- 跑测试套件并修复简单的报错
- 起草带有规范描述的 PR
那些简单的“提示词-回复”式工具老是记不清进度。它们刚开始给 issue 分类，聊得稍微长一点，就把原计划忘得一干二净。我需要的是一个自带规划能力、持久记忆，还能委派子任务，且不会因为上下文窗口爆掉而全盘崩溃的工具。
入门：安装
Deep Agents 既提供了 SDK，也提供了一个叫 dcode 的 CLI 工具。因为想在自己的仓库里快速试水，所以我先用了 CLI。
curl -LsSf https://langch.in/dcode | bash
这条命令会把 dcode 装到你的系统里。如果你喜欢，也可以通过 pip 来装：
pip install deepagents
第一个小坑：CLI 安装倒是很顺，但我一开始没意识到还得单独配置模型提供商。Deep Agents 是模型无关的，这点很棒，但也意味着你得自己准备好 API Key。我先是配了我的 OpenAI Key：
export OPENAI_API_KEY="sk-..."
你也可以用 Anthropic，通过 Ollama 跑本地模型，或者任何支持工具调用（tool calling）的提供商。后来我写代码时换成了 Claude，发现一样好用——模型切换毫无卡顿，这绝对是 Deep Agents 的一大亮点。
跑第一个任务：给 Issue 分类
我把 dcode 指向了我的开源仓库，给了它一个具体的任务：
dcode
然后在交互界面里输入：
> 把这个仓库里未解决的 issue 都过一遍。把每个 issue 分类为 bug、feature request（功能请求）、question（提问）或 stale（已停滞）。给它们打上对应的标签。对于超过 90 天没有任何活动的 issue，打上 "stale" 标签，并留一条礼貌的评论，问问它是否还有参考价值。
接下来的操作让我眼前一亮。Deep Agents 并没有无脑去调 GitHub API，而是先制定了一个计划——把任务拆成了“拉取未解决 issue”、“分析每个 issue”、“确定分类”、“打标签”和“处理停滞 issue”这几步。这个规划步骤是内置在框架里的，在正式开干之前，你能眼看着它把目标拆解开来。
接着，Agent 开始逐个处理 issue。当它撞上 GitHub API 的频率限制时，它会自动退避并重试——这代码我一行都没写。它大概用了 20 分钟就给 47 个 issue 分好了类，这活儿要是换我自己干，得搭进去一整个下午。
上下文管理：真正的杀手锏
跟我以前用过的其他 Agent 配置相比，这才是 Deep Agents 大放异彩的地方。长时间运行的任务会产生海量的对话历史。大多数 Agent 要么一碰到上下文限制就崩溃，要么就开始“失忆”，忘了前面的步骤。
Deep Agents 通过内置的中间件解决了这个问题，它能：
- 压缩对话历史 —— 旧消息会被自动摘要
- 把大型工具返回结果转存到磁盘 —— 它不会把巨大的 API 响应留在上下文里，而是写进虚拟文件系统，只保留一个引用
- 使用提示词缓存 —— 在遇到重复模式时降低延迟和成本
我在它处理那 47 个 issue 时亲眼见识了这招。大概处理到第 15 个 issue 的时候，上下文就变很大了。Deep Agents 把前面的对话进行了压缩，只保留了已经分类过的内容摘要，腾出空间给剩下的 issue。Agent 丝毫没有搞丢自己的进度。
子 Agent：委派并行工作
下一个任务，我想根据最近的代码改动，跨多个文件更新文档。这时候子 Agent 就派上大用场了。
Deep Agents 允许你为独立的子任务生成子 Agent，每个子 Agent 都有自己独立的上下文窗口。这意味着一个子 Agent 可以去改 API 参考文档，另一个去更新 README，它们各自的上下文互不干扰。
在 SDK 里，代码长这样：
from deepagents import DeepAgent
agent = DeepAgent(model="claude-sonnet-4-20250514")
result = agent.invoke(
"Update all documentation files to reflect the changes in the v2.3 release. "
"Work on the README, API reference, and changelog in parallel using subagents."
)
主 Agent 把任务拆成了三个子任务，为每个任务生成了子 Agent，并协调了最终结果。每个子 Agent 都有独立的上下文窗口，所以它们不会互相打架。主 Agent 等这三个子 Agent 都干完活后，给我返回了一份总结。
有个坑得注意：子 Agent 默认共享同一个虚拟文件系统，所以如果两个子 Agent 同时去改同一个文件，就会起冲突。我是吃过这亏的，当时两个子 Agent 同时去更新 changelog，直接撞车了。解决办法是在委派任务时明确文件所有权——告诉每个子 Agent 它只能动哪些文件。
虚拟文件系统与持久记忆
Deep Agents 内置了一个跨会话持久化的虚拟文件系统。系统提示词、技能（skills）和长期记忆都存在这里。对于开源项目维护来说，这简直太好用了。
在我第一次处理完 issue 分类后，Agent 就学到了我仓库里的模式——有哪些标签、命名规范是什么、issue 通常长啥样。到了下一次会话，它直接就能想起这些信息，不用我再废话一遍。
你还可以定义技能——也就是 Agent 按需加载的复用行为。我给“PR 审查”建了个技能，里面包含了项目编码规范和审查清单的具体指令：
# In config.toml
[[skills]]
name = "pr-review"
description = "Review pull requests following project conventions"
prompt = """Review this PR against our coding standards:
- All public functions must have docstrings
- Tests required for new features
- No breaking changes without a deprecation path
- Follow the existing code style in each module"""
现在，只要我让 Agent 去审查 PR，它就会自动加载这个技能。
人工干预：把好关
搞开源项目，我可不想让 Agent 在我的仓库里撒野。对于敏感操作，Deep Agents 支持人工干预审批。
我设置了在执行以下操作前必须经过我同意：
- 推送代码
- 创建 PR
- 在 issue 下发评论
- 修改 CI 配置
# config.toml
[approval]
require_approval = ["git_push", "git_commit", "github_comment", "github_pr_create"]
当 Agent 想执行这些动作时，它会暂停并把即将干的事展示给我。我可以批准、修改或者拒绝。这招帮我避免了一次社死——当时 Agent 差点在一个其实是关键 bug、且有人正在跟进的 issue 下面评论：“This issue appears to be stale and inactive”。
使用 SDK 获得更精细的控制
CLI 用来跑简单任务很爽，但面对更复杂的工作流，SDK 能让你控得更细。这是我写的一个用来自动化处理每周开源维护工作的脚本：
from deepagents import DeepAgent
from langgraph.checkpoint.memory import MemorySaver
# Set up persistence for cross-session memory
checkpointer = MemorySaver()
agent = DeepAgent(
model="claude-sonnet-4-20250514",
checkpointer=checkpointer,
skills=["issue-triage", "doc-updater", "pr-review"],
)
# Run weekly maintenance
result = agent.invoke(
"Perform weekly maintenance: "
"1) Check for stale issues older than 60 days and label them. "
"2) Review open PRs that have been waiting more than 7 days. "
"3) Update the changelog with any merged PRs from this week. "
"4) Run the test suite and report any failures.",
config={"configurable": {"thread_id": "weekly-maintenance-2024-01-15"}}
)
有了 thread_id，我以后就能接着聊这次的话题。如果 Agent 中断了（我有一次断网就碰上了），我只要用同一个 thread ID，就能从它断掉的地方接着来。
用 LangSmith 追踪调试
Deep Agents 原生集成了 LangSmith 来做追踪。这绝对是调试救星。有一次我的 Agent 在更新文档时跑偏了，我打开 LangSmith 一眼就看出了哪一步出了岔子——它把代码里的注释错认成了公共 API 方法，给一个根本不存在的东西写了文档。
开启追踪功能：
export LANGSMITH_API_KEY="lsv2_..."
export LANGSMITH_TRACING=true
追踪记录会展示每一次工具调用、每一次模型请求，以及 Agent 做出的每一个决策。虽然这不是免费的（LangSmith 按用量收费），但用来调试复杂的 Agent 行为，这钱花得值。
实用建议与坦白讲局限性
在开源项目上用了 Deep Agents 几周后，这是我总结的心得：
建议：
- 先用 CLI，再写 SDK 代码。CLI 迭代更快，你也能自然地摸清 Agent 的能力边界。
- 任务描述一定要具体。“更新文档”太模糊了。“根据 src/processor.py 中
process_data函数新增的参数，更新 docs/api.md 里的 API 参考”这种描述效果才好。 - 重复任务用技能。如果你发现自己一遍遍输入相同的指令，把它抽离成一个技能吧。
- 任何会改动你公开仓库的操作，务必开启人工干预。Agent 是会犯错的。
- 留意你的 API 花费。带子 Agent 的长程任务烧 token 很快，盯紧你的用量。
局限性：
- 规划系统有时候会把简单任务过度拆解。我见过它把“修个错别字”拆成五个步骤，纯属浪费。
- 子 Agent 协调还不算完美。如果子 Agent 之间需要共享信息，你必须在任务描述里明确设计好。
- 文档还在完善中。有些配置选项文档没写清楚，我只能去啃源码才搞明白。
- 它有自己的一套设计理念，这大部分情况下是好事，但如果你的工作流跟它的设想不符，你就会跟框架较劲。如果你只想要个不带规划或子 Agent 的简单 Agent，用 Deep Agents 就属于杀鸡用牛刀了——直接用 LangChain 的
create_agent就行。 - 就行。
- MCP 服务器集成能用，但偶尔会抽风。我在连 GitHub MCP 服务器时就遇到过偶尔超时的问题。
尽管有这些局限，Deep Agents 已经成了我处理复杂开源维护任务的首选。光是内置的上下文管理，就把我之前被“Agent 失忆症”折磨的问题给解决了。而且它本身是开源的，这意味着遇到不好用的地方，我完全可以自己去检查代码、修改，甚至提交 PR 回馈社区。