跳到主要内容

数据截至 (上游 commit 25aa2735dabb)

Deep Agents — 架构与原理

30 秒导读: Deep Agents 是 LangChain 官方出的 batteries-included agent harness(开箱即用的 agent 外壳)。你给它一个模型、几个自己的工具、一句系统提示,它就还你一个已经会读写文件、跑 shell、拆子 agent、自己压缩上下文的 agent。它不发明新的运行时,只是把这些能力预装成一摞中间件,叠在 LangChain 的 create_agent() 上面。

引用约定: 本页所有 path:line 相对克隆根。libs/deepagents/deepagents/ 是 SDK 主包目录,libs/ARCHITECTURE.md、README.md 是仓库自带的上游文档。

1. 这是什么(零基础也能懂)​

一句话定义: Deep Agents 是一个有主张的 agent 外壳——把"长时间、多步骤任务的 agent 通常都要自己写一遍"的那套基础设施(计划、文件、子 agent、上下文管理),做成默认就有、又能逐件替换的默认值。

它解决什么问题。 想象你要让 AI 干一件跑一两个小时的活:读完一个大仓库、改十几个文件、边做边记笔记。自己从零搭,会依次撞上四堵墙:

撞到的墙具体表现本文档哪章给答案
上下文塞满几十次工具调用后历史超出窗口,模型开始失忆05
没有工作台模型没地方放中间产物,只能把一切塞回对话里02、03
主线被淹一次大搜索的结果污染主线程,后面全乱04
每次重写权限、审批、断点续跑这些"工程活"每个项目都要重造01、03

Deep Agents 就是把这四堵墙的答案预先打包好。

给谁用。 三类人各取所需:

你是谁你的处境该用哪层
想快速做一个能干长活的 agent不想自己写待办工具、文件工具、摘要逻辑Deep Agents
想要一个轻的 agent loop只要"模型 + 工具 + 循环",自带的中间件反而碍事LangChain create_agent()
agent loop 本身形状就不对要自定义图、并行分支、特殊状态流转LangGraph

这段取舍是 README 的 FAQ 明说的(README.md:85-89),不是推断。

它开箱能做什么。 只要调一次 create_deep_agent(),模型就已经看得见这几组工具——这份清单写在函数自己的 docstring 里(libs/deepagents/deepagents/graph.py:291-299):

工具干什么谁提供
ls / read_file / write_file / edit_file / glob / grep一整套文件操作FilesystemMiddleware
execute在沙箱里跑 shell 命令同上,但只在后端支持时才出现
task把一件事丢给子 agent 去做SubAgentMiddleware

注意:待办清单(write_todos)已经不在这份默认清单里了。TodoListMiddleware 自 0.7.x 起改为 opt-in——默认栈不再装它,只有像 _openai_codex.py 这样的 harness profile 会把它作为 extra_middleware 加回(libs/deepagents/deepagents/profiles/harness/_openai_codex.py:77)。

文件工具的数量有三种口径,别被数字绕晕(三处都对,差别只在"谁在数"):

口径数量出处
create_deep_agent docstring 列的文件操作6(不含 delete)libs/deepagents/deepagents/graph.py:293
FilesystemMiddleware(tools=...) 可选的内置文件工具名7(含 delete)libs/deepagents/deepagents/middleware/filesystem.py:1339,_FS_TOOL_ORDER
中间件构造时真正造出来的工具对象8(7 个 + execute)libs/deepagents/deepagents/middleware/filesystem.py:1718-1731,tool_factories

03 按 8 个的口径讲,因为那一章关心的是"模型这次请求里能看见谁"。

注意 execute 那一行:它不是无条件存在的。后端必须实现 SandboxBackendProtocol(libs/deepagents/deepagents/backends/protocol.py:840),这个工具才会被放进模型请求——这是 §6 要讲的"中间件比普通工具强"的第一个具体例子。

用起来什么样。 最小可跑示例就是 README 的 Quickstart(README.md:55-64),四行:

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.5",              # 或直接传一个 BaseChatModel 实例
    tools=[my_custom_tool],              # 你自己的工具,附加,不会顶掉内置的
    system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})

