deepagents Getting Started

整理日期：2026-03-23 仓库地址：https://github.com/langchain-ai/deepagents

项目简介

deepagents 是 LangChain 官方出品的**"batteries-included" Agent 框架**——开箱即用的生产级 AI Agent。

定位： 直接对标 Claude Code，README 明确声明"primarily inspired by Claude Code"，目标是做出同类通用性更强的开源版本。本质是基于 LangGraph 构建的、带完整工具链的代码助手/任务 Agent 框架。

三大产品形态：

Python SDK (deepagents) — create_deep_agent() 一行代码创建 Agent
CLI (deepagents-cli) — 终端交互式 coding agent，类 Claude Code
ACP Server (deepagents-acp) — 通过 Agent Client Protocol 接入各种 AI IDE（如 Claude Code 客户端）

项目结构

deepagents/
├── libs/
│   ├── deepagents/              # 核心 SDK
│   │   └── deepagents/
│   │       ├── graph.py         # create_deep_agent() 主入口
│   │       ├── _models.py       # 模型解析工具
│   │       ├── backends/        # 文件/执行后端（Filesystem/State/LocalShell/Sandbox）
│   │       └── middleware/      # 中间件层（功能扩展点）
│   │           ├── filesystem.py       # 文件工具（read/write/edit/ls/glob/grep）
│   │           ├── subagents.py        # 同步 subagent（task 工具）
│   │           ├── async_subagents.py  # 异步 subagent（后台任务）
│   │           ├── summarization.py    # 上下文自动摘要
│   │           ├── memory.py           # 持久化 memory（AGENTS.md）
│   │           ├── skills.py           # 技能/工具加载
│   │           └── patch_tool_calls.py # Tool Call 修正中间件
│   │
│   ├── cli/                     # CLI 命令行工具
│   │   └── deepagents_cli/
│   │       ├── main.py          # CLI 入口点
│   │       ├── app.py           # Textual TUI App
│   │       ├── agent.py         # CLI Agent 创建（create_cli_agent）
│   │       ├── tools.py         # CLI 特有工具（web_search/fetch_url）
│   │       ├── server.py        # 本地 LangGraph 服务器
│   │       ├── mcp_tools.py     # MCP 协议集成
│   │       ├── ask_user.py      # Human-in-the-Loop 工具
│   │       └── subagents.py     # subagents.yaml 解析
│   │
│   ├── acp/                     # ACP 协议服务器
│   │   └── deepagents_acp/
│   │       └── server.py        # AgentServerACP（桥接 ACP 协议↔LangGraph）
│   │
│   ├── evals/                   # 评测框架
│   └── partners/                # 合作方沙箱集成
│       ├── daytona/             # Daytona 沙箱
│       ├── modal/               # Modal 远程执行
│       ├── quickjs/             # QuickJS 沙箱
│       └── runloop/             # Runloop 沙箱
│
└── examples/
    ├── deep_research/           # 深度研究 Agent
    ├── content-builder-agent/   # 内容生成 Agent
    ├── nvidia_deep_agent/       # NVIDIA API 集成 Agent
    ├── ralph_mode/              # Ralph Mode（扩展示例）
    └── text-to-sql-agent/       # Text-to-SQL Agent

核心架构

┌──────────────────────────────────────────────────────────────────────┐
│  用户 / IDE / Claude Code 客户端                                      │
└─────┬─────────────┬──────────────────────┬──────────────────────────┘
      │             │                      │
      ▼             ▼                      ▼
  Python SDK      CLI (TUI)            ACP Server
  直接调用         终端交互              ACP 协议接入
      │             │                      │
      └─────────────┴──────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────────────────────────────┐
