DeepAgents：LangChain 官方推出的开箱即用 AI Agent 框架，一行代码启动你的智能体

项目地址：https://github.com/langchain-ai/deepagents
本周 Star 数：+5,498 ⭐（总计 16,738 stars）
语言：Python | 许可证：MIT
发布时间：2026年3月 | 作者：LangChain 官方团队

---

一、为什么 DeepAgents 值得关注？

在 AI Agent 领域，开发者面临的最大痛点从来不是"能不能做"，而是"怎么快速做好"。从零搭建一个生产可用的 Agent，需要处理提示词工程、工具调用、上下文管理、子任务分发、错误恢复……每一个环节都可能成为卡点。

DeepAgents 正是 LangChain 官方团队对这一痛点的直接回应。

这个项目本周在 GitHub Trending 上强势登榜，单周斩获 5,498 颗 Star，跻身 Python 类项目周榜前三。它的定位非常清晰：一个开箱即用的 Agent 框架（Agent Harness）——不是又一个 Agent 理论框架，而是一个你安装完就能立刻跑起来的、有主见的（opinionated）智能体系统。

更有意思的是，项目 README 里坦诚地写道：

"This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so."

这句话透露了两个信息：第一，Claude Code 的架构设计已经成为业界标杆；第二，DeepAgents 的野心是在此基础上做得更通用、更开放。

---

二、DeepAgents 是什么？核心定位解析

2.1 Agent Harness vs Agent Framework

在理解 DeepAgents 之前，有必要区分两个概念：

• Agent Framework（框架）：提供构建 Agent 的基础设施，如 LangGraph、AutoGen、CrewAI。你需要自己设计 Agent 的行为逻辑。
• Agent Harness（线束/脚手架）：在框架之上，提供一个已经配置好、可以直接运行的 Agent 实例。你不需要从零开始，只需要在已有基础上定制。

DeepAgents 属于后者。它基于 LangGraph 构建，但封装了所有"让 Agent 真正好用"的细节：规划能力、文件系统访问、Shell 执行、子 Agent 调度、上下文自动管理……

一句话总结：LangGraph 给你砖头，DeepAgents 给你一栋可以直接入住的房子。

2.2 设计哲学：信任 LLM

DeepAgents 的安全模型有一个鲜明的立场：

"Trust the LLM model. The agent can do anything its tools allow. Enforce boundaries at the tool/sandbox level, not by expecting the model to self-police."

这与很多 Agent 框架的做法相反。很多框架试图通过提示词约束模型行为，但 DeepAgents 认为这是不可靠的——真正的边界应该在工具层和沙箱层设置，而不是依赖模型的"自律"。

这种设计哲学让 DeepAgents 在实际使用中更加可预测，也更容易进行安全审计。

---

三、核心功能深度解析

3.1 规划工具（Planning）：write_todos

DeepAgents 内置了任务规划机制。Agent 在处理复杂任务时，会首先调用 write_todos 工具，将大任务分解为可追踪的子任务列表。

这个设计解决了 LLM 在处理长任务时的一个经典问题：中途"忘记"自己在做什么。通过显式的 TODO 列表，Agent 可以：

• 在任务开始时制定计划
• 在执行过程中标记完成状态
• 在遇到阻塞时重新评估优先级
• 在任务结束时验证所有子任务是否完成

这种"先计划，再执行"的模式，让 Agent 的行为更加透明和可控，也大幅提升了复杂任务的完成率。

3.2 文件系统工具（Filesystem）

DeepAgents 提供了一套完整的文件系统操作工具：

工具	功能
read_file	读取文件内容
write_file	创建或覆盖文件
edit_file	精确编辑文件（类似 diff patch）
ls	列出目录内容
glob	模式匹配文件搜索
grep	在文件中搜索文本

这套工具让 Agent 具备了真正的"工作记忆"——它可以将中间结果写入文件，在后续步骤中读取，而不是全部塞进上下文窗口。

特别值得一提的是 edit_file 工具。与简单的"读取-修改-写入"不同，精确编辑工具可以只修改文件的特定部分，避免因为上下文截断导致的文件损坏问题。这在处理大型代码文件时尤为重要。

3.3 Shell 执行（Shell Access）：execute

