Deep Agents SDK 实战指南：基于 create_deep_agent 构建可定制、可投产的 Agent 框架-平芜编程栈

Deep Agents SDK 实战指南：基于 create_deep_agent 构建可定制、可投产的 Agent 框架

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

Deep Agents 是 LangChain 团队开源的“batteries-included”Agent 框架（agent harness）：它在 LangGraph 之上预置了文件系统、子代理委派、上下文管理、技能（Skills）、记忆与人机协同审批等能力，开箱即跑，同时允许你在不 fork 仓库的前提下覆盖或替换其中任何一块。本文以 libs/deepagents/README.md 为主线，结合 pyproject.toml 的依赖约束与 graph.py 的装配源码，完整讲解如何安装、配置、扩展并最终将 Deep Agents 投入生产。

一、定位：它是 LangGraph 生态里最“有主见”的一层

README 对 Deep Agents 的定义是：an open source agent harness — an opinionated agent that runs out of the box. Extend, override, or replace any piece.官方给出四条设计原则：

Opinionated（有主见）：默认配置面向长周期、多步骤任务调优；
Extensible（可扩展）：无需 fork 即可覆盖或替换任意组件；
Model-agnostic（模型无关）：任何支持 tool calling 的模型都可以驱动，包括前沿 API、开源权重的托管服务和本地模型；
Production-ready（生产就绪）：构建在 LangGraph 之上，天然具备流式、持久化与 checkpointing 能力，并可经 LangSmith 获得追踪、评估与部署支持。

README 的 FAQ 明确了它与 LangGraph、LangChain 三者的层次关系，这也是选型时的核心依据：

层次	定位	适用场景
LangGraph	图运行时（graph runtime）	Agent 循环本身不是合适的形态，需要自定义图结构时
LangChain 的`create_agent`	图运行时之上的最小 agent harness	想要更轻的 harness，不要捆绑的中间件时
Deep Agents	`create_agent`之上更 opinionated 的 harness	想要规划、上下文管理、委派等能力开箱即用

三者是同一技术栈中的可组合层次：任何 LangGraph 的CompiledStateGraph都可以作为子代理传入 Deep Agent，让自定义编排与框架默认行为并行工作。README 同时说明，该项目的灵感主要来自 Claude Code——最初就是为研究“是什么让 Claude Code 具备通用性”而发起的尝试。

二、安装与工程基线

README 给出的安装方式一行即可：

uv add deepagents

结合 pyproject.toml 可以确认当前工程的基线事实：

版本与许可：当前版本0.7.13，MIT 许可，Python 要求>=3.11,<4.0（classifiers 覆盖 3.11–3.14）；
核心依赖：langchain>=1.4.0,<2.0.0、langchain-core>=1.6.2,<2.0.0、langchain-anthropic、langchain-google-genai、langsmith、packaging、wcmatch>=11.0；
可选依赖组（extras）：
- aws：langchain-aws（Bedrock 支持）；
- quickjs：langchain-quickjs（QuickJS 脚本执行后端）；
- video：av+pillow（视频抽帧读取支持）。
测试体系：[tool.pytest.ini_options]中默认通过-m 'not benchmark'跳过墙钟基准测试，并将未预期警告提升为错误（warnings as errors），依赖pytest-xdist、pytest-timeout、pytest-socket（断网测试）等；lint 使用 ruff 全量规则集（select = ["ALL"]）配合少量忽略项。

仓库内运行测试与代码检查可直接参考 libs/deepagents/Makefile，测试目录约定见 libs/deepagents/tests/README.md。

三、最小示例与 create_deep_agent 参数全景

README 的最小示例：

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 and write a summary"})

这个 agent 可以规划、读写文件并自主管理上下文。create_deep_agent的完整签名与参数文档见 graph.py，默认构建的 agent 自带以下工具：

ls、read_file、write_file、edit_file、glob、grep：文件操作；
execute：在沙箱中运行 shell 命令（仅当 backend 实现了SandboxBackendProtocol，否则返回错误信息）；
task：调用子代理。

3.1 关键参数速查