│  create_deep_agent()  ←  graph.py 核心工厂                           │
│                                                                      │
│  中间件栈（Middleware Stack）：                                        │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │  TodoListMiddleware       ← write_todos 任务规划              │   │
│  │  FilesystemMiddleware     ← read/write/edit/ls/glob/grep      │   │
│  │  SubAgentMiddleware       ← task（同步 subagent 委派）         │   │
│  │  AsyncSubAgentMiddleware  ← 后台异步 subagent（LangSmith 部署）│   │
│  │  SummarizationMiddleware  ← 上下文过长时自动摘要               │   │
│  │  PatchToolCallsMiddleware ← Tool Call 格式修正                 │   │
│  │  SkillsMiddleware         ← 自定义技能加载                     │   │
│  │  MemoryMiddleware         ← AGENTS.md 持久化 memory           │   │
│  │  AnthropicCachingMiddleware ← Anthropic prompt cache 优化      │   │
│  │  HumanInTheLoopMiddleware ← interrupt_on 配置的 HITL 审批      │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                    │                                                  │
│                    ▼                                                  │
│         langchain.create_agent()  →  LangGraph CompiledStateGraph    │
│                                                                      │
│  Backend（文件/执行后端）：                                            │
│  ┌─────────────────────────────────────────────┐                    │
│  │ StateBackend     ← 内存（默认，测试用）       │                    │
│  │ FilesystemBackend ← 本地磁盘                  │                    │
│  │ LocalShellBackend ← 本地 shell + 文件系统     │                    │
│  │ CompositeBackend  ← 路由（不同路径→不同后端） │                    │
│  │ SandboxBackend   ← Modal/Daytona/Runloop 等  │                    │
│  └─────────────────────────────────────────────┘                    │
└──────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
         LLM（Claude Sonnet 4.6 默认，支持任意 tool-calling 模型）

核心工作流程

1. Agent 初始化（`create_deep_agent`）

python

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[my_tool],
    system_prompt="You are a research assistant.",
    interrupt_on={"edit_file": True},   # 编辑文件前暂停等待人工确认
    checkpointer=MemorySaver(),          # 持久化对话状态
)

内部流程：

解析 model（string → BaseChatModel，OpenAI 默认用 Responses API）
为 general-purpose subagent 构建中间件栈
处理 subagents 列表（SubAgent / CompiledSubAgent / AsyncSubAgent 三种类型）
构建主 Agent 中间件栈
拼接 system_prompt（用户自定义 + BASE_AGENT_PROMPT）
调用 langchain.create_agent() → 返回 LangGraph CompiledStateGraph

2. 请求处理（Agent Invoke）

python

result = agent.invoke({
    "messages": [{"role": "user", "content": "Research LangGraph and write a summary"}]
})

流程：

用户消息 → LangGraph 图执行
  → 中间件注入工具到 LLM context
  → LLM 调用 write_todos（规划任务）
  → LLM 调用 read_file / glob / grep（读取代码/文件）
  → LLM 调用 execute（运行命令）
  → LLM 调用 task（委派给 subagent）
  → 上下文过长时 SummarizationMiddleware 自动摘要
  → HITL interrupt_on 触发时暂停等待用户决策
  → 任务完成返回最终结果

3. Subagent 机制

同步 SubAgent（task 工具）：

主 Agent 通过 task(description, subagent_type) 委派任务
subagent 在独立上下文窗口中运行，防止上下文污染
可通过 subagents.yaml 或 Python 代码定义

异步 SubAgent（后台任务）：

针对 LangSmith 上部署的远程 LangGraph Agent
主 Agent 可 launch_async_subagent 启动后台任务，继续做其他事
通过 check_async_subagent 查询状态，cancel_async_subagent 取消

4. ACP Server（供 IDE 接入）

AgentServerACP 实现 ACP 协议，把 Deep Agent 暴露给任何支持 ACP 的 IDE：

流式推送 tool call 状态（read/edit/execute 等类型可视化）
Todo list → Plan 可视化（write_todos → AgentPlanUpdate）
HITL 权限请求（approve/reject/always allow）
支持会话模式切换（mode 对应不同 Agent 配置）

部署步骤

方法一：SDK（Python）

bash

pip install deepagents
# 或
uv add deepagents

python

from deepagents import create_deep_agent