execute 工具允许 Agent 直接运行 Shell 命令。这是 DeepAgents 最强大也最需要谨慎使用的功能。

框架支持沙箱化执行，可以将命令限制在特定的环境中运行，防止意外的系统级操作。对于生产环境，建议配合远程沙箱（Remote Sandbox）使用，将 Agent 的执行环境与宿主系统完全隔离。

Shell 访问能力让 DeepAgents 可以：

• 运行测试套件并分析结果
• 执行构建脚本
• 调用外部 CLI 工具
• 管理 Git 仓库
• 安装依赖包

3.4 子 Agent 调度（Sub-agents）：task

这是 DeepAgents 最具创新性的功能之一。通过 task 工具，主 Agent 可以将子任务委托给独立的子 Agent 执行，每个子 Agent 拥有独立的上下文窗口。

这个设计解决了 LLM 上下文窗口的根本限制。当一个任务需要处理的信息量超过单个上下文窗口时，传统方案要么截断信息，要么使用 RAG 检索。DeepAgents 的方案更优雅：

1. 主 Agent 分析任务，识别可以并行或串行处理的子任务
2. 为每个子任务创建独立的子 Agent，传入必要的上下文
3. 子 Agent 在独立的上下文窗口中完成任务，返回结果摘要
4. 主 Agent 整合所有子任务结果，生成最终输出

这种"分而治之"的架构，让 DeepAgents 理论上可以处理任意复杂度的任务，只要任务可以被合理分解。

3.5 智能上下文管理（Context Management）

DeepAgents 内置了自动上下文管理机制：

• 自动摘要：当对话历史过长时，自动对早期内容进行摘要压缩
• 大输出文件化：当工具返回的内容过大时，自动保存到文件并在上下文中只保留文件路径
• 智能截断：在必要时智能截断内容，保留最关键的信息

这些机制让 Agent 可以在有限的上下文窗口内处理远超窗口大小的任务，而不需要开发者手动管理上下文。

---

四、快速上手：从安装到运行只需 3 步

4.1 安装

# 使用 pip
pip install deepagents

# 或使用 uv（推荐，更快）
uv add deepagents

4.2 最简单的使用方式

from deepagents import create_deep_agent

# 创建一个默认配置的 Agent
agent = create_deep_agent()

# 运行任务
result = agent.invoke({
    "messages": [{
        "role": "user", 
        "content": "Research LangGraph and write a summary to summary.md"
    }]
})

print(result["messages"][-1].content)

就这么简单。Agent 会自动：

1. 制定研究计划（write_todos）
2. 搜索相关信息
3. 将结果写入 summary.md 文件
4. 返回完成确认

4.3 自定义配置

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# 自定义模型、工具和提示词
agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o"),
    tools=[my_custom_tool, another_tool],
    system_prompt="You are a senior software engineer specializing in Python.",
)

# 流式输出
for chunk in agent.stream({
    "messages": [{"role": "user", "content": "Refactor the code in src/"}]
}):
    print(chunk)

4.4 MCP 工具集成

DeepAgents 通过 langchain-mcp-adapters 支持 MCP（Model Context Protocol）协议，可以直接接入任何 MCP 兼容的工具服务器：

from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agent

async with MultiServerMCPClient({
    "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
}) as mcp_client:
    agent = create_deep_agent(tools=mcp_client.get_tools())
    result = await agent.ainvoke({"messages": [...]})

---

五、CLI 工具：终端里的 Claude Code 替代品

DeepAgents 不只是一个 Python SDK，它还提供了一个功能完整的命令行工具（CLI），定位是"终端里的 AI 编程助手"。

5.1 安装 CLI

curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/libs/cli/scripts/install.sh | bash

5.2 CLI 核心功能

交互式 TUI（Terminal UI）：提供富文本终端界面，支持流式响应输出，让 Agent 的思考过程清晰可见。

网络搜索集成：CLI 内置了网络搜索能力，Agent 可以实时获取最新信息，不再局限于训练数据的截止日期。

无头模式（Headless Mode）：支持非交互式运行，可以集成到 CI/CD 流水线中：

# 在 CI 中自动运行代码审查
deepagents run --headless "Review the changes in the last commit and create a review.md"