参数	类型/取值	说明
`model`	`str`或`BaseChatModel`	接受`provider:model`字符串（如`"openai:gpt-5.5"`）或已初始化的模型实例。`model=None`（默认走`claude-sonnet-4-6`）自`0.5.3`起弃用，将在`1.0.0`移除
`tools`	工具序列	与内置工具合并，永不覆盖内置项。若要隐藏某个内置工具，需在`HarnessProfile`里配`excluded_tools`，或传入自定义`FilesystemMiddleware(tools=[...])`
`system_prompt`	`str`或`SystemMessage`	调用者撰写的系统指令，位于最终 system prompt 最前；组装顺序为`USER -> BASE -> SUFFIX`。传`SystemMessage`可保留`cache_control`标记（用于 Anthropic 显式 prompt cache 断点）
`middleware`	`AgentMiddleware`序列	插入在核心栈之后、尾部栈之前；同名中间件原位替换
`subagents`	`SubAgent`/`CompiledSubAgent`/`AsyncSubAgent`	三类子代理规格，见下文
`skills`	路径列表（如`["/skills/user/", "/skills/project/"]`）	必须用 POSIX 斜杠，相对 backend 根目录；默认`StateBackend`时通过`invoke(files={...})`提供技能文件；同名技能后者覆盖前者
`memory`	路径列表（`AGENTS.md`文件）	启动时加载进 system prompt，实现跨会话记忆
`permissions`	`FilesystemPermission`规则列表	按声明顺序求值，首个匹配生效，无匹配则放行；`mode`支持`allow`/`deny`/`interrupt`
`backend`	`BackendProtocol`实例	文件存储与执行后端，默认`StateBackend()`
`interrupt_on`	工具名到审批配置的映射	如`{"edit_file": True}`表示每次编辑前暂停等待人工
`response_format`/`state_schema`/`context_schema`/`checkpointer`/`store`/`debug`/`name`/`cache`	—	直通底层`create_agent`；`state_schema`必须是`DeepAgentState`子类以保留`messages`上的`DeltaChannel`reducer

3.2 模型字符串如何被解析

传字符串模型时，内部走 resolve_model：它调用langchain.chat_models.init_chat_model，并叠加ProviderProfile注册表中登记的 provider 级初始化行为（如 NVIDIA NIM 与 OpenRouter 的归属头、OpenAI 默认走 Responses API）。两个与 README FAQ 呼应的细节值得注意：

OpenAI 数据留存：openai:模型默认走 Responses API；如需 chat completions 或关闭留存，需自行init_chat_model("openai:...", use_responses_api=False)（或store=False）后传入实例；
开源权重与本地模型：任何支持 tool calling 的模型均可——前沿 API、Baseten/Fireworks 托管的开源模型，以及经 Ollama、vLLM、llama.cpp 自托管的模型，均可通过任意 LangChain chat model 接入。

3.3 底层状态与图装配

从源码结构看，框架在生产侧有两个值得了解的设计：

检查点增长优化：DeepAgentState 在messages上使用DeltaChannel(_messages_delta_reducer, snapshot_frequency=50)，把 checkpoint 体积增长从 O(N²) 降到 O(N)——长会话场景下这直接影响持久化成本；
递归上限与元数据：最终通过create_agent(...)装配后附加recursion_limit=9999及ls_integration="deepagents"等追踪元数据（见 graph.py），为 LangSmith 侧的集成识别与长任务执行留足余量。

四、内置能力逐项拆解

README 的 Features 列表（子代理、文件系统、上下文管理、Shell、持久记忆、人机协同、Skills、工具/MCP）在源码中分别对应明确的模块，下面按“README 声明 -> 源码位置 -> 用法要点”展开。

4.1 子代理：隔离上下文的委派机制

subagents参数支持三种形态（见 graph.py 参数文档）：

SubAgent：声明式同步子代理，经task工具调用；需提供name、description，可选覆盖system_prompt、tools、model、middleware、interrupt_on、skills、permissions、response_format；
CompiledSubAgent：预编译的 runnable，同样经task暴露，但不接受声明式 prompt/工具配置；
AsyncSubAgent：远程/后台子代理（按graph_id识别，可带url/headers），路由到AsyncSubAgentMiddleware，以非阻塞后台任务方式运行，并提供启动、查询、更新、取消、列表等异步任务工具。

两个默认行为要点：

general-purpose 兜底子代理：若未提供名为general-purpose的子代理，框架会自动注入一个默认同步子代理（除非通过 harness profile 的GeneralPurposeSubagentProfile(enabled=False)禁用）。若既未传入任何同步子代理、默认又被禁用，则task工具完全不暴露；
fork 模式（实验性）：mode="fork"的子代理延续父代理的对话并从继承状态重建 system prompt，而非隔离启动；其自身system_prompt只是附加段，且不能定义skills。该能力于 0.7.12 引入（见 CHANGELOG）。

SubAgent的继承规则也很明确：interrupt_on默认继承顶层配置，子代理自带配置则整体覆盖；permissions同理（自带规则整体替换父级）；CompiledSubAgent与远程AsyncSubAgent均不继承顶层interrupt_on，审批须配置在其内部。