# 最简用法（默认 claude-sonnet-4-6，需设 ANTHROPIC_API_KEY）
agent = create_deep_agent()
result = agent.invoke({
    "messages": [{"role": "user", "content": "List files in /tmp"}]
})

# 自定义模型
from langchain.chat_models import init_chat_model
agent = create_deep_agent(
    model=init_chat_model("openai:gpt-5"),
    tools=[my_tool],
    system_prompt="You are a helpful assistant.",
)

方法二：CLI（命令行 coding agent）

bash

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

# 启动
deepagents

# 非交互模式（CI/脚本）
deepagents --no-interactive --prompt "Add tests for all functions in src/"

# 指定模型
deepagents --model openai:gpt-5

方法三：ACP Server（供 IDE 接入）

bash

pip install deepagents-acp

# 启动 ACP server（可被 Claude Code 等 ACP 客户端连接）
python -m deepagents_acp

Demo 示例

0. 实际运行记录（dev-server，2026-03-23，pyenv Python 3.12.12）

任务设计：用经典编程任务验证 agent 的完整能力链路——规划 → 写文件 → 执行 shell → 自主容错

任务 prompt:
1. Create a file called fib.py with a fibonacci function (both recursive and iterative versions)
2. Create a file called test_fib.py that tests both versions
3. Run the tests and show me the results

Agent 实际执行过程（Claude Sonnet 4.6）

Sonnet 4.6 遇到 Permission denied 后，主动先用 execute 探测工作目录，再切换为绝对路径，一次成功：

⚙️  call [write_todos]: 拆解任务，标记第 1 项 in_progress
📤 result: Updated todo list

⚙️  call [write_file]: {'file_path': '/fib.py', ...}
📤 result: Error writing file '/fib.py': [Errno 13] Permission denied

⚙️  call [execute]: {'command': 'echo $HOME && pwd'}
📤 result: /home/ubuntu
           /tmp/deepagents-sandbox          ← 确认了实际工作目录

⚙️  call [write_file]: {'file_path': '/tmp/deepagents-sandbox/fib.py', ...}
📤 result: Updated file /tmp/deepagents-sandbox/fib.py  ✅

⚙️  call [write_todos]: 标记第 1 项 completed，第 2 项 in_progress
⚙️  call [write_file]: {'file_path': '/tmp/deepagents-sandbox/test_fib.py', ...}
📤 result: Updated file /tmp/deepagents-sandbox/test_fib.py  ✅

⚙️  call [write_todos]: 标记第 2 项 completed，第 3 项 in_progress
⚙️  call [execute]: {'command': 'cd /tmp/deepagents-sandbox && python -m pytest test_fib.py -v'}
📤 result: platform linux -- Python 3.12.12, pytest-9.0.2
           45 passed ✅

⚙️  call [write_todos]: 标记第 3 项 completed
🤖 **45/45 tests passed.**

Haiku vs Sonnet 4.6 对比

	Claude 3.5 Haiku	Claude Sonnet 4.6
任务规划	无 todo 追踪	先拆解 todo，逐项标记进度
遇到权限错误	重试同样路径两次再切 shell	先探测工作目录，一次切换成功
写文件方式	用 shell `cat > file` 写入	直接用 `write_file` 绝对路径
测试工具	无 pytest → 降级 unittest	直接用 pytest，环境感知更强
测试数量	2 tests	45 tests（更全面）

1. 基础用法

python

from deepagents import create_deep_agent

agent = create_deep_agent()

# 流式输出
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "Write a Python fibonacci function"}]},
    stream_mode="messages"
):
    print(chunk)

2. 带 HITL 的 Agent

python

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    interrupt_on={
        "execute": True,   # 执行命令前等待确认
        "edit_file": True, # 编辑文件前等待确认
    },
    checkpointer=MemorySaver(),
)

config = {"configurable": {"thread_id": "session-1"}}

# 第一次调用，执行会在 execute 工具处暂停
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Run ls -la"}]},
    config=config
)

# 恢复执行（批准）
agent.invoke(
    {"type": "approve"},
    config=config
)