人工审批（Human-in-the-loop）：对于高风险操作（如删除文件、执行危险命令），CLI 支持暂停并请求人工确认，确保关键操作不会意外执行。

持久记忆（Persistent Memory）：CLI 可以在会话之间保持记忆，记住用户的偏好、项目上下文和历史决策。

---

六、与同类项目的横向对比

6.1 DeepAgents vs Claude Code

维度	DeepAgents	Claude Code
开源	✅ MIT 开源	❌ 闭源
模型支持	任意支持工具调用的 LLM	仅 Claude
可定制性	高（可替换任何组件）	低
开箱即用	✅	✅
生态集成	LangChain 生态	Anthropic 生态
企业部署	灵活（本地/云端）	依赖 Anthropic API

DeepAgents 的最大优势是模型无关性——你可以用 GPT-4o、Gemini、Qwen、DeepSeek，甚至本地运行的 Llama，只要模型支持工具调用即可。这对于有数据隐私要求或成本控制需求的企业来说，是决定性的优势。

6.2 DeepAgents vs AutoGen

AutoGen 是微软推出的多 Agent 框架，同样支持 Agent 间的协作。两者的主要区别：

• AutoGen 更侧重于多 Agent 对话和协作模式，适合需要多个专业 Agent 协同工作的场景
• DeepAgents 更侧重于单个强大 Agent 的能力扩展，通过子 Agent 机制处理复杂任务

对于大多数实际应用场景，DeepAgents 的方案更简单直接；对于需要复杂 Agent 社会的场景，AutoGen 可能更合适。

6.3 DeepAgents vs deer-flow（字节跳动）

本周同样在 Trending 的 deer-flow 是字节跳动推出的 SuperAgent 框架。两者定位有所不同：

• deer-flow 更像一个完整的 Agent 操作系统，内置了沙箱、记忆、技能等完整基础设施
• DeepAgents 更轻量，专注于 Agent 核心能力，通过 LangChain 生态扩展

如果你已经在使用 LangChain/LangGraph，DeepAgents 是最自然的升级路径；如果你需要一个完整的 Agent 平台，deer-flow 可能更合适。

---

七、技术架构深度解析

7.1 基于 LangGraph 的状态机

DeepAgents 的核心是一个 LangGraph 状态机。create_deep_agent() 返回的是一个编译好的 LangGraph 图（Graph），这意味着你可以使用所有 LangGraph 的高级功能：

# 流式输出（支持 token 级别的流式）
async for event in agent.astream_events({"messages": [...]}, version="v2"):
    if event["event"] == "on_chat_model_stream":
        print(event["data"]["chunk"].content, end="", flush=True)

# 使用检查点（Checkpointing）实现持久化
from langgraph.checkpoint.sqlite import SqliteSaver

with SqliteSaver.from_conn_string("agent_state.db") as checkpointer:
    agent = create_deep_agent(checkpointer=checkpointer)
    
    # 第一次运行
    config = {"configurable": {"thread_id": "session-001"}}
    result = agent.invoke({"messages": [...]}, config=config)
    
    # 恢复会话（从上次中断的地方继续）
    result = agent.invoke({"messages": [new_message]}, config=config)

7.2 工具调用循环

DeepAgents 的执行循环遵循标准的 ReAct 模式，但加入了更多的智能优化：

用户输入
    ↓
LLM 思考（生成工具调用计划）
    ↓
工具执行（并行或串行）
    ↓
结果处理（大输出自动文件化）
    ↓
上下文检查（是否需要摘要压缩）
    ↓
继续思考 or 返回最终结果

7.3 子 Agent 的隔离机制

子 Agent 的上下文隔离是通过 LangGraph 的子图（Subgraph）机制实现的。每个子 Agent 是一个独立的 LangGraph 图实例，拥有独立的状态和上下文窗口。

主 Agent 通过 task 工具调用子 Agent 时，会传入：

• 任务描述
• 必要的上下文信息（文件路径、关键变量等）
• 期望的输出格式

子 Agent 完成任务后，将结果摘要返回给主 Agent，而不是返回完整的执行历史。这种设计既保证了信息传递的完整性，又避免了上下文污染。

