企业官网建设流程全解析

Deep Agents 实战：一个开箱即用的 AI 代理框架

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

Deep Agents 是一个"batteries-included"（自带全套装备的）agent harness，解决的核心问题是：不自己拼装一堆工具，就能得到一个能干长活、会分任务、会管上下文的 AI 代理。它基于 LangChain 和 LangGraph 构建，MIT 许可，支持任何能调用工具的模型。

🎯 一、它凭什么值得关注

多数代理框架给的是积木，拼装靠你自己。Deep Agents 反过来：默认配置就是为长周期、多步骤任务调过的，装完即可规划、读写文件、把子任务派给子代理。

更关键的是它同时做到了模型无关和生产级。前沿 API、开源权重模型、自己跑的 Ollama 都能接；底层 LangGraph 提供流式输出、持久化和检查点（执行状态落盘，中断后从断点恢复），这些生产基建不用你自建。

值得一提的还有可替换性：任何组件都能扩展、覆盖或整体替换，不需要 fork。你甚至可以把一张自己编译的 LangGraph 图当作子代理插进来。

⚙️ 二、核心机制拆解

主循环怎么走。输入很简单：把模型、工具列表、系统提示词、可选的子代理配置交给create_deep_agent()。处理阶段，SDK 依次解析模型与 profile，组装一份有固定顺序的中间件栈（文件系统、子代理、摘要、人工审批各就各位），再把整套配置交给 LangChain 的create_agent()，由 LangGraph 驱动"模型→工具→模型"的循环。输出是一张编译好的图：传入消息、调用invoke，拿到结果，全程可流式推送。

更贴近实战的是Ralph 循环，一种以流行模式命名的迭代执行方式。你给出一个任务，代理带着全新上下文跑一轮，把成果写进文件系统；下一轮还是同一个任务，但基于磁盘上的状态继续推进，如此循环，直到任务完成或触达迭代上限。

图中展示了 Ralph 循环的一个完整周期：任务输入、代理执行、成果持久化到文件系统，再回到任务继续循环

可以类比接力赛交接棒：上下文是跑者的腿，会累，所以每轮换新的；文件系统是赛道，换多少个跑者，赛道上的进度都在。

🏗️ 三、架构与模块划分

deepagents/ ├── libs/ │ ├── deepagents/ # SDK核心：create_deep_agent、中间件、后端、profiles │ ├── code/ # dcode 终端编码代理（Textual TUI，支持远程沙箱） │ ├── acp/ # ACP 协议适配器，把代理接进 Zed 等编辑器 │ ├── talon/ # 长时运行代理宿主：渠道、定时任务、后台任务 │ ├── evals/ # 端到端评测框架与基准数据集 │ └── partners/ # 沙箱与平台集成：Daytona、Modal、Runloop、Vercel ├── examples/ # 可运行示例：ralph_mode、deep_research、text-to-sql 等 └── openwiki/ # 架构与概念文档

每个包都有独立的pyproject.toml和uv.lock，独立版本化。依赖方向是单向的：code、acp、talon 都依赖 SDK 核心，SDK 不反向依赖产品层。改行为前先定位它属于哪一层，可复用的 harness 行为放deepagents/，终端专属的流程放code/。

🚀 四、五分钟上手：Deep Agents 安装与最小示例

Deep Agents 安装一行命令：

uv add deepagents

最小可运行示例：

from deepagents import create_deep_agent agent = create_deep_agent( model="openai:gpt-5.5", # 任何支持工具调用的模型都行 ) result = agent.invoke({"messages": "Research LangGraph and write a summary"})

这几行之外不用配任何东西：代理会自己列待办、读写文件，对话变长时还会压缩上下文。

🔍 五、真实场景演练：Deep Agents 使用场景

长任务研究：不爆上下文

痛点：一个研究任务跑了几十个工具调用，上下文先炸了。Deep Agents 用子代理（每个带独立上下文窗口）分拆任务，摘要中间件负责压缩旧对话。示例 examples/deep_research/ 就是这套打法，整个过程可以在 LangSmith 追踪里逐步回放。

追踪界面展示了一次文本转 SQL 任务的完整执行：各中间件步骤、每次模型调用的耗时与 token、代理自己写下的待办列表

自主迭代：让代理自己把活干完

痛点：长任务经常中途失速，因为"模型忘了自己在干什么"。examples/ralph_mode/ 里的 Ralph 循环正是解法：python ralph_mode.py "Build a Python course" --iterations 5，代理每轮都拿新鲜上下文，用文件系统和 git 当记忆，中途断了也不丢进度。

终端编码：dcode 开箱即用

痛点：想在终端里干活，又不想离开终端。dcode（Deep Agents Code）就是现成方案：libs/code/ 实现，支持 MCP 工具加载、模型流式重试、远程沙箱，配置见 libs/code/README.md。

dcode 启动界面：LangSmith 追踪已开启、MCP 工具已加载，底部状态栏显示当前模型与 token 用量，可直接开始对话

编辑器集成：接进 Zed

痛点：代理困在终端里，IDE 用不上。libs/acp/ 的适配器把代理通过 stdio 暴露给支持 ACP（Agent Client Protocol，编辑器与代理之间的通信协议）的编辑器，配合持久化检查点，进程重启后还能接着上次聊。

🧩 六、从默认到定制

扩展点很明确：换模型、加工具、改提示词、配子代理，以及换 profile 与后端。落到代码上，就是改这几行：

agent = create_deep_agent( model="anthropic:claude-sonnet-4", # 第一行：换模型 tools=[my_query_tool], # 第二行：塞自己的函数 system_prompt="你是开源社区支持助手。", # 第三行：换人设 subagents=[reviewer], # 第四行：分派子任务 )

工具不局限于 Python 函数，任何 MCP 服务器都能作为工具接入。生态里最常碰的是三样：LangSmith（追踪、评测、部署）、远程沙箱（Modal、Daytona、Runloop，ralph 传--sandbox modal就让代码在远端跑）、ACP 编辑器接入。注意一点：自加自定义中间件时，它是相对核心栈的固定位置剪接进去的，顺序有意义，别随手挪。

⚠️ 七、踩坑与注意事项

安全边界：Deep Agents 遵循"信任 LLM"模型——代理能做工具允许的一切。边界要设在工具或沙箱层：比如 ralph 的--sandbox modal让代码跑在远程沙箱，--shell-allow-list白名单放行哪些 shell 命令。别指望模型自我约束。

上下文与成本：默认配置为长任务调过，但长对话依然烧 token。内置的摘要和落盘卸载能扛住主路径；自己写循环时，记得给上下文留预算。

测试门槛：新功能或修 bug 都要带单元测试，测试断言的是可观察行为，不是把实现逻辑复述一遍。项目把未接受的 warning 当错误处理，贡献前先把包内测试跑绿。

🤝 八、社区与贡献入口

想参与的话，入口都在仓库里：

• AGENTS.md — 开发规范与 PR 约定
• libs/DEVELOPMENT.md — 环境搭建与改-测-查循环
• openwiki/ — 架构与概念文档
• examples/ — 可运行示例，适合照着读

功能、文档、你发现的 bug，维护者都欢迎。建议先从 AGENTS.md 读起，再挑一个 examples/ 里的例子跑一遍。

📌 九、写在最后

Deep Agents 给你的是一台装好就跑的长任务代理：规划、文件、子代理、上下文管理都在默认值里，任何零件又能单独换掉。它适合想把研究、编码、内容生产这类多步骤长活自动化，又不想从零搭基建的团队和个人。下一步不用想太多：装个 dcode，让终端里的代理先跑起来。

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