---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - langchain
  - deep-agents
  - typescript
  - agent-harness
sources:
  - "https://docs.langchain.com/oss/javascript/deepagents"
  - "https://docs.langchain.com/oss/javascript/deepagents/overview"
  - "https://docs.langchain.com/oss/javascript/deepagents/harness"
  - "https://docs.langchain.com/oss/javascript/deepagents/quickstart"
  - "https://docs.langchain.com/oss/javascript/deepagents/customization"
  - "https://docs.langchain.com/oss/javascript/deepagents/models"
  - "https://docs.langchain.com/oss/javascript/deepagents/profiles"
  - "https://docs.langchain.com/oss/javascript/deepagents/comparison"
  - "https://docs.langchain.com/oss/javascript/deepagents/code-link"
  - "https://docs.langchain.com/oss/javascript/deepagents/changelog-js"
last_verified: 2026-08-11
---

# 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 约定

1. 安装 `deepagents`、`langchain`、`@langchain/core`，再安装所选模型与工具的集成包。
2. 使用 `createDeepAgent({ model, tools, systemPrompt })` 创建 Agent。
3. 模型必须支持 tool calling；字符串通常采用 `provider:model`。
4. 任务规划不是默认能力。需要 `write_todos` 时显式追加 `todoListMiddleware()`。
5. 搜索可使用供应商原生工具，或 `@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。

## 默认中间件栈

### 裸栈

只有模型时，核心顺序可概括为：

1. Filesystem middleware
2. 同步 SubAgent middleware（默认 `general-purpose` 存在时）
3. Summarization middleware
4. PatchToolCalls middleware
5. 支持供应商的提示缓存与 profile 附加能力

### 启用全部能力后的顺序

1. Skills
2. Filesystem + permissions
3. 同步 SubAgent
4. Summarization
5. PatchToolCalls
6. AsyncSubAgent
7. 调用方 `middleware`
8. Harness profile 的额外 middleware
9. `excludedTools` 过滤
10. Anthropic / Bedrock 提示缓存
11. Memory
12. 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` / `systemPromptSuffix`
- `toolDescriptionOverrides`
- `excludedTools` / `excludedMiddleware`
- `extraMiddleware`
- `generalPurposeSubagent`

`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 页面存在跨语言混排。遇到冲突时按以下证据优先级处理：

1. TypeScript API Reference 与导出的类型。
2. 同页 TypeScript 代码示例。
3. TypeScript 专题页的明确限制说明。
4. 通用 prose。
5. 明显使用 snake_case、Python 类型或 Python 包版本的段落。

这不是风格问题，而是正确性问题：例如 Python 的 `state_schema`、middleware 同名替换、permission `interrupt` 模式和 provider profile 都不能直接移植到 TypeScript。