企业官网建设流程全解析

Deepagents 开源 AI 代理：4 大核心能力与快速上手指南

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

deepagents 是一个开箱即用的开源 AI 代理框架，把规划、文件系统、子代理和上下文管理这些长任务里最繁琐的部分打包成了默认行为。你只需要一个支持工具调用的模型，几行代码就能跑起一个能读写文件、拆分任务、自己管理上下文的代理。它适合想快速做出"能干活"的 AI 助手、又不想从零搭轮子的开发者和团队。

📌 项目定位：一个"自带工具包"的 AI 代理

deepagents 官方给自己的定义是 "The batteries-included agent harness"（电池全含的代理外壳）。LangGraph 提供运行时，LangChain 的create_agent提供代理抽象，而 deepagents 在这两者之上补上了默认中间件、可插拔后端、子代理和技能——你拿到的不是空壳，而是一套调好的默认配置，想换哪件就换哪件，无需 fork。

代理跑在编辑器里：deepagents 通过 ACP 协议接入 Zed 等编辑器，直接操作代码。

🧩 核心能力拆解：4 大能力分别解决什么问题

子代理：把大任务拆给"同事"

任务太大时，主代理可以把子任务委派给子代理。每个子代理有独立的上下文窗口，干完活只把结论汇报回来，主代理的上下文保持干净。对应功能：subagents配置，可声明式定义或传入任意 LangGraph 编译图。

文件系统工具：读、写、改、搜一套齐全

代理内置read_file、write_file、edit_file、glob、grep等文件工具，后端可插拔——本地目录、沙箱、远程存储都能接。对应功能：backends包，文件、记忆、Shell 执行都在这一层决定"落在哪里"。

上下文管理：长对话不爆窗口

对话越长，token 越贵、上下文越容易溢出。deepagents 会自动对历史做摘要压缩，并把冗长的工具输出转储到磁盘，需要时再取回。对应功能：摘要中间件与工具输出 offload。

人在环审批：关键操作先过目

工具调用真正执行前，你可以批准、修改或拒绝。对应功能：human-in-the-loop 中间件，触发时代理会暂停等你确认，敏感操作不再失控。

⚙️ 它是怎么工作的：三步理解执行循环

构造时，create_deep_agent()解析模型、后端、提示词和子代理，组装好中间件栈，交给 LangChain 生成可运行的图。执行时，每一轮模型都会收到消息历史、系统提示词和工具列表，它要么直接回答，要么发起工具调用；工具结果写回状态，循环往复，直到产出最终答案。

这张图解了代理循环中模型调用的流式处理与重试逻辑，是理解执行过程的好入口。

你可以把它理解成一个拿任务清单的实习生：想一下 → 动手干 → 记结果 → 再想下一步。底层由 LangGraph 负责状态携带、检查点和流式输出，所以长任务中途失败可以从断点恢复，不用从头再来。仓库里的 ralph_mode 示例 就是这种"做一步、落盘、再循环"模式的完整演示。

🚀 快速上手：三步跑出第一个代理

第一步，安装 SDK：

uv add deepagents

第二步，几行代码创建代理并调用：

from deepagents import create_deep_agent agent = create_deep_agent(model="openai:gpt-5.5", system_prompt="You are a research assistant.") result = agent.invoke({"messages": "调研 LangGraph 并写一份摘要"})

第三步，想要终端里的编码代理，可以单独装dcode，它是基于 deepagents 构建、类似 Claude Code 的预置产品，详见 examples 目录里的现成玩法。

📋 真实使用场景：三个最有代入感的故事

长调研任务中途"失忆"。让代理读几十份文档并汇总，普通对话早把上下文撑爆了。deepagents 的摘要压缩加磁盘转储正好接住这个问题：中间结果写进文件，历史自动瘦身，最后主代理只读结论，不用把全过程背在脑子里。

多文件改动上下文互相污染。改一个横跨多目录的功能时，主代理把任务拆给子代理：每个子代理在独立上下文里各自作业，互不干扰，结束后只向主代理汇报结果。仓库的 content-builder-agent 示例 展示了用子代理和技能分工的完整写法。

生产环境出问题无从查起。上线后一次"答非所问"很难从日志里推断原因。deepagents 与 LangSmith 配合，能逐步回放每次模型调用和工具执行，定位到具体是哪一步跑偏。

🧠 进阶与扩展：换模型、加工具、挂技能

默认配置不顺手时，不用 fork：传自己的tools、换任意支持工具调用的模型（前沿 API、Baseten/Fireworks 上的开放权重、Ollama 本地模型都行）、覆盖系统提示词、定义子代理，甚至给代理挂载"技能"让它按需加载可复用行为。

agent = create_deep_agent( model="openai:gpt-5.5", tools=[my_custom_tool], system_prompt="你是社区运营助手。", )

LangSmith 里的一次完整追踪：每个中间步骤、时间戳和 token 消耗都清晰可见。

⚠️ 避坑指南：三条实操提醒

• 安全边界放在工具层，别指望模型自律。deepagents 遵循"信任 LLM"模型：工具允许它做什么，它就能做什么。给文件、Shell 上沙箱和权限，是唯一的可靠防线。
• 长任务先看上下文策略。摘要和 offload 是默认开启的，但超长工具输出仍建议后端指向磁盘或沙箱，避免状态膨胀拖慢每一轮。
• 工具"可见"不等于"可用"。模型看不到某个工具，多半是中间件没装或 profile 排除了它；工具可见但执行失败，则要看所选后端的能力和文件系统权限，两条路径排查方向完全不同。

🎯 总结

deepagents 把长任务代理最麻烦的四件事——子代理、文件、上下文、审批——默认做好，且对模型不挑食、对扩展不封闭。下一步建议：装好 SDK 后，先让它做一件"查资料、写文件、再总结"的小事，亲自感受一下这个执行循环。

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