重点看这两处:

  1. tools= 是加法——create_deep_agent() 的参数文档明写 "Passing tools here is additive — it never removes a built-in"(graph.py:336)。想去掉某个内置工具,得走 profile 的 excluded_tools,不是靠不传。
  2. 返回值是 LangGraph 的 CompiledStateGraph,所以 .invoke() / .stream() / checkpoint / interrupt 全都是 LangGraph 原生能力,Deep Agents 一个都没重新发明。

一句话直觉。 把 LangChain 的 create_agent() 想成毛坯房:水电(模型调用、工具执行循环)都通了,但空的。Deep Agents 是精装交付:家具(文件、子 agent)已经摆好,而且每件都能拆下来换掉。

2. 三层心智模型:谁负责什么​

这一节回答一个最常卡住人的问题:出了问题该去哪一层找? 官方架构文档专门为此写了「The three layers」(libs/ARCHITECTURE.md:12-28),照抄它的分工:

┌─────────────────────────────────────────────────────────────┐
│  Deep Agents    有主张的 harness                            │
│                 默认值 / 中间件栈 / 后端 / profiles         │
├─────────────────────────────────────────────────────────────┤
│  LangChain      agent 抽象                                  │
│  create_agent() 模型 + 工具 + 中间件 → 一个 agent loop      │
├─────────────────────────────────────────────────────────────┤
│  LangGraph      运行时                                      │
│                 state / checkpoint / streaming / interrupt  │
└─────────────────────────────────────────────────────────────┘

自下而上读:

  • LangGraph = 运行时。 它把 agent 跑成一张图:若干步骤 + 步骤间的跳转,每步能读写共享 state。持久化(checkpoint)、流式观测(streaming)、暂停/恢复(interrupt)都由它提供(libs/ARCHITECTURE.md:24)。
  • LangChain create_agent() = agent 抽象。 调用方只描述"模型、工具、中间件"三样,它负责把"调模型 → 执行工具 → 再调模型"这个循环搭出来(libs/ARCHITECTURE.md:25)。
  • Deep Agents = 有主张的 harness。 关键一句原文:它不引入新运行时,create_deep_agent() 只是组装默认中间件栈,并配置后端、子 agent、技能、记忆和 profile(libs/ARCHITECTURE.md:26)。

这条分层的实操价值: 定位问题时先问"这行为归谁管"。

症状大概率在哪层去看
某个工具模型根本看不见Deep Agents(中间件装配 / profile 排除)01
工具看得见但一调就报错Deep Agents(后端能力 / 权限)02、03
循环不停 / 工具结果没回填LangChain agent loop上游 create_agent
会话恢复不了、状态丢了LangGraph checkpoint上游 LangGraph + 05

3. 顶层全景:一次 invoke 的两阶段​

整个系统只有两个阶段,分别对应两张图。官方架构文档也是这么切的:construction(应用代码调 create_deep_agent())与 execution(拿到的图被 invoke)(libs/ARCHITECTURE.md:32-34)。

3.1 阶段一 · construction:组栈​

怎么读这张图: 从上往下是 create_deep_agent() 函数体的执行顺序,最后一步吐出一张可以 invoke 的图。

  create_deep_agent(model=, tools=, subagents=, backend=, skills=, memory=, ...)
        │
        ├─① 解析模型 ────► resolve_model(model) ──► 按模型挑一个 harness profile
        │                                            (给这个模型定制提示词/工具面)
        ├─② 解析后端 ────► backend 或默认 StateBackend()
        │                   (文件、技能、记忆、execute 都落在它上面)
        │
        ├─③ 组子 agent ──► 声明式 / 已编译 / 异步 三类分流
        │                   + 自动补一个 general-purpose 子 agent
        │
        ├─④ 叠中间件栈 ──► 基础脚手架 → 【用户中间件插这里】→ 尾部中间件
        │                   最后按 profile 的 excluded_middleware 过滤
        │
        ├─⑤ 拼系统提示 ──► 用户 system_prompt → profile base → profile 后缀
        │
        └─⑥ 交给上游 ────► create_agent(...).with_config(recursion_limit=9999)
                                 │
                                 ▼
                        CompiledStateGraph  ← 你拿到的 agent

每一步的对应代码在 §5 逐条点名;真正的细节(profile 怎么匹配、栈序为什么这么排)在 01-assembly-and-profiles.md。