---

八、实际应用场景

8.1 代码库分析与重构

agent = create_deep_agent(
    system_prompt="You are a senior software architect. Analyze code quality and suggest improvements."
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": """
        Analyze the codebase in ./src:
        1. Identify code smells and anti-patterns
        2. Check for security vulnerabilities
        3. Suggest refactoring opportunities
        4. Write a detailed report to analysis_report.md
        """
    }]
})

8.2 自动化研究报告生成

agent = create_deep_agent(
    tools=[web_search_tool, arxiv_tool],  # 添加搜索工具
    system_prompt="You are a research analyst specializing in AI/ML."
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Research the latest developments in multimodal LLMs and write a comprehensive report"
    }]
})

8.3 DevOps 自动化

agent = create_deep_agent(
    system_prompt="You are a DevOps engineer. Help automate infrastructure tasks."
)

# Agent 可以读取配置文件、执行命令、修改脚本
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Set up a CI/CD pipeline for this Python project"
    }]
})

---

九、生产部署注意事项

9.1 安全配置

DeepAgents 的"信任 LLM"哲学意味着你需要在工具层做好安全防护：

from deepagents import create_deep_agent
from deepagents.tools import create_sandbox_executor

# 使用沙箱化的 Shell 执行器
sandbox_executor = create_sandbox_executor(
    allowed_commands=["python", "pip", "git"],
    working_directory="/workspace",
    network_access=False  # 禁止网络访问
)

agent = create_deep_agent(
    tools=[sandbox_executor],
    # 禁用默认的 Shell 工具
    disable_default_tools=["execute"]
)

9.2 成本控制

子 Agent 机制虽然强大，但每个子 Agent 都会消耗独立的 token。建议：

1. 为子 Agent 设置 token 预算限制
2. 使用更便宜的模型处理简单子任务
3. 启用缓存机制避免重复计算

agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o"),
    subagent_model=init_chat_model("openai:gpt-4o-mini"),  # 子 Agent 用更便宜的模型
    max_tokens_per_subagent=10000,
)

9.3 可观测性

DeepAgents 与 LangSmith 深度集成，可以追踪每一次工具调用、每一个子 Agent 的执行过程：

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY=your_api_key

启用后，所有 Agent 的执行轨迹都会自动上传到 LangSmith，方便调试和性能优化。

---

十、社区与生态

DeepAgents 作为 LangChain 官方项目，天然继承了 LangChain 庞大的生态系统：

• 16,000+ 集成：LangChain 生态中的所有工具、模型、向量数据库都可以直接使用
• LangSmith：企业级的 Agent 可观测性平台
• LangGraph Studio：可视化的 Agent 调试工具
• LangGraph Cloud：托管的 Agent 运行环境

项目目前在 GitHub 上有 16,738 颗 Star，本周新增 5,498 颗，增长势头强劲。社区活跃度高，Issues 响应速度快，文档质量优秀。

---

十一、总结与展望

DeepAgents 代表了 AI Agent 开发的一个重要趋势：从"搭积木"到"拎包入住"。

它不是要取代 LangGraph 或其他底层框架，而是在这些框架之上提供一个更高层次的抽象，让开发者可以专注于业务逻辑，而不是 Agent 基础设施。

对于不同类型的开发者，DeepAgents 的价值各有侧重：

• 初学者：最快的 Agent 入门路径，5 分钟内跑起来第一个 Agent
• 中级开发者：省去大量样板代码，专注于业务逻辑定制
• 高级开发者：完整的 LangGraph 能力 + 开箱即用的最佳实践，快速构建生产级 Agent

随着 LLM 能力的持续提升，Agent 框架的竞争将越来越集中在"易用性"和"可靠性"上。DeepAgents 在这两个维度上都做出了清晰的取舍和优化，值得持续关注。

如果你正在考虑构建 AI Agent 应用，DeepAgents 是 2026 年最值得尝试的开源项目之一。

---

参考资料

• GitHub 仓库
• 官方文档
• API 参考
• LangChain 论坛
• LangSmith 可观测性平台

---

本文发布于 2026-03-23，基于 DeepAgents 最新版本撰写。项目仍在快速迭代中，建议以官方文档为准。