DeepAgents 知识库

导入知识库或按 index.md 的阅读顺序使用；页面之间的前置关系以各页 frontmatter 为准。

学习路径

按前置依赖排的阅读顺序，同一档内无先后：

起步：环境与最小可跑

1. python-env-and-uv-provisioning — DeepAgents 的唯一硬性系统要求是 Python 版本线，系统自带解释器普遍不达标，用 uv 置备合规解释器并建独立虚拟环境是标准解法

2. deepagents-package-family — DeepAgents 的能力拆成三个名字相近、职责完全不同的 PyPI 包，装错包或敲错命令是新手最高频的事故现场

3. model-access-two-paths — model 参数接受预配置实例与提供方字符串两种写法，二者在框架内部走完全不同的分支，决定了依赖哪个接入包、以及各类配置档能否命中

装具骨架 4. deep-agent-harness-overview — create_deep_agent 等价于 create_agent 加一摞预装中间件，产物仍是标准的编译状态图，四支柱能力都由这摞中间件提供 5. provider-profile — 提供方配置档管「模型怎么被构造出来」，把一组初始化参数打包在字符串路径构造时自动注入，但在实例路径下静默失效

1. agent-graph-introspection — 编译后的智能体是一张状态图，节点清单与工具绑定都能当场反查，但访问路径有好几个易踩空的分叉
2. builtin-tools-inventory — 只传一个业务工具，装具会自动挂上一整套内置工具，但「到底几个」有编译期与运行期两个口径，差异全在执行类工具的条件注入上
3. harness-profile — 装具配置档管「模型造好之后怎么跑」，所谓按模型调优拆开看就是一段追加的系统提示后缀，且它在实例路径下靠提供方标识反查仍能命中
4. invoke-result-anatomy — 一次调用的返回值是一个状态容器而不只是对话历史，消息链、虚拟文件、待办清单、中断都各占一个字段，读懂它才能从运行结果里取出证据
5. tool-call-triggering-reliability — 工具、规划、委派是否发生都由模型临场判断，不是结构保证，稳定触发要靠任务复杂度加明确指令，而不是靠框架配置
6. tool-function-contract — 一个普通 Python 函数加类型注解与文档字符串就是一个工具，文档字符串是喂给模型的工具说明书、不是可有可无的注释

四支柱与工具接入 12. agent-middleware-hooks — 中间件把拦截点从 HTTP 请求换成了模型调用，六个钩子分成两族——前后钩子落为图节点、包裹钩子是闭包，签名与义务都不同 13. mcp-server-integration — 用一个独立的适配器包把外部工具服务器暴露的工具批量转成标准工具列表，三行配置换一整套成熟工具，代价是整条链路必须跑在异步上下文里 14. subagent-delegation — 用一个三字段字典定义子智能体挂进工厂函数，主智能体就能通过内置的委派工具把多步子任务整体交出去、只拿回一条结论 15. todo-planning-pillar — 规划支柱让智能体先把多步任务写成一份结构化待办清单再执行，清单同时落进状态字段，代码可随时取出渲染成进度面板 16. tool-name-collision — 三条来路的工具汇进同一个工具字典，同名时用户传入的一方胜出且与注册顺序无关，后果是语义静默改变而不报错 17. virtual-filesystem-state-backing — 智能体眼里的文件系统在存储侧只是状态里的一个扁平字典，目录是查询时算出来的假象，并发不互相覆盖靠的是字典合并型归并函数