3.2 阶段二 · execution:模型被中间件"前后夹住"​

这是整份文档最该记住的一张图。怎么读: 请求从上往下由外向内穿过中间件栈到达模型,响应再由内向外退栈回来;每一层进出各有一次改写机会。

      state.messages + 工具集 + 系统提示
                 │
   ┌─────────────▼──────────────┐   进栈:每层的 wrap_model_call 可以改写 ModelRequest
   │  中间件栈(由外向内)        │   ·加/减工具   ·往系统提示里塞说明
   │  Skills? → FS → SubAgent?  │   ·裁剪/摘要历史  ·读写自己的 typed state
   │  → Summarize → Patch →     │
   │  … → Memory → HITL         │
   └─────────────┬──────────────┘
                 ▼
          ModelRequest(最终版) ───────────►  模 型
                 ▲                              │
                 │  退栈:每层可加工响应        ▼
   ┌─────────────┴──────────────┐        ModelResponse
   │  中间件栈(由内向外)        │        (可能带 tool_calls)
   └─────────────┬──────────────┘
                 ▼
          工具执行 ── 内置文件工具 → 走 backend
                   ├ execute      → 走沙箱 shell
                   └ task         → 起一个子 agent(自带独立的栈)
                 │
                 ▼
          结果写回 state.messages ──► 下一轮,或结束

三个要点:

  1. 模型请求是被"重写"出来的,不是被"配置"出来的。 最终送到模型面前的工具列表和系统提示,是每一层中间件依次改写 ModelRequest 的结果。
  2. 工具执行也能被夹。 FilesystemMiddleware.wrap_tool_call(libs/deepagents/deepagents/middleware/filesystem.py:3458)在工具返回后检查结果大小,超阈值就把内容卸载到文件系统,只把摘要留在上下文里。
  3. 子 agent 是"图里套图"。 task 工具执行的是另一个完整的 agent,它有自己的中间件栈和自己的消息历史——见 04-subagents.md。

4. 关键分工表:四个目录各管什么​

官方文档的「Common starting points」(libs/ARCHITECTURE.md:104-110)已经给了这张排查表,这里补上本文档对应的章节:

部件干什么文件/目录详见
装配入口组装中间件顺序、拼系统提示、决定默认模型行为libs/deepagents/deepagents/graph.py01
中间件工具可见性、系统提示注入、请求期一切行为libs/deepagents/deepagents/middleware/03、05
后端文件落在哪、能不能跑 shell、路径怎么路由libs/deepagents/deepagents/backends/02
Profiles按 provider / 具体模型定制 harnesslibs/deepagents/deepagents/profiles/01

Profiles 内部还分两半,职责正交(libs/deepagents/deepagents/profiles/__init__.py:11-20):

  • ProviderProfile 管模型构造期——resolve_model 该用什么 init_chat_model 参数、要不要做前置副作用。
  • HarnessProfile 管运行期——提示词怎么拼、哪些工具藏起来、加哪些额外中间件、默认子 agent 开不开。

5. 主线走一遍:从参数到 create_agent​

这一节把 §3.1 那张图落到 graph.py 的具体位置,不进代码细节——细节归 01。

① 模型 → profile。 传字符串就 resolve_model(model) 建实例(graph.py:604),传 None 会走过时路径并发弃用警告(graph.py:586-602)。拿到模型后立刻 _harness_profile_for_model(model, _model_spec) 挑出这个模型的 harness profile(graph.py:605),后面的提示词、工具排除、额外中间件都听它的。

② 后端。 一行兜底:backend = backend if backend is not None else StateBackend()(graph.py:627)。默认后端把"文件"存在 LangGraph 的图 state 里——线程级、不落盘,所以默认配置下 execute 不可用。

③ 子 agent 分流。 遍历 subagents,按字段判形态:有 graph_id 归异步、有 runnable 归已编译、其余是声明式(graph.py:647-655)。声明式的会被现场配一套自己的中间件(graph.py:667-675)。随后除非 profile 关掉、或调用方自己传了同名的,否则自动补一个 general-purpose 子 agent(graph.py:750-751)。

