学习笔记 · Obsidian
Deep Agents TypeScript：差异与定制
路由边界：
/oss/javascript/deepagents与/harness都规范跳转到本页 overview；它们不是额外的一套 API，但属于站内可点击入口。
结论先行
TypeScript 版与 Python 版共享同一套 Deep Agents 思想：在 LangChain Agent 与 LangGraph 之上预装文件工作区、上下文压缩、同步/异步子代理、技能、记忆和人机审批。真正需要区别对待的是 API 命名、可配置项、中间件组合语义和若干尚未对齐的能力。
TypeScript 最小入口是 deepagents 包的 createDeepAgent，配置对象采用 camelCase。文档中的代码与 JavaScript API Reference 应优先于同页残留的 Python 式 prose；当前 TypeScript 文档有多处 create_deep_agent、system_prompt、interrupt_on 等复制残留，不能照抄到代码里。
何时选 Deep Agents
| 需求 | 更合适的抽象 |
|---|---|
| 少量工具、短对话、无需工作区 | LangChain createAgent |
| 确定性分支、显式状态机、细粒度节点控制 | LangGraph |
| 长任务、文件工作区、子代理隔离、自动压缩和治理 | Deep Agents |
与 Claude Agent SDK 相比，Deep Agents 的主要取舍是解耦：模型、执行后端和部署目标可分别选择；可在沙箱内运行 Agent，也可让 Agent 在外部把远程沙箱当工具。代价是跨模型兼容与调参责任更多落在使用方。比较页本身注明草拟日期为 2026-04-16，产品选型时应重新核验竞品现状。
快速启动与 TypeScript 约定
- 安装
deepagents、langchain、@langchain/core，再安装所选模型与工具的集成包。 - 使用
createDeepAgent({ model, tools, systemPrompt })创建 Agent。 - 模型必须支持 tool calling；字符串通常采用
provider:model。 - 任务规划不是默认能力。需要
write_todos时显式追加todoListMiddleware()。 - 搜索可使用供应商原生工具，或
@langchain/tavily等外部工具。
Google 的示例代码使用 google-genai:...，但部分 prose 写成 google_genai:...。以可运行示例和模型集成文档为准，不混用连字符与下划线。
createDeepAgent 配置地图
| TypeScript 字段 | 作用 | 与 Python 的关键差异 |
|---|---|---|
model | 模型标识或模型实例 | 相同概念 |
systemPrompt | 业务角色、目标和约束 | camelCase |
tools | 领域工具 | 与内置文件/委派工具并存 |
memory | 启动时加载的 AGENTS.md | 相同概念 |
skills | 渐进加载的技能目录 | 相同概念 |
backend | 文件与执行环境 | TS 后端协议 V2 原生支持二进制 |
permissions | 内置文件工具路径规则 | 当前只有 allow / deny |
subagents | 同步或异步子代理规格 | 字段同样使用 camelCase |
middleware | 调用方附加中间件 | 文档只保证追加，不保证按名称替换默认项 |
interruptOn | 工具级人机审批 | 需 checkpointer 才能跨中断恢复 |
responseFormat | 主代理结构化结果 | 结果位于 structuredResponse |
contextSchema | 单次运行的只读上下文类型 | 常用 Zod；向子代理传播 |
TypeScript 定制页没有列出 Python 的 stateSchema。不要从 Python 版推断 TypeScript 支持相同入口；需要自定义持久状态时先核对当前 JS API Reference 或直接使用 LangGraph。
默认中间件栈
裸栈
只有模型时，核心顺序可概括为：
- Filesystem middleware
- 同步 SubAgent middleware（默认
general-purpose存在时） - Summarization middleware
- PatchToolCalls middleware
- 支持供应商的提示缓存与 profile 附加能力
启用全部能力后的顺序
- Skills
- Filesystem + permissions
- 同步 SubAgent
- Summarization
- PatchToolCalls
- AsyncSubAgent
- 调用方
middleware - Harness profile 的额外 middleware
excludedTools过滤- Anthropic / Bedrock 提示缓存
- Memory
- Human-in-the-loop
顺序具有语义：PatchToolCalls 修复中断或取消留下的悬空工具调用；Memory 在系统提示最终组装阶段注入；HITL 必须看到最终工具集合。
TypeScript 的覆盖边界
Python 文档说明“同名中间件整体替换默认实例”，而 TypeScript 定制页只说明用户 middleware 会追加在 PatchToolCalls 之后，且“覆盖默认中间件”小节没有给出可用机制。因此：
- 不要依赖名称碰撞替换默认中间件。
- 需要移除工具时优先使用 harness profile 的
excludedTools。 - 需要改变整体执行栈时，直接用 LangChain
createAgent组装 middleware，或核对当前 TypeScript API 后再实现。 - 自定义 middleware hook 不应修改共享闭包变量；并发运行时使用 graph state 或并发安全存储。
Harness profiles
TypeScript 当前明确支持 harness profile，用于一次性表达供应商/模型相关的执行外壳差异：
baseSystemPrompt/systemPromptSuffixtoolDescriptionOverridesexcludedTools/excludedMiddlewareextraMiddlewaregeneralPurposeSubagent
extraMiddleware 可为静态数组或零参数工厂；工厂适合为每个 Agent 创建新实例。Filesystem 与 SubAgent 属于必要脚手架，不能通过 excludedMiddleware 删除。profile 可解析和序列化 YAML/JSON，但包含非空 middleware 实例时无法完整序列化。
TypeScript 没有 Python 的 entrypoint 插件注册方式；应用启动时直接调用注册 API。profiles 专页还明确说 provider profiles 与插件注册系统是 Python-only。与之冲突的是 models 页仍展示 ProviderProfile prose。当前应以更具体的 profiles 页与 API Reference 为准，不把 ProviderProfile 当作已确认的 TypeScript 能力。
模型选择原则
- 简单检索与分类可用更快、更便宜的模型；长推理、代码与复杂工具编排选更强模型。
- Agent 是否成功不只由通用 benchmark 决定，还取决于 tool calling、上下文长度、结构化输出和供应商限流。
models页的评测表是一个时间点快照，不是永久排名；上线前用自己的任务集评估。- 提示缓存仅对支持的供应商生效，其他供应商应视为 no-op，而不是错误。
两个导航入口的真实边界
code-link当前 307 跳转到/oss/deepagents/code/overview。它只是 Deep Agents Code 的桥接入口；dcode是基于 Python SDK 的独立终端产品，不是 TypeScript SDK 子模块。changelog-js当前 307 跳转到/oss/javascript/releases/changelog。它是 JavaScript 生态全局 changelog，不是 Deep Agents 独有版本日志。
文档使用守则
当前 TypeScript 页面存在跨语言混排。遇到冲突时按以下证据优先级处理：
- TypeScript API Reference 与导出的类型。
- 同页 TypeScript 代码示例。
- TypeScript 专题页的明确限制说明。
- 通用 prose。
- 明显使用 snake_case、Python 类型或 Python 包版本的段落。
这不是风格问题，而是正确性问题：例如 Python 的 state_schema、middleware 同名替换、permission interrupt 模式和 provider profile 都不能直接移植到 TypeScript。