ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

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

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。一、示例概述一个可自主完成编码任务的 Agentdeploy-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_KEYClaude 模型访问凭证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} } }nameAgent 在部署平台上的唯一标识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.mdexecute()正是 Agent 触达该能力的关键通道。六、Skills 深度解析规划、审查与偏好记忆示例为 Agent 配备了三个 Skill每个 Skill 都是一个带 frontmatternamedescription的SKILL.mddeepagents 会将其作为可检索的能力模块注入上下文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 文件并报告三类常见问题缺失模块 docstringast.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 之前在超出任务范围进行重构之前何时写入用户给出可复用的持久反馈时例如 Dont 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(urlhttps://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_modemessages, ): print(chunk.data, end, flushTrue)要点拆解get_client(url...)URL 为部署 URL可在 LangSmith 控制台的Deployments页面找到client.threads.create()LangGraph 的持久化线程模型天然支持多轮会话与状态恢复checkpointingclient.runs.stream(..., stream_modemessages)以消息流模式逐块消费 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-agentGTM市场增长Agent配备 competitor-analysis Skill并演示了subagents机制——subagents/market-researcher/目录下有自己的agent.json与AGENTS.md可作为独立子 Agent 被主 Agent 通过task()调用deploy-mcp-docs-agentMCP 文档类 Agent。对照可见AGENTS.md 的四阶段工作流 skills 目录 agent.json 的三位一体结构是可复用的 Agent 骨架。若要让编码 Agent 处理更复杂任务AGENTS.md 中的 Subagents 小节提供了扩展方向使用task(subagent_typeresearcher)让子 Agent 调研 API、文档或模式使用task(subagent_typegeneral-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),仅供参考
返回列表