3. 自定义 Subagent（通过 subagents.yaml）

yaml

# ~/.deepagents/agent/subagents.yaml
subagents:
  - name: researcher
    description: "Specialized in web research and summarization"
    system_prompt: "You are a research specialist..."
    model: openai:gpt-5

踩坑记录

坑 1：Python 版本

问题：直接用系统 python3（3.10），deepagents 要求 3.11+
正确做法：eval "$(pyenv init -)" && pyenv shell 3.12.12

坑 2：Bedrock 模型 Legacy

问题：us.anthropic.claude-3-5-sonnet-20241022-v2:0 报 "Legacy / not used in 15 days"
原因：Bedrock 会把超过 15 天没调用的模型标为 Legacy，与 IAM 权限无关
解决：用最新跨区域 inference profile：us.anthropic.claude-sonnet-4-6

坑 3：FilesystemMiddleware 不接受 sandbox_dir 参数

问题：FilesystemMiddleware(sandbox_dir=...) → TypeError: unexpected keyword argument

解决：sandbox 通过 backend 参数传入，不是 middleware 的参数

python

# 错误
FilesystemMiddleware(sandbox_dir="/tmp/sandbox")
# 正确
create_deep_agent(backend=LocalShellBackend(root_dir="/tmp/sandbox"))

坑 4：重复 middleware

问题：手动传 middleware=[FilesystemMiddleware(...)] → "Please remove duplicate middleware instances"
原因：create_deep_agent 默认已包含完整 middleware 栈
解决：通过顶层参数（backend、model、tools）定制，不要手动传默认已有的 middleware

坑 5：LocalShellBackend 参数名

问题：LocalShellBackend(cwd=...) → TypeError: unexpected keyword argument 'cwd'
正确参数：root_dir（工作目录），inherit_env=True，virtual_mode=False

坑 6：write_file 路径问题

现象：agent 调 write_file('/fib.py', ...) 报 Permission denied
原因：virtual_mode=False 时路径按字面解析，/fib.py 是根目录
Agent 自动处理：失败后自动切换到 execute 用 shell 写文件
建议：用 virtual_mode=True，此时 /fib.py 映射到 {root_dir}/fib.py

坑 7：stream 输出中 node_output 可能为 None

解决：加判断 if node_name == "__end__" or node_output is None: continue

坑 8：messages 可能是 Overwrite 对象

问题：for msg in messages → TypeError: 'Overwrite' object is not iterable
解决：if hasattr(msgs, "__iter__") and not isinstance(msgs, str): msg_list = list(msgs)

关键结论

1. 中间件架构是最大亮点

不同于 CrewAI/AutoGen 等框架，deepagents 使用中间件栈而非继承/装饰器模式扩展 Agent。每个 Middleware 向 Agent 注入工具、修改 state、或 wrap LLM 调用。这让功能组合非常灵活，任意启停单个能力，且各 Middleware 之间解耦。

2. Backend 抽象解决了"在哪执行"问题

同一套 Agent 代码可以跑在：本地 shell、本地文件系统、Modal/Daytona/Runloop 远程沙箱。切换只需替换 backend 参数，Agent 逻辑完全不变。这是 Claude Code 等工具的核心痛点——deepagents 用 Backend 协议优雅解决了。

3. ACP 协议是战略核心

deepagents-acp 让 deepagents 可以作为后端接入任何 ACP 兼容的前端（包括 Claude Code 的客户端 UI）。LangChain 在押注 ACP 成为 AI Agent 通信的通用协议，类似 LSP 之于编辑器。

4. "Trust the LLM" 安全模型

明确拒绝"靠模型自律"的安全策略。系统依赖工具/沙箱层面的边界（interrupt_on HITL 审批 + sandbox isolation），不期望 LLM 自我节制。这和大多数生产级 Agent 框架的趋势一致。

5. 与 Claude Code 的核心区别