4.2 文件系统与可插拔后端

“read, write, edit, or search over pluggable local, sandboxed, or remote backends” 由 backends 包落地，导出的后端包括：

后端	特点
`StateBackend`	默认后端；文件存于 agent 状态中，通过`invoke(files={...})`提供初始文件
`FilesystemBackend`	从磁盘按`root_dir`读取
`LocalShellBackend`	本地 shell 执行；与`FilesystemBackend`自 0.7.0 起默认`virtual_mode=True`（路径锚定在`root_dir`下，`..`越界被拒绝，解析到`root_dir`之外的路径抛`ValueError`）
`StoreBackend`	基于 LangGraph`BaseStore`的持久存储（需要向 agent 传`store`）
`CompositeBackend`	组合多个后端并按路径路由
`ContextHubBackend`	远端 Context Hub 存储（0.7.7 起批量合并并发写入）
`LangSmithSandbox`	LangSmith 托管沙箱

execute工具是“shell access — run commands in your sandbox of choice” 的落点：只有当 backend 实现SandboxBackendProtocol时才可用，否则工具直接返回错误。0.7.0 起 agent 还会看到具备破坏性、可递归的delete工具（当后端支持时），且文件系统权限把delete归为写操作——允许对某路径写入的规则也授权递归删除该子树，除非有 narrower 的 deny/interrupt 规则覆盖（见 filesystem.py 中_DEFAULT_FS_TOOL_OPS的读写分类与 CHANGELOG 0.7.0 条目）。

4.3 上下文管理：摘要 + 卸载 + 补丁

对应 README 的 “summarize long threads and offload tool outputs to disk”：

SummarizationMiddleware：核心栈成员，基于当前模型与 backend 由create_summarization_middleware(model, backend)构建，负责长线程摘要与工具输出卸载到磁盘；
PatchToolCallsMiddleware：紧随其后，修复工具调用消息的一致性问题；
超大工具消息驱逐：middleware/_message_eviction.py定义了TOO_LARGE_TOOL_MSG等常量，过大的工具结果内容会被卸载，只保留内容预览。

4.4 持久记忆与 Skills

memory：memory=["/memory/AGENTS.md"]这类路径在启动时加载并注入 system prompt，显示名自动从路径派生；由MemoryMiddleware实现（位于栈尾，且在 prompt-caching 中间件之后，避免记忆更新使 Anthropic prompt cache 前缀失效——这一点在 graph.py 的注释中有明确说明）；
skills：可复用行为，按需加载。skills=["/skills/user/", "/skills/project/"]指向包含SKILL.md的技能源，由SkillsMiddleware构建；仓库内大量示例可直接参考examples/目录下各 agent 的skills/布局。

4.5 人机协同（HITL）与权限

两条配置通道最终都汇入HumanInTheLoopMiddleware：

interrupt_on：显式映射，如interrupt_on={"edit_file": True}在任何一次编辑前暂停，供人工批准、编辑或拒绝；
permissions：声明式规则，mode三选一——"allow"（默认放行）、"deny"（返回权限拒绝错误）、"interrupt"（经 HITL 暂停审批）。存在任意 interrupt 规则时框架自动安装HumanInTheLoopMiddleware，并把生成的interrupt_on条目与显式interrupt_on参数合并（同名工具以用户条目为准，合并逻辑见_merge_fs_interrupt_on）。

注意FilesystemMiddleware的权限在工具层执行而非 backend 层——直接调用 backend API 目前不走permissions检查。

五、中间件栈：不 fork 即可扩展的底层机制

“override or replace any piece without forking” 的落点是中间件栈的三段式装配（见 create_deep_agent 文档字符串）：

Base stack（基础栈）：SkillsMiddleware（提供skills时）→FilesystemMiddleware→SubAgentMiddleware（存在内联子代理时）→ 摘要中间件 →PatchToolCallsMiddleware→AsyncSubAgentMiddleware（提供异步子代理时）；
User middleware：你传入的middleware在此插入。同名中间件原位替换（保持栈序），新名字则插入到最后一个核心中间件之后、尾部栈之前；
Tail stack（尾部栈）：harness profile 的extra_middleware→ 工具排除中间件 → prompt caching 中间件（Anthropic 无条件挂、对非 Anthropic 模型 no-op；安装了langchain-aws/langchain-fireworks时分别挂 Bedrock/Fireworks 版本）→MemoryMiddleware（提供memory时）→HumanInTheLoopMiddleware（需要审批时）。

