deepagents

LangChain Deep Agents 是 LangChain 官方推出的「开箱即用型 Agent 框架」——如果说 LangGraph 是搭建 Agent 的「引擎」，Deep Agents 则是把一切组装好的「整车」。23,295 颗星、MIT 许可、活跃在 LangChain 生态核心，这个项目正在重新定义 Agent 开发的最佳实践。

---

背景：为什么需要 Agent Harness？

大多数 Agent 框架（如 LangChain 早期版本）只提供最底层的工具调用循环：模型生成 → 工具执行 → 结果回传。你需要自己处理上下文溢出、文件管理、子任务委托、状态持久化……这些在实际生产中极为繁琐的「基础设施」问题。

Deep Agents 的诞生，就是为了把这层脏活累活封装掉。它的定位介于 LangGraph（底层图引擎）和 LangChain create_agent（轻量封装）之间，是一个「有态度的全功能 Agent 脚手架」——opinionated，即默认配置已为长期任务优化，你可以在此基础上按需定制，而不必从零搭建。

该框架由 LangChain 团队维护，版本 0.6.3，支持 Python 3.11+。

---

核心功能：给 AI 一个完整的工作台

Deep Agents 提供了 Agent 在真实任务中需要的一切：

规划与待办事项：内置 write_todos 工具，Agent 可以维护结构化的任务清单，在多步骤工作中持续追踪进度。这是长期任务代理的必备能力，也是大多数框架忽略的细节。

虚拟文件系统：Agent 可以读写文件、搜索内容，背后是支持本地、沙箱或远程等多种存储后端的可插拔架构。支持声明式的读写权限规则，控制 Agent 能访问哪些目录——这对安全隔离至关重要。

上下文管理：当对话历史超过模型上下文窗口时，Deep Agents 会自动压缩或外化到磁盘，而非粗暴截断。这解决了长程 Agent 任务中最常见的「记忆丢失」问题。

子 Agent 委托：通过 task 工具，主 Agent 可以将复杂任务分解并委托给子 Agent，每个子 Agent 拥有独立的上下文窗口。类似于 Claude Code 的多 Agent 协作模式。

Shell 执行：在指定沙箱环境中运行命令行指令，Agent 具备完整的终端操作能力。

持久化记忆：基于可插拔的状态和存储后端，Agent 可以在跨会话之间保持记忆和上下文。

人在回路：工具调用前可配置审批流程，人类可以批准、修改或拒绝某次操作，适用于高风险任务场景。

Skills 机制：可复用的行为模块，Agent 按需加载，类似 AI 应用的「插件」系统。

MCP 服务器支持：内置 Model Context Protocol，任何符合 MCP 标准的工具或服务器均可接入。

---

技术架构：站在 LangGraph 肩膀上

Deep Agents 基于 LangGraph 构建，充分利用了其流式输出、状态持久化和 checkpointing 能力。依赖栈如下：

层级	技术
Agent 运行时	LangGraph（状态图 + 持久化）
LLM 接口	LangChain Core + 各 Provider SDK
可观测性	LangSmith（追踪、评估、部署）
工具生态	LangChain Tools + MCP

代码仓库采用 monorepo 结构，核心代码在 libs/deepagents，CLI 应用在 libs/cli，另有 libs/acp、libs/code、libs/partners 等模块。项目使用 uv 管理依赖，pyproject.toml 定义包结构，测试框架为 pytest（含 pytest-asyncio 异步支持）。

代码质量方面，仓库包含完整测试套件（pytest + pytest-cov）、pre-commit 配置、ruff 代码检查、类型检查（ty），文档质量极高——不仅有 README，还有 THREAT_MODEL.md 威胁模型文档、DEV.md 开发指南，以及独立的文档站点。

项目支持任何实现了 tool calling 的 LLM——无论是 OpenAI GPT 系列、Anthropic Claude、Google Gemini，还是 Ollama/vLLM 等本地部署模型，Model-agnostic 特性让用户不受单一供应商绑定。

---

上手体验：SDK 与 CLI 两条路径

Python SDK 方式（适合集成到现有项目）：

uv add deepagents

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": ["Research LangGraph"]})

CLI 方式（开箱即用，类似 Claude Code）：

curl -LsSf https://langch.in/dcode | bash

这是官方提供的「一键安装脚本」，安装后即可在终端中运行一个功能完整的编码 Agent，支持配置模型、API Key 等。CLI 基于 Textual 框架构建，提供交互式终端体验。

另有 JavaScript/TypeScript 版本 deepagents.js，可在 Node.js 环境中使用。

---

行业意义：Agent 开发进入「脚手架时代」

Deep Agents 的出现，代表了 Agent 开发从「从零组装」向「脚手架构建」的范式转变。

LangChain 生态三个层次的分工愈发清晰：LangGraph 负责底层图执行，LangChain create_agent 提供轻量封装，而 Deep Agents 则打包了生产级 Agent 需要的一切「默认能力」。这种分层设计让开发者可以根据需求选择合适层级——既可以从 Deep Agents 开始快速落地，也可以深入 LangGraph 定制特殊逻辑。

项目配套的 LangSmith 集成是其生产就绪的关键。Agent 执行轨迹的数据量极大，人工排查几乎不可能，LangSmith 提供了追踪、可视化和 AI 辅助调试（Polly 功能），让 Agent 的行为分析和调优变得可操作。

从 GitHub 数据看，项目在 2026 年 5 月仍有活跃更新（pushed_at: 2026-05-23），版本处于 Beta 阶段，功能仍在快速迭代中。

---

局限与风险

Deep Agents 本质上是一个「有态度的封装」，这种 opinionated 特性既是优势也是局限。如果你需要的 Agent 行为与框架预设差异较大，可能需要大量覆写或深度改造。

另一个现实挑战是：Deep Agents 的能力上限高度依赖底层 LLM 的工具调用质量。对于不支持 tool calling 或 tool calling 质量较差的模型，Deep Agents 的很多高级特性可能无法充分发挥。

此外，虽然框架本身免费开源，但配合使用的 LangSmith（追踪、评估）有付费层级，生产环境可能产生额外成本。

---

总结

维度	评价
功能完整性	⭐⭐⭐⭐⭐ 开箱即用，功能丰富
技术深度	⭐⭐⭐⭐⭐ 基于 LangGraph，生产级
上手门槛	⭐⭐⭐⭐ CLI 一键安装，Python SDK 简洁
文档质量	⭐⭐⭐⭐⭐ 独立文档站、威胁模型、示例丰富
生产就绪度	⭐⭐⭐⭐ LangSmith 集成，MIT 许可

Deep Agents 适合想要快速构建复杂 Agent 应用但不想陷入基础设施细节的开发者，是当前 AI Agent 生态中完成度最高的「一站式」解决方案之一。