Deep Agents 完整指南：如何让 AI 代理靠规划、文件与子代理完成长程任务

Deep Agents 完整指南如何让 AI 代理靠规划、文件与子代理完成长程任务【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents让 AI 代理完成一件大活——调研一个主题、核对资料、写出成稿——听起来不难但真实跑起来经常卡在同一类地方对话越滚越长模型把前面的关键结论忘了一次工具调用返回了上万行内容直接把上下文窗口撑爆任务明明可以拆成几路并行代理却只能串行硬撑。Deep Agentsdeepagents 库就是冲着这些问题来的它是一个开箱即用的代理框架agent harness基于 LangChain 和 LangGraph 构建把任务规划、文件系统读写、子代理委派、上下文自动压缩、人工审批这些长程任务必需的默认能力打包在一起用create_deep_agent()一个函数就能组装出可用的代理。下面不罗列功能清单而是跟着一项真实任务——调研一个技术主题并产出书面报告——看这些能力在流程中的每个环节分别解决了什么。第一步先立计划再动手代理拿到任务后默认工具集里有一个write_todos它被要求先把大任务拆成带状态的待办清单再逐项执行。这个习惯性的先规划是 Deep Agents 默认的中间件行为不是你额外写的逻辑。在 deep_research 示例 中主代理的工作流被明确规定为保存需求 → 用 TODO 规划 → 委派子代理 → 汇总 → 回复。规划的意义在于中途任何一步失败你都能从清单里看到卡在哪而不是面对一屏聊天记录无从下手。第二步把重活委派给子代理隔离上下文调研类任务最大的消耗是搜了一堆网页正文全堆在主对话里。Deep Agents 给主模型提供一个task工具主代理把一段自包含的任务描述交给指定类型的子代理子代理在独立的上下文窗口里完成全部工作完成后只把最终报告交回主代理中间过程不污染主线。子代理可以是声明式的给一个名字、描述、系统提示词还能单独指定更便宜的模型比如用 Haiku 级模型做检索用强模型做汇总也可以是已编译好的 LangGraph 图CompiledSubAgent你自定义的编排逻辑可以直接插进来仓库还实现了异步子代理AsyncSubAgentMiddleware任务提交到远端后立刻返回任务 ID主代理可以边干别的边轮询结果适合耗时较长的后台工作。具体的委派语义和上下文隔离细节见 子代理与 Skills 概念文档。content-builder 示例里主代理写完初稿前会把资料收集交给researcher子代理研究笔记落盘到research/目录写作过程只引用结论这就是隔离上下文带来的直接收益。第三步用文件系统当外部记忆代理边干活边把中间产物写成文件调研笔记存research/初稿存blogs/。文件系统后端是插件化的FilesystemBackend可指向本地目录、状态存储或沙箱工具面包括读、写、编辑、搜索。这里有两个值得注意的默认行为大结果自动卸载。当某次工具返回的文本超过预算框架会把全文写到磁盘的large_tool_results/路径下上下文里只留一个带预览的指针代理需要细节时再按offset/limit分段读回。单次工具调用不再能撑爆窗口。上下文吃紧时自动摘要。SummarizationMiddleware在每次模型调用前检查历史长度超过阈值就把较早的消息归档成带时间戳的会话档案conversation_history/{session_id}.md用摘要替换旧历史继续跑如果模型提供商真的返回了上下文溢出错误会触发同一条恢复路径再试。这两条机制的完整语义在 上下文管理文档 里有精确描述。也就是说长任务不丢信息不靠模型记忆力而靠文件加归档这两条确定性的通路。第四步在关键动作上设人工检查点默认栈里带 human-in-the-loop工具调用可以被配置成需要人工批准、编辑或拒绝后才执行。配合文件权限规则allow/deny/interrupt你可以让代理在只读目录里随便翻但一旦要execute跑 shell 命令或删文件就挂起等你确认。安全边界因此落在工具与沙箱层而不是希望模型自觉——这是项目安全策略里明确写下的立场。如果希望代理在受控环境里跑 shell沙箱后端是一等公民libs/partners/下提供了 Daytona、Modal、Runloop、Vercel、QuickJS 五种沙箱提供商集成命令在沙箱里执行宿主环境不受影响。第五步用 Skills 沉淀可复用的流程代理的方法论可以写成文件而不是代码一个技能就是一个带SKILL.mdYAML frontmatter 声明名字和描述的目录。框架只在系统提示里列出技能名称和描述模型判断任务匹配时才去读完整说明——这种渐进式加载让技能库可以很大而不撑大提示词。content-builder 示例 展示了完整的文件即配置形态AGENTS.md放品牌语气常驻系统提示、skills/blog-post/SKILL.md放博客写作流程按需加载、subagents.yaml定义研究子代理改语气、加技能、换子代理都不需要动 Python 代码。上手路径先跑起来再改哪里git clone https://gitcode.com/GitHub_Trending/de/deepagents最简路径两步走uv add deepagentsfrom deepagents import create_deep_agent agent create_deep_agent( modelopenai:gpt-5.5, # 任何支持工具调用的模型 tools[my_custom_tool], # 你的自定义工具或 MCP 工具 system_promptYou are a research assistant., ) result agent.invoke({messages: Research LangGraph and write a summary})接下来按需求深入加memory挂入常驻记忆文件加skills挂技能目录用subagents声明子代理换backend切换文件存储位置。改默认行为的入口在 核心源码 的graph.py组装、middleware/工具可见性与行为、backends/文件与 shell三份职责的映射关系见 架构总览。仓库是一个 monorepo除 SDK 外还有几块值得知道的组件libs/code/是预构建的终端编码代理dcode对标 Claude Code 的 TUI 产品libs/acp/把 Deep Agent 接入 Zed 等编辑器的 Agent Client Protocollibs/evals/是真实模型行为评测套件libs/talon/是实验性的长驻宿主。依赖方向单一它们都消费deepagentsSDK。长任务跑挂了怎么办重试与可观测性生产上跑长任务模型流中途断连是高频故障。dcode 的默认恢复策略是断流后标记该回答不完整下一轮重试从全新响应开始而不是拼接半成品转录、用量和工具状态逐次对账整个过程在界面上可见。排查代理为什么这么走时Deep Agents 跑在 LangGraph 之上天然支持流式、检查点与中断恢复配合 LangSmith 可以看到每一步的工具调用与状态变更——text-to-sql 示例的 trace 就是典型的观察视角如果你习惯在编辑器里工作libs/acp/提供的 ACP 集成可以把它作为外部代理接入而想直接体验成品dcode 的终端界面本身就是一个完整形态的 Deep Agent适合与不适合的场景适合需要多步骤、跨较长时间的任务深度调研、批量文档分析、代码库级修改——规划、隔离委派和上下文压缩正是为此调优希望文件即配置的团队改AGENTS.md和技能文件就能调整代理行为不发版要换模型的场景任何支持工具调用的模型都行前沿 API、开源权重、Ollama/vLLM 自托管都在官方 FAQ 里确认过需要沙箱隔离执行的生产部署配合检查点和 LangSmith 可观测。不适合一问一答的简单请求。完整框架的规划、子代理、摘要都是为长对话调的短任务直接用 LangChain 的create_agent更轻代理循环本身形状不对的场景比如固定 DAG 流水线直接写 LangGraph 图更合适期望模型自我约束不越权的场景。项目明确采用信任 LLM模型代理能做的事等于工具允许它做的事边界必须你在工具/沙箱层设好。content-builder 示例 的安全提示也说了它有文件系统写权限别在存放敏感数据的目录里直接跑。写在最后Deep Agents 的定位很清晰它不发明新运行时而是把长程多步任务最需要的几个默认件——规划、文件、子代理、上下文管理、人工审批——组装成一套可以直接改、可以整体替换的框架。从create_deep_agent()跑通第一个代理再到换后端、加技能、接沙箱每一步都有对应的示例和文档可以对照examples 目录、测试与评测指南。要不要用、用到哪一层取决于你的任务长度和隔离要求——这两点在本文的流程里应该已经能对照判断了。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考