特性	Claude Code	deepagents
模型	仅 Anthropic	任意 tool-calling LLM
开源	否	MIT 全开源
扩展性	有限	Middleware 完全可组合
Sandbox	无原生支持	Modal/Daytona/Runloop 等
协议	专有	ACP 开放协议

下次可以试的方向

[ ] 用 SubAgentMiddleware 跑多 agent 协作任务
[ ] 接入 MCP 工具（通过 langchain-mcp-adapters）
[ ] 用 checkpointer 实现任务暂停/恢复
[ ] 跑 deepagents CLI，看 TUI 界面（类 Claude Code 的终端体验）
[ ] 用 interrupt_on 实现 human-in-the-loop 审批流

参考资源

GitHub: https://github.com/langchain-ai/deepagents
官方文档: https://docs.langchain.com/oss/python/deepagents/overview
API 参考: https://reference.langchain.com/python/deepagents/
ACP 协议: https://agentclientprotocol.com/protocol/overview
JS/TS 版本: https://github.com/langchain-ai/deepagentsjs
LangSmith: https://docs.langchain.com/langsmith/home

deepagents Getting Started ​

项目简介 ​

项目结构 ​

核心架构 ​

核心工作流程 ​

1. Agent 初始化（create_deep_agent） ​

2. 请求处理（Agent Invoke） ​

3. Subagent 机制 ​

4. ACP Server（供 IDE 接入） ​

部署步骤 ​

方法一：SDK（Python） ​

方法二：CLI（命令行 coding agent） ​

方法三：ACP Server（供 IDE 接入） ​

Demo 示例 ​

0. 实际运行记录（dev-server，2026-03-23，pyenv Python 3.12.12） ​

Agent 实际执行过程（Claude Sonnet 4.6） ​

Haiku vs Sonnet 4.6 对比 ​

1. 基础用法 ​

2. 带 HITL 的 Agent ​

3. 自定义 Subagent（通过 subagents.yaml） ​

踩坑记录 ​

坑 1：Python 版本 ​

坑 2：Bedrock 模型 Legacy ​

坑 3：FilesystemMiddleware 不接受 sandbox_dir 参数 ​

坑 4：重复 middleware ​

坑 5：LocalShellBackend 参数名 ​

坑 6：write_file 路径问题 ​

坑 7：stream 输出中 node_output 可能为 None ​

坑 8：messages 可能是 Overwrite 对象 ​

关键结论 ​

1. 中间件架构是最大亮点 ​

2. Backend 抽象解决了"在哪执行"问题 ​

3. ACP 协议是战略核心 ​

4. "Trust the LLM" 安全模型 ​

5. 与 Claude Code 的核心区别 ​

下次可以试的方向 ​

参考资源 ​

deepagents Getting Started

项目简介

项目结构

核心架构

核心工作流程

1. Agent 初始化（`create_deep_agent`）

2. 请求处理（Agent Invoke）

3. Subagent 机制

4. ACP Server（供 IDE 接入）

部署步骤

方法一：SDK（Python）

方法二：CLI（命令行 coding agent）

方法三：ACP Server（供 IDE 接入）

Demo 示例

0. 实际运行记录（dev-server，2026-03-23，pyenv Python 3.12.12）

Agent 实际执行过程（Claude Sonnet 4.6）

Haiku vs Sonnet 4.6 对比

1. 基础用法

2. 带 HITL 的 Agent

3. 自定义 Subagent（通过 subagents.yaml）

踩坑记录

坑 1：Python 版本

坑 2：Bedrock 模型 Legacy

坑 3：FilesystemMiddleware 不接受 sandbox_dir 参数

坑 4：重复 middleware

坑 5：LocalShellBackend 参数名

坑 6：write_file 路径问题

坑 7：stream 输出中 node_output 可能为 None

坑 8：messages 可能是 Overwrite 对象

关键结论

1. 中间件架构是最大亮点

2. Backend 抽象解决了"在哪执行"问题

3. ACP 协议是战略核心

4. "Trust the LLM" 安全模型

5. 与 Claude Code 的核心区别

下次可以试的方向

参考资源