机制纵深 18. checkpointer-and-thread-id — 检查点保存器管同一会话内的连续性、键是会话标识，键值仓库管跨会话的持久性，两者是互不替代的正交轴 19. custom-middleware-authoring — 写一个中间件只有三步——继承基类、覆盖一个钩子、用中间件参数挂进去，挂载是追加到预装栈而不是替换 20. file-tools-contract — 写文件只能创建、改已有文件必须走编辑工具，编辑要求字符串唯一匹配否则报错，这两条契约的报错是给模型的纠错信号而非死胡同 21. filesystem-backend-family — 同一套文件工具背后可换六种后端，换后端等于换持久化策略而智能体代码一行不改；组合后端按路径前缀路由，前缀本身就成了持久开关 22. heterogeneous-model-layering — 每个子智能体可以配自己的模型并独立装配调优配置，主智能体用强模型编排、子智能体用轻量模型干活，运行期可逐次调用观测命中的模型 23. large-tool-result-offload — 工具结果超过阈值时框架自动把全文搬进虚拟文件、上下文里只留一条带预览的引用，默认阈值约 80 KB 高到常规演示规模够不着，且省 token 要用一次额外读回来换 24. mcp-tool-mechanics — 协议就是几条结构化消息，标准输入输出下服务器是本机子进程，工具只有异步实现且每次调用重建会话，稳态开销约 1330 毫秒 25. state-schema-and-jump-to — 智能体的状态是所有中间件状态定义在构建期的合并结果，前后钩子除了读写状态还能靠写一个跳转字段叫停整个循环 26. subagent-isolation-boundary — 委派的隔离是双向的——子智能体只看见一条任务描述、主智能体只收回一条结果，但文件状态例外地双向穿透，且隔离有可量化的时间开销 27. todos-state-and-reducer — 待办清单写进状态但对模型屏蔽，模型靠消息历史里的工具回显读回计划；该字段没有累加归并函数，所以是整张覆盖，并因此需要一道并发护栏

扩展与协同 28. cross-session-memory-store — 跨会话记忆的载体是一个独立于任何会话的键值仓库，底层是扁平键值对而非目录树，命名空间做多用户隔离，进程重启即清零 29. hitl-approval-gate — 按工具名声明审批门，命中时调用正常返回一个中断而不是报错，人给出批准、拒绝、改参数、代答四种决定之一后从断点续跑 30. skill-file-spec — 一个技能是一个以技能名命名的目录，里面的说明文件由元数据与正文组成，描述字段缺了技能会被直接丢弃、名字不符只是警告 31. subagent-description-routing — 子智能体的描述字段是写给主智能体做路由决策的说明书，写模糊不会报错、只会让主智能体静默地不委派，而任务描述是子智能体唯一的信息入口 32. summarization-middleware — 摘要中间件零配置就在后台运转、默认阈值高到常规演示规模够不着，压缩是模型抽取式改写而非截断，单次净亏、靠后续每轮省回来 33. wrap-hook-handler-control — 包裹钩子里的内层入口是一个精确闸门——调 0 次是短路、1 次是正常、N 次是重试，多个包裹中间件按洋葱顺序层层套娃

边界、代价与对照 34. context-saving-mechanisms-boundary — 参数截断、卸载、摘要压缩、子智能体隔离都号称省上下文，但操作对象、是否调模型、有损与否各不相同，混用会得出错误结论 35. filesystem-permissions — 按文件路径设权限的第二条通道，硬拒模式在工具内同步拦截、不需要检查点，中断模式则导流进审批流程、必须配检查点 36. ghost-vocabulary-decay — 压缩会悄无声息吃掉某些关键词而智能体既不报错也不自知，观测它必须打在摘要文本上、打在完整消息历史上永远是满分 37. interrupt-resume-mechanics — 中断不是代码冻结而是状态落盘加退出执行栈，恢复时节点从头重放，因此审批点之前的副作用必须幂等；检查点缺失只影响恢复、不影响中断 38. memory-middleware-injection — 记忆有两种进入上下文的方式——后端持久化按需读回、记忆中间件开局注入系统提示，区分它们只需看这次回答里有没有读文件调用 39. progressive-disclosure-levels — 渐进披露分三级——摘要常驻、全文按需、参考资料再按需，所谓激活没有专用机制、就是模型自主发起的一次读文件，且只有技能足够大时才真的省 token 40. skill-source-layering — 技能可以来自多个来源目录，同名时加载顺序靠后的覆盖靠前的，来源标签从路径自动推导，因此团队基线、项目定制与外部平台目录能自然分层

成品验收 41. dcode-cli — 终端编码智能体等于工厂函数加一层交互外壳加外壳替你拍板的装具配置，源码里字面调用同一个工厂函数，能在成品里逐个指认四支柱