deepagents 部署自治编码 Agent：基于 AGENTS.md 的 Plan → Implement → Review → Deliver 工作流实战指南-育师

deepagents 部署自治编码 Agent：基于 AGENTS.md 的 Plan → Implement → Review → Deliver 工作流实战指南

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

导读：本文围绕deploy-coding-agent示例中的 AGENTS.md，系统讲解如何为 deepagents 定义一个"输入任务描述 → 自主规划 → 编码实现 → 测试审查 → 提交交付"的自治编码 Agent。你将掌握deepagents deploy的部署配置（agent.json）、四阶段工作流设计、write_todos规划工具与execute沙箱执行的配合方式，以及 code-review / coding-prefs / planning 三个内置 Skill 的实战用法，并学会通过 LangGraph SDK 以流式方式调用已部署的 Agent。

一、示例概述：一个可自主完成编码任务的 Agent

deploy-coding-agent是 deepagents 仓库中一个完整的可部署示例（位于 examples/deploy-coding-agent/），它的目标非常明确：给定一个任务描述，Agent 在拥有完整 Shell 访问权限的 LangSmith 沙箱内自主完成计划、实现、测试和提交。

整个示例由以下文件构成：

examples/deploy-coding-agent/ ├── AGENTS.md # Agent 指令与四阶段工作流（本文主体） ├── agent.json # 部署配置（Agent 名称与模型） └── skills/ ├── code-review/ # 代码审查 Skill，附带 lint 辅助脚本 ├── coding-prefs/ # 用户编码偏好 Skill └── planning/ # 任务规划 Skill

从结构上可以清晰看出 deepagents 的组件化设计哲学：系统提示（AGENTS.md）负责定义行为与流程，agent.json 负责部署参数，skills/ 目录以 Skill 形式承载可复用的能力模块。

二、部署前提：环境变量与沙箱要求

在部署之前，需要准备两个环境变量（见 README.md）：

变量	说明
`ANTHROPIC_API_KEY`	Claude 模型访问凭证
`LANGSMITH_API_KEY`	部署命令与 LangSmith 沙箱必需

复制.env.example为.env并填入两个 Key 即可。其中LANGSMITH_API_KEY是部署和沙箱的硬性前提——Agent 运行在一个远程沙箱环境中，具备完整的 Shell 访问能力。

三、部署配置与命令：从 agent.json 到 deepagents deploy

示例的部署配置 agent.json 非常精简：

{ "name": "deepagents-deploy-coding-agent", "runtime": { "model": {"model_id": "anthropic:claude-sonnet-4-5"} } }

name：Agent 在部署平台上的唯一标识；
runtime.model.model_id：指定运行模型，此处为anthropic:claude-sonnet-4-5。同仓库的另一个示例 deploy-content-writer 则使用openai:gpt-4.1，说明model_id可按需替换为任意受支持的提供商模型。

部署命令只有一行：

deepagents deploy

该命令会读取当前目录下的agent.json，将 Agent 及其关联的 AGENTS.md 指令、skills 目录一并打包部署到 LangSmith。部署完成后，可在 LangSmith 控制台的Deployments页面找到部署 URL，用于后续 SDK 调用。

注意（MCP 服务器变更）：该示例早期版本曾通过mcp.json接入 LangChain 文档 MCP 服务器。如今 MCP 服务器已升级为工作区级（workspace-level）资源，需先用deepagents mcp-servers add --url <url>注册一次，再在tools.json文件中引用（详见 README.md）。

3.1 关于部署机制的源码佐证

deepagents 构建在 LangGraph 之上，官方 README 将其定位为 "batteries-included agent harness"，并明确指出其具备生产就绪特性：基于 LangGraph 的流式输出、持久化、checkpointing，以及对 LangSmith 的一等公民追踪、评测与部署支持（见 libs/deepagents/README.md）。从源码结构看，部署链路依赖的是 LangGraph Server 与 LangSmith 的托管能力，deepagents deploy只是把本地定义的 Agent 配置与指令上传并实例化的入口。

四、AGENTS.md 核心：四阶段工作流设计

AGENTS.md 为 Agent 定义了对每个任务都强制执行的分阶段工作流，这是本示例的灵魂所在：

Phase 1: Plan（规划）

仔细阅读 issue / 任务描述；
探索仓库结构，理解代码库；
使用grep和glob定位相关文件；
使用write_todos写出分步实施计划；
如果任务有歧义，先提问澄清再动手。

规划阶段的关键工具是write_todos。从 libs/acp/deepagents_acp/server.py 的源码可以看到，该工具被实现为待办事项更新机制，且在 ACP 协议服务端会被特殊处理（如write_todos可配置为需要人工审批的决策点，见 libs/acp/examples/demo_agent.py），这说明规划不是"走形式"，而是可被观测、可被人工干预的真实状态节点。