④ 主 agent 中间件栈。 从空列表起头(graph.py:817),按条件依次追加 Skills、Filesystem、SubAgent、Summarization、PatchToolCalls、AsyncSubAgent(graph.py:818-851)——待办清单中间件已不在默认栈里(见 §1)。这里有个关键动作:在追加尾部之前先记下"核心栈的名字集合"(graph.py:855 的 _main_core_names),用户中间件才能被插到核心之后、尾部之前。尾部依次是 profile 额外中间件、prompt caching、Memory、HITL(graph.py:859-876)。

⑤ 过滤与排除。 先按 profile 的 excluded_middleware 过滤,再合并用户中间件,再过滤一次(graph.py:877-889);工具级排除 _ToolExclusionMiddleware 最后才追加,注释写得很直白:放最后,这样被排除的工具名不会被某个自定义 wrap_model_call 又加回来(graph.py:890-893)。

⑥ 提示词拼装。 调用方的 system_prompt 放最前,profile 的 base_system_prompt(缺省为空)与 system_prompt_suffix 依次跟上,用空行连接(graph.py:911-920)。Deep Agents 不再自带默认提示词:BASE_AGENT_PROMPT 已弃用(0.7.0 起、0.9.0 移除),只留一个发弃用警告的 __getattr__ 兼容垫片(graph.py:121-137)。

⑦ 交棒。 最后一步就是把攒好的一切原样递给上游(graph.py:922-944):

    return create_agent(
        model,
        system_prompt=final_system_prompt,
        tools=_tools,
        middleware=deepagent_middleware,
        ...
        state_schema=state_schema if state_schema is not None else DeepAgentState,
    ).with_config(
        {
            "recursion_limit": 9_999,
            ...
        }
    )

这段最值得看两处:

  • state_schema 默认用 DeepAgentState(graph.py:934)——它就是 LangChain AgentState 换了个 messages reducer,见 §9 第 4 条。
  • recursion_limit=9_999(graph.py:937)——LangGraph 默认的递归上限对"长任务 agent"太小,这里直接顶到近乎不设限。这是 Deep Agents"为长活优化"这条主张最赤裸的一行代码。

6. 中间件 vs 普通工具:根本区别在哪​

很多人第一反应是"待办、文件这些不就是几个工具函数吗,为什么要做成中间件"。deepagents.middleware 的模块 docstring 专门有一节回答,标题就叫 "Why middleware instead of plain tools?"(libs/deepagents/deepagents/middleware/__init__.py:15-33)。

一句话答案: 中间件重写的是 AgentMiddleware.wrap_model_call() 这个钩子,它在每次 LLM 请求发出之前拦截请求;而 tools=[] 里的普通函数只在模型已经决定调用它之后才被执行——它拦不到请求,自然改不了请求。

四类"普通工具永远做不到"的事(同一段 docstring):

能力具体例子源码里的实现
动态增删工具后端不支持 shell 时,把 execute 从这次请求里摘掉middleware/filesystem.py:3005 _filter_unsupported_tools_and_apply_prompt
注入系统提示Memory / Skills 每轮把"你有哪些技能、记忆里写了啥"塞进系统消息middleware/memory.py:380、middleware/skills.py:1018
改写消息历史数 token、截断旧的工具参数、上下文快满时用摘要替换历史middleware/summarization.py:1335
跨轮维护状态中间件持有一份 typed state dict,跨轮存活(如摘要事件)各中间件的 state_schema

时序对照(这是理解差异的关键):

一轮里的两个时点

   ┌── 时点 A:请求组装 ───┐            ┌── 时点 B:工具执行 ──┐
   │  中间件在这里干活    │            │  普通工具在这里干活 │
   └──────────┬───────────┘            └───────────┬─────────┘
              │                                    │
   改工具列表 / 改系统提示 / 改历史        模型说"调它",才轮到你
              │                                    │
              └────────► 模 型 ────────────────────┘

架构文档把这条差别再压成一句:通过 tools= 传进来的可调用对象无法改写模型调用前的工具列表或提示词(libs/ARCHITECTURE.md:61)。

推论(也是 §9 的伏笔): 因为一切能力都从 wrap_model_call 这一个口子进入模型请求,所以"这个工具为什么在/不在"永远只有一个答案来源——中间件栈。这让排查有唯一的现场。