两条防护规则保证“可扩展”不以“可坏”为代价：

脚手架中间件受保护：_REQUIRED_MIDDLEWARE（graph.py）将FilesystemMiddleware（承载全部内置文件工具与权限安全保证）与SubAgentMiddleware（承载task工具处理器）列为不可排除项；profile 的excluded_middleware试图剔除它们时直接抛ValueError，而不是让 agent 静默降级；
排除必须“落空可查”：excluded_middleware中任何未匹配到已装配中间件的条目、私有下划线名字、或歧义名字都会触发ValueError，防止拼写错误导致静默失效。

System prompt 的组装顺序同样是确定性的：USER（你的system_prompt）→BASE（profile 的base_system_prompt）→SUFFIX（profile 的system_prompt_suffix），以空行分隔。0.7.0 起默认 BASE 为空（authored base prompt 被精简），BASE_AGENT_PROMPT已弃用但保留可导入（0.9.0 移除），需要旧行为时显式system_prompt=BASE_AGENT_PROMPT。

六、生产部署与选型 FAQ

README FAQ 对三个高频问题的回答可以浓缩为：

能用开源/本地模型吗？能。任何支持 tool calling 的模型均可，接入方式即任意 LangChain chat model 实例；
能上生产吗？能。Deep Agents 构建于 LangGraph 之上，为生产 agent 部署设计；配合 LangSmith 获得追踪、评估与监控（README 指向其 going-to-production 指南）；
何时不用它？想要更轻的 harness 用create_agent；agent 循环形态本身不合适时直接下探 LangGraph。三层可自由组合，CompiledStateGraph可作为子代理插回 Deep Agent。

从仓库结构看，生产配套能力是分层提供的：libs/下还有 acp（Agent Client Protocol 服务）、code（TUI 编码 agent）、talon（多渠道宿主）、partners（Daytona/Modal/QuickJS/Runloop/Vercel 等沙箱集成），libs/evals/提供统一评估体系——这些属于 Deep Agents 生态的扩展面，核心 SDK 用户可按需取用。

七、安全模型：trust the LLM

README 的安全章节给出了一条明确原则：Deep Agents 遵循 “trust the LLM” 模型——agent 能做其工具允许的一切，边界必须在工具/沙箱层强制，而不是指望模型自我约束。落实到工程上就是前文提到的组合拳：

选对后端：本地执行用LocalShellBackend/FilesystemBackend的virtual_mode（默认开启，路径锚定root_dir），远程执行用托管沙箱后端；
用permissions对敏感路径声明 deny/interrupt 规则；
用interrupt_on对高危工具（如edit_file、execute）设置人工审批点。

八、版本提示：0.7.x 的行为变化

以 CHANGELOG 为准的近期关键行为（影响存量代码升级）：

0.7.0：不再默认包含TodoListMiddleware/write_todos（需要时手动middleware=[TodoListMiddleware()]）；新增delete工具；write_file语义改为“缺失则创建、存在则整体替换”（不再有 file-exists 错误）；默认 system prompt 精简；
0.7.4：execute在 SDK artifacts 中暴露退出码；
0.7.6：摘要时将历史卸载到独立 session ID；
0.7.7：BackendProtocol.glob对裸模式改为递归；ContextHubBackend批量合并并发变更；
0.7.9：excluded_tools生效于执行排除；RubricMiddleware强制标准全覆盖；
0.7.12：SDK 新增子代理会话 fork；
0.7.13：SDK 子代理模式由handoff更名为isolated。

升级跨 0.7.0 时建议逐项核对上述破坏性变更清单。

九、仓库导航

入口	路径	用途
主入口与参数文档	libs/deepagents/deepagents/graph.py	`create_deep_agent`、`DeepAgentState`
公共 API 导出	libs/deepagents/deepagents/init.py	`SubAgent`、`FilesystemMiddleware`、`MemoryMiddleware`、`RubricMiddleware`、profile 注册等
后端实现	libs/deepagents/deepagents/backends/	`StateBackend`、`FilesystemBackend`、`LocalShellBackend`、`StoreBackend`、`CompositeBackend`、`LangSmithSandbox`
中间件实现	libs/deepagents/deepagents/middleware/	文件系统、子代理、技能、记忆、摘要、HITL 等
模型解析	libs/deepagents/deepagents/_models.py	`resolve_model`、provider 识别与归一化
版本记录	libs/deepagents/CHANGELOG.md	各版本破坏性变更与修复
测试	libs/deepagents/tests/	单元测试、集成测试与基准
示例 agents	examples/	deep research、text-to-sql、content builder 等可运行参考