Phase 2: Implement（实现）

严格按计划逐步执行；
编写符合现有模式的干净、惯用代码；
每次重大变更后运行测试；
测试失败立即调试修复，再继续下一步；
每完成一步就更新待办列表。

Phase 3: Review（审查）

运行完整测试套件：execute("python -m pytest")；
如配置了 linter 则运行：execute("ruff check .")；
端到端通读每个修改过的文件；
验证改动确实解决了原始 issue；
如有问题，回到 Phase 2 重新实现。

Phase 4: Deliver（交付）

使用清晰、描述性的提交信息提交更改；
总结已完成的工作与关键决策。

这四阶段与"编码标准"（Coding Standards）小节共同构成一个闭环：标准定义了实现期的质量底线（匹配既有代码风格、新功能必须写测试、改动最小化、只在逻辑不自明处加注释、在系统边界处理错误并信任内部代码），流程则保证每个环节可验证、可回溯。

五、常用模式：文件定位、代码理解、测试与 Shell 执行

AGENTS.md 的 "Common Patterns" 小节给出了 Agent 日常工作的四条高频范式，全部以工具调用形式落地：

定位文件：先用glob("**/*.py")或grep("pattern")缩小范围，再读文件，避免盲目打开整个仓库；
理解代码：优先阅读 imports、类定义与测试，快速建立代码心智模型；
验证改动：编辑后必须运行测试，不假设正确性；
执行命令：git、pytest、linter、构建等一律通过execute()在沙箱内执行。

这套模式与 deepagents 的沙箱化 Shell 设计一脉相承：仓库官方文档将 "Shell access — run commands in your sandbox of choice" 列为核心能力（见 libs/deepagents/README.md），execute()正是 Agent 触达该能力的关键通道。

六、Skills 深度解析：规划、审查与偏好记忆

示例为 Agent 配备了三个 Skill，每个 Skill 都是一个带 frontmatter（name+description）的SKILL.md，deepagents 会将其作为可检索的能力模块注入上下文：

6.1 planning：把任务拆解为可执行计划

planning/SKILL.md 规定了一套五步规划法：

理解任务：完整阅读任务描述，明确预期产出与验收标准，记录约束条件；
探索代码库：找到仓库根目录、识别技术栈（语言 / 框架 / 测试运行器）、阅读 README 与 CONTRIBUTING、研究既有测试的模式；
定位相关文件：用grep找相关代码，读入口文件与相关模块，区分"需修改"与"需新建"的文件；

写出计划：通过write_todos生成结构化计划，示例格式为：

write_todos([ "1. <specific change in specific file>", "2. <next specific change>", "3. Write tests for <feature>", "4. Run test suite and fix failures", "5. Review all changes" ])

评估风险：是否有破坏性变更、边界情况、对其他模块的影响，把不确定项标记出来供审查。

Skill 还给出了计划质量准则：3–10 个具体步骤、每步具体到无需再规划即可执行、显式包含"写测试"与"跑测试"步骤、以"审查/验证"步骤收尾。

6.2 code-review：交付前的结构化自审

code-review/SKILL.md 提供了一份四维审查清单：

正确性（Correctness）：改动是否解决原始问题、是否引入副作用、边界情况是否处理、错误处理是否恰当（不过度）；
代码质量（Code Quality）：风格是否一致、是否有多余的复杂性、命名是否清晰、是否残留死代码 / 注释掉的代码 / TODO；
测试（Tests）：新功能是否有覆盖、既有测试是否仍通过、是否同时覆盖 happy path 与错误路径、测试是否过于脆弱（不测实现细节）；
安全（Safety）：是否硬编码密钥、用户输入是否在边界验证、是否存在 SQL 注入 / XSS / 命令注入向量、文件操作是否使用安全路径。

审查流程建议先端到端通读每个修改文件（而非只看 diff），然后依次执行：

execute("python -m pytest -v") execute("ruff check .") execute("python /skills/code-review/lint_check.py .")

其中lint_check.py是该 Skill 附带的轻量 lint 辅助脚本（源码见 skills/code-review/lint_check.py）。从源码看，它基于 Python 标准库ast实现，递归扫描 Python 文件并报告三类常见问题：

缺失模块 docstring：ast.get_docstring(tree)为空即告警；
函数过长：超过 50 行（含 async 函数）即告警，如源码第 42-47 行所示；
裸except:子句：ast.ExceptHandler且node.type is None即告警（源码第 50-51 行）。