7. 仓库全景:monorepo 里各包是什么​

这是一个 monorepo,libs/ 下每个目录都是独立发布的 Python 包。本文档全系列只讲 libs/deepagents 这一个包,其余在这里一次性交代清楚,各章不再重复。

目录包名版本是什么
libs/deepagentsdeepagents0.7.7SDK 核心,本文档主角。 create_deep_agent 及全部中间件、后端、profile
libs/codedeepagents-code0.1.57dcode —— 终端里的编码 agent,Textual 写的 TUI
libs/clideepagents-cli0.2.2部署工具链:init / dev / deploy 三个子命令
libs/acpdeepagents-acp0.0.10Agent Client Protocol 连接器,让 Zed 这类编辑器直接跑 Deep Agent
libs/talondeepagents-talon0.0.3实验性长驻运行时:channel adapter(如 WhatsApp)+ cron 调度
libs/evalsdeepagents-evals0.0.1行为评测套件 + Harbor / Terminal-Bench 2.0 集成
libs/partners/*见下—沙箱后端适配包
examples/——十余个可跑示例(deep research、text-to-SQL、ralph mode、talon…)

版本号取自各包的 pyproject.toml(如 libs/deepagents/pyproject.toml:3、libs/code/pyproject.toml:7);SDK 的 __version__ 由 release-please 与之同步(libs/deepagents/deepagents/_version.py:21)。

libs/partners/ 五个沙箱适配包,每个把一家沙箱服务包成 Deep Agents 认的后端:

目录包名
daytonalangchain-daytona
modallangchain-modal
quickjslangchain-quickjs
runlooplangchain-runloop
vercellangchain-vercel-sandbox

几个容易踩的事实:

  • dcode 和 deepagents 命令是两个包。 deepagents-cli==0.1.0 起,交互式 REPL 搬走了,deepagents-cli 只剩部署子命令;交互式编码 agent 是 deepagents-code(libs/cli/README.md:9-15,入口点见 libs/code/pyproject.toml:151-153)。
  • Talon 是 alpha,官方明说不适合生产,且尚未实现完整 HITL 审批策略、沙箱隔离、多租户边界(libs/talon/README.md:5-7)。
  • JS/TS 版本是另一个仓库 deepagentsjs,不在本 monorepo 内(README.md:44)。

8. 阅读地图​

8.1 建议顺序​

  index.md  ← 你在这
     │  懂了三层分工 + 两阶段
     ▼
  01 装配流水线 ──────► 栈是怎么叠出来的、profile 怎么介入
     │
     ▼
  02 后端 ────────────► 文件和 shell 到底落在哪
     │
     ├──► 03 文件系统与权限 ──► 工具族、动态可见性、权限闸门
     ├──► 04 子 agent ────────► 三种形态与上下文隔离
     ├──► 05 上下文工程 ──────► 摘要、卸载、checkpoint 不爆炸
     └──► 06 技能/记忆/自评 ──► 文件如何变成行为

01 和 02 是地基,建议按序读;03–06 彼此独立,按需挑。

8.2 「我想解决 X,该读哪章」​

我的问题读这章
中间件顺序为什么是这个?我的自定义中间件会插在哪?01-assembly-and-profiles.md
换个模型后行为变了,profile 在背后做了什么?01-assembly-and-profiles.md
我要让 agent 的文件真的落到磁盘 / 跨会话保留02-backends.md
execute 工具怎么不见了?怎么接沙箱?02-backends.md
怎么禁止 agent 碰某些路径?怎么加人工审批?03-filesystem-and-permissions.md
想把子任务丢出去做、又不想污染主上下文04-subagents.md
长会话上下文爆了 / checkpoint 越存越大05-context-engineering.md
想用一批 markdown 文件教会 agent 新习惯06-skills-memory-rubric.md

8.3 承重术语约定(全书一词一义)​

上下文管理那几个词在源码里就混着用,读各章前先钉死中译,免得把两件事当成一件:

中文词只用来指源码锚点
卸载(offload)把内容写进后端文件、原位换成"预览 + 路径"这个动作_offload_tool_message_content(middleware/_message_eviction.py:119)
驱逐(evict)"这条结果该不该被卸载"这个阈值判定,只是卸载的触发条件tool_token_limit_before_evict(middleware/filesystem.py:1617)、TOOLS_EXCLUDED_FROM_EVICTION(middleware/filesystem.py:1477-1486)
压缩 / 摘要(summarization)把一段历史交给模型压成一条 summary,和卸载是两条独立防线middleware/summarization.py

所以"大工具结果卸载"是完整说法:先判驱逐、再做卸载。本书叙述一律用「卸载」指落盘动作,不拿「驱逐」当它的同义词。三条防线怎么串起来见 05。

9. 巧妙之处速览​

每条一句话,想细看就跳对应章节。

  1. wrap_model_call 单点收口。 加工具、减工具、改提示、裁历史,全部发生在同一个钩子里——所以"模型看见了什么"永远有唯一的解释现场,不需要在几十处配置项之间对账(middleware/__init__.py:15-33)。→ 本文 §6

  2. 后端按路径前缀路由。 CompositeBackend 把 routes 按前缀长度从长到短排序后匹配,于是 /memories/ 走持久 store、其余走临时 state,对模型来说仍是一个平坦的文件系统(backends/composite.py:232-233)。→ 02

  3. 沙箱后端用 shell 命令实现整套文件 API。 ls / grep / glob / read 全部由 shell 命令派生出来;edit 小载荷内联执行、大载荷退化成"上传新旧字符串 + 服务端替换脚本"。接一家新沙箱因此只需实现四样抽象成员:execute()、upload_files()、download_files() 和 id 属性(backends/sandbox.py:1275、1804-1826)。注意上游两处 docstring 自相矛盾:类 docstring 写的是这四样(backends/sandbox.py:1293-1294),模块 docstring 只提了前两样(backends/sandbox.py:11-12);以代码为准,是四样。→ 02

  4. DeltaChannel 把 checkpoint 增长从 O(N²) 压到 O(N)。 DeepAgentState 只改了一件事:messages 字段挂上 DeltaChannel(_messages_delta_reducer, snapshot_frequency=50),每步只存增量、每 50 步打一次快照,而不是每步都把整段历史再存一遍(graph.py:70-73;reducer 见 _messages_reducer.py:31)。→ 05

  5. 权限是三态,而且分"精确工具"和"批量工具"两套判据。 FilesystemPermission 有 allow / deny / interrupt 三种效果,规则按声明顺序首个命中即生效(middleware/filesystem.py:384、420)。妙在它意识到两类工具语义不同:read_file / write_file / edit_file 是 exact,只看这一个路径命不命中;ls / glob / grep / delete 是 bulk,看搜索子树是否可能与规则前缀相交,路径参数缺省时保守地一律触发(middleware/_fs_interrupt.py:38,_FS_TOOL_PATH_ARGS)。一个 grep 可能捞出敏感目录里的内容,所以它必须按"可能相交"而不是"精确等于"来判。 → 03

  6. 必需脚手架不可被 profile 剥离。 FilesystemMiddleware 和 SubAgentMiddleware 被登记在 _REQUIRED_MIDDLEWARE 里;profile 若想把它们从栈里排掉,_apply_excluded_middleware 直接抛 ValueError,而不是安静地交付一个残废 agent——注释理由很硬:前者承载所有内置文件工具并且是上一条那套权限保证的落点,后者是 task 工具的处理器(graph.py:238-253)。→ 01

  7. 排除项必须命中,否则报错。 profile 里写了却没匹配到任何中间件的排除项会被判为"多半是拼写错误或过期配置"并抛错,而且是在主栈和 general-purpose 子 agent 栈都跑完之后统一核对(graph.py:899-909)。配置漂移在构造期就暴露,不留到运行时。

  8. 大工具结果自动卸载。 工具返回超过 token 阈值时,wrap_tool_call 把内容写进文件系统,上下文里只留一个可回读的引用(middleware/filesystem.py:3458-3483)。术语分工见 §8.3。→ 05

  9. prompt cache 的顺序意识。 Memory 中间件被刻意排在 profile 中间件之后,注释理由是:记忆更新会改系统提示,放前面会让 Anthropic 的 prompt cache 前缀失效(graph.py:856-870)。栈序在这里是性能决策,不只是逻辑决策。

10. 代码地图​

grep 符号名比行号抗漂移,优先用符号名定位。所有路径相对克隆根。

10.1 入口与装配​

主题文件符号
唯一公开入口libs/deepagents/deepagents/graph.pycreate_deep_agent
默认状态 schema(DeltaChannel)libs/deepagents/deepagents/graph.pyDeepAgentState
已弃用的旧默认系统提示libs/deepagents/deepagents/graph.py_LEGACY_BASE_AGENT_PROMPT(经 __getattr__ 以 BASE_AGENT_PROMPT 之名发弃用警告)
用户中间件的插入规则libs/deepagents/deepagents/graph.py_apply_custom_middleware
必备脚手架libs/deepagents/deepagents/graph.py_REQUIRED_MIDDLEWARE
排除项过滤与覆盖校验libs/deepagents/deepagents/_excluded_middleware.py_apply_excluded_middleware、_verify_excluded_middleware_coverage
模型解析libs/deepagents/deepagents/_models.pyresolve_model
消息增量 reducerlibs/deepagents/deepagents/_messages_reducer.py_messages_delta_reducer

10.2 中间件与后端​

主题文件符号
「为什么用中间件」总论libs/deepagents/deepagents/middleware/__init__.py模块 docstring
文件工具 + 动态可见性libs/deepagents/deepagents/middleware/filesystem.pyFilesystemMiddleware、_filter_unsupported_tools_and_apply_prompt
文件工具名单与顺序libs/deepagents/deepagents/middleware/filesystem.py_FS_TOOL_ORDER、_ALL_FS_TOOL_NAMES
路径权限规则libs/deepagents/deepagents/middleware/filesystem.pyFilesystemPermission、_check_fs_permission
权限 → 人工审批的桥libs/deepagents/deepagents/middleware/_fs_interrupt.py_build_interrupt_on_from_permissions、_FS_TOOL_PATH_ARGS
大结果卸载(触发)libs/deepagents/deepagents/middleware/filesystem.pyFilesystemMiddleware.wrap_tool_call、TOOLS_EXCLUDED_FROM_EVICTION
大结果卸载(落盘)libs/deepagents/deepagents/middleware/_message_eviction.py_offload_tool_message_content、TOO_LARGE_TOOL_MSG
子 agent 与 task 工具libs/deepagents/deepagents/middleware/subagents.pySubAgentMiddleware、SubAgent、CompiledSubAgent、GENERAL_PURPOSE_SUBAGENT
异步/远程子 agentlibs/deepagents/deepagents/middleware/async_subagents.pyAsyncSubAgentMiddleware、AsyncSubAgent
摘要压缩libs/deepagents/deepagents/middleware/summarization.pySummarizationMiddleware、create_summarization_middleware
记忆注入libs/deepagents/deepagents/middleware/memory.pyMemoryMiddleware
技能加载libs/deepagents/deepagents/middleware/skills.pySkillsMiddleware
自评libs/deepagents/deepagents/middleware/rubric.pyRubricMiddleware
工具排除libs/deepagents/deepagents/middleware/_tool_exclusion.py_ToolExclusionMiddleware
后端协议libs/deepagents/deepagents/backends/protocol.pyBackendProtocol、SandboxBackendProtocol、BackendFactory
默认后端libs/deepagents/deepagents/backends/state.pyStateBackend
前缀路由libs/deepagents/deepagents/backends/composite.pyCompositeBackend
沙箱基类libs/deepagents/deepagents/backends/sandbox.pyBaseSandbox

10.3 Profile 与文档​

主题文件符号
Profile 两相分工总论libs/deepagents/deepagents/profiles/__init__.py模块 docstring
运行期 profilelibs/deepagents/deepagents/profiles/harness/harness_profiles.pyHarnessProfile、_harness_profile_for_model、GeneralPurposeSubagentProfile
构造期 profilelibs/deepagents/deepagents/profiles/provider/provider_profiles.pyProviderProfile、register_provider_profile
内置 profile 注册libs/deepagents/deepagents/profiles/_builtin_profiles.py模块级注册逻辑
官方架构说明(上游)libs/ARCHITECTURE.md「The three layers」「Construction and execution」