脚本退出码语义清晰：发现任何告警返回 1 并打印N warning(s) found.，无告警返回 0 并打印No warnings found.，可直接作为 Agent 交付前检查的硬性信号。

6.3 coding-prefs：用户级编码偏好记忆

coding-prefs/SKILL.md 管理/memory/coding-prefs.md，该文件是**用户级（user-scoped）**的——每个用户拥有独立副本，写入内容只影响与同一用户的后续会话。

何时读取：在决定代码风格、测试框架、提交信息格式之前；在决定是否添加注释 / 类型标注 / docstring 之前；在超出任务范围进行重构之前；
何时写入：用户给出可复用的持久反馈时，例如 "Don't add docstrings unless I ask"、"I prefer pytest over unittest"、"Stop summarizing what you did at the end"；
如何写入：先读后追加（文件可能不存在），绝不覆盖，偏好随时间累积；若新偏好与旧条目冲突，则替换旧行并注明变更。

这一机制让 Agent 的"风格稳定性"从单次会话扩展到跨会话，是长期使用同一部署 Agent 时保持输出一致性的关键。

七、部署后实测：给 Agent 发任务

部署完成后，可以在 LangSmith 中打开该 Agent，直接发送任务进行验证，README 推荐了三个典型任务：

"Add a function that reverses a string and write a test for it"（实现功能 + 补测试）
"Find all TODO comments in the repo and create a summary"（代码检索 + 总结）
"Refactor the main module to use dataclasses"（重构）

这些任务分别覆盖了实现、检索、重构三类典型编码场景，恰好对应 AGENTS.md 四阶段工作流中"测试驱动""代码理解""最小改动"等原则。Agent 会严格遵循 AGENTS.md 定义的 Plan → Implement → Review → Deliver 流程处理这些任务。

八、通过 LangGraph SDK 流式调用部署的 Agent

除了在 LangSmith 控制台手动对话，还可以通过 LangGraph SDK 以编程方式调用部署后的 Agent。README 给出的完整示例：

from langgraph_sdk import get_client client = get_client(url="https://<your-deployment-url>") thread = await client.threads.create() async for chunk in client.runs.stream( thread["thread_id"], "agent", input={"messages": [{"role": "user", "content": "Add a hello_world function and test it"}]}, stream_mode="messages", ): print(chunk.data, end="", flush=True)

要点拆解：

get_client(url=...)：URL 为部署 URL，可在 LangSmith 控制台的Deployments页面找到；
client.threads.create()：LangGraph 的持久化线程模型，天然支持多轮会话与状态恢复（checkpointing）；
client.runs.stream(..., stream_mode="messages")：以消息流模式逐块消费 Agent 输出，chunk.data即为增量内容，适合流式渲染到终端或 UI；
图节点名为"agent"，与 agent.json 中定义的 Agent 一一对应。

这种"部署一次、SDK 到处调"的方式，正是 deepagents 基于 LangGraph 的生产级部署能力的直接体现。

九、同系列示例对比与扩展思路

仓库的examples/deploy-*系列展示了同一套部署机制在不同 Agent 类型上的复用：

deploy-content-writer：内容写作 Agent，通过 blog-post / social-media 两个 Skill 产出文章；
deploy-gtm-agent：GTM（市场增长）Agent，配备 competitor-analysis Skill，并演示了subagents机制——subagents/market-researcher/目录下有自己的agent.json与AGENTS.md，可作为独立子 Agent 被主 Agent 通过task()调用；
deploy-mcp-docs-agent：MCP 文档类 Agent。

对照可见，AGENTS.md 的四阶段工作流 + skills 目录 + agent.json 的"三位一体"结构是可复用的 Agent 骨架。若要让编码 Agent 处理更复杂任务，AGENTS.md 中的 Subagents 小节提供了扩展方向：使用task(subagent_type="researcher")让子 Agent 调研 API、文档或模式，使用task(subagent_type="general-purpose")派发相互独立的子任务——主 Agent 专注规划与集成，子 Agent 分担研究与实现，形成可水平扩展的协作结构。

十、小结

deploy-coding-agent示例完整演示了 deepagents 的"部署型自治编码 Agent"范式：以 AGENTS.md 定义四阶段行为契约（规划 → 实现 → 审查 → 交付），以 agent.json 声明部署参数，以三个 Skill 注入规划、审查与偏好记忆能力，以 LangSmith 沙箱提供完整 Shell 执行环境。整个方案在 LangGraph + LangSmith 的生产级底座上运行，既能通过deepagents deploy一行命令上线，也能通过 LangGraph SDK 流式编程调用，是一套从定义到落地全程可复制的 Agent 工程化模板。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考