---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - langchain
  - deep-agents
  - typescript
  - context-engineering
  - multi-agent
sources:
  - "https://docs.langchain.com/oss/javascript/deepagents/skills"
  - "https://docs.langchain.com/oss/javascript/deepagents/memory"
  - "https://docs.langchain.com/oss/javascript/deepagents/retrieval"
  - "https://docs.langchain.com/oss/javascript/deepagents/context-engineering"
  - "https://docs.langchain.com/oss/javascript/deepagents/openwiki"
  - "https://docs.langchain.com/oss/javascript/deepagents/subagents"
  - "https://docs.langchain.com/oss/javascript/deepagents/dynamic-subagents"
  - "https://docs.langchain.com/oss/javascript/deepagents/async-subagents"
last_verified: 2026-08-11
---

# Deep Agents TypeScript：上下文、记忆、检索与子代理

## 把信息放到正确层

| 信息/工作类型 | 推荐机制 | 生命周期 |
| --- | --- | --- |
| 每次都必须遵守的短规则 | `AGENTS.md` memory | 启动时总是进入系统提示 |
| 任务相关的详细流程与模板 | Skill | 先加载 name/description，命中后再读正文和资源 |
| 用户 ID、角色、连接、短期凭证 | Runtime context | 每次 invoke 传入，不自动给模型看 |
| 大工具结果与历史消息 | 自动 offloading / summarization | 接近上下文上限时压缩 |
| 跨会话事实与偏好 | Store-backed long-term memory | 由 namespace 决定用户/Agent/组织范围 |
| 输出密集或专门工作 | 子代理 | 独立上下文，只回传最终结果 |

核心原则是“常驻内容越短越好”。把所有知识塞入 system prompt 会降低相关性、增加缓存失效和成本；把需要每次遵守的安全规则藏进按需 Skill 又可能错过。

## System prompt 与 runtime context

静态 `systemPrompt` 会与基础提示、memory、skills、文件系统说明、子代理说明、自定义 middleware 提示和 HITL 说明共同组装。需要根据用户角色动态改变提示时，用 `dynamicSystemPromptMiddleware` 读取 `request.runtime.context` 或 store；仅工具需要这些数据时，不必为此创建动态提示 middleware。

`contextSchema` 通常用 Zod 声明。invoke 时通过 options 的 `context` 传值；工具经 `ToolRuntime` 读取。Runtime context 自动传播到同步子代理，可用带子代理前缀的扁平键或独立字段表达专用配置。

上下文工程页的完整提示清单仍夹杂 `system_prompt`、`interrupt_on` 和 Python 源码链接。结构概念可用，但 TypeScript 字段名必须改为 camelCase。

## 自动上下文压缩

### Offloading

默认阈值为约 20,000 文本 tokens：

- 大型文件写入/编辑输入已存在 backend 中；当整体上下文接近窗口的 85% 时，较旧调用会替换成文件指针。
- 大型工具结果会写入 backend，消息里保留路径与前 10 行预览。

模型可随后使用 `read_file`、`grep` 和分页读取恢复细节。非文本媒体不按二进制大小计入这套 token 规则。

### Summarization

`SummarizationMiddleware` 在裸栈中默认存在：

- 通常在模型 profile 的输入窗口达到 85% 时触发。
- 保留最近约 10% tokens。
- 缺少 profile 时回退到约 170,000 tokens / 保留 6 条消息。
- 标准 `ContextOverflowError` 可触发立即摘要并重试。
- 原消息会以文本形式保存在 backend，活动上下文只保留结构化摘要和最近消息。

摘要流生成的 token 可能混入普通 token stream，UI/日志要按 metadata 过滤。摘要是文本化压缩，不保存较早媒体 block。

## Skills

Skill 是目录化能力包：`SKILL.md` 的 YAML frontmatter 至少有 `name` 和 `description`，正文写执行指令，可附 `scripts/`、`references/` 与 `assets/`。

三层渐进披露：

1. 启动加载所有技能的 name + description。
2. 命中任务后读完整 `SKILL.md`。
3. 指令要求时才读或运行支持文件。

写作建议：description 同时说明“做什么”和“何时使用”，减少近义技能；正文控制在单一工作流，长参考移到一层深的文件；给出决策条件、输入输出与边界情况。`SKILL.md` 超过 10 MB 会被跳过。

多 source 同名时后一个覆盖前一个。SDK 只加载显式传入的路径，不会自动扫描 Deep Agents Code 的用户/项目目录。一般 `general-purpose` 子代理继承主 Agent skills，自定义子代理不继承，需在规格中显式配置。

技能脚本能否执行取决于 backend：普通 backend 只能读，shell 运行需要 sandbox。技能文件在 sandbox 外时，需要 `beforeAgent` 上传、`afterAgent` 下载同步，否则模型看得到说明却运行不了脚本。

### Skills 页的已知冲突

该页多个段落使用 Python 的 `create_deep_agent`、`list[str]`、`interrupt_on` 和 `mode="interrupt"`。其中路径级 interrupt 与 TypeScript permissions 专页冲突。可靠结论是：

- 可用 permissions 做只读技能库。
- TypeScript 工具级写入审批使用 `interruptOn`。
- 不能依据此页断言 permission 存在 `interrupt` mode。

## 长期记忆

文件型记忆可按三个维度设计：

- 用户范围：用户偏好与私有上下文，推荐默认。
- Agent / assistant 范围：一个 Agent 的共享身份和经验。
- 组织范围：共享政策，通常必须只读。

语义事实可保存在 `AGENTS.md` 等文件；程序性知识放 Skills；会话过程属于 checkpointer 支持的 episodic memory。要检索历史会话，可把 thread search 封装成工具，并在服务端按 user/org metadata 过滤。

热路径写入立即可见但增加响应延迟；后台 consolidation 可定时读取近期对话并合并记忆，代价是下一次会话前才生效。cron 频率必须与搜索回看窗口一致，否则重复处理或漏掉会话。

共享记忆的最大风险是跨用户提示注入：

- 默认使用 user namespace。
- 组织政策由应用写、Agent 只读。
- 同一文件并发写是 last-write-wins；按主题拆文件或用 consolidation 串行化。
- 多 Agent 共用部署时把 assistant ID 纳入 namespace。

## Retrieval 与 RAG

Retrieval 页给出三个架构：

| 架构 | 何时检索 | 特点 |
| --- | --- | --- |
| 2-Step RAG | 生成前固定检索 | 可预测、低延迟、灵活性低 |
| Agentic RAG | Agent 自己决定 | 灵活但调用数与延迟波动 |
| Hybrid RAG | 查询改写、检索验证、答案验证 | 在控制与灵活性间折中 |

Deep Agent 只需获得能访问知识源的工具就可形成 Agentic RAG。大规模语料仍应建立 loader → splitter → embeddings → vector store 管线；已有 SQL、CRM 或文档库可直接包装为工具，不必为了 RAG 重新入库。

大结果适合“检索 → 写入 backend → 子代理分别分析 → 主 Agent 汇总”。这样主上下文只接收文件路径与短报告，而不是所有原文。

## 同步子代理

同步子代理由 `task` 调用；主 Agent 阻塞到完成，但一次模型响应可并行发出多个 task。适合多步骤调查、专门模型/工具以及上下文隔离，不适合简单单步动作或必须保留全部中间上下文的任务。

TypeScript 声明式规格的主要字段：`name`、`description`、`systemPrompt`、`tools`、`model`、`middleware`、`interruptOn`、`skills`、`responseFormat`、`permissions`。注意继承关系：

- `systemPrompt` 与 custom skills 不继承。
- `model` 和工具默认继承；显式 tools 会整体覆盖。
- custom middleware 追加到子代理栈，不继承主 Agent middleware。
- 子代理 permissions 若提供，会整体替换父规则。
- 结构化结果 JSON 序列化后通过 ToolMessage 返回父 Agent。

Compiled subagent 可接任意已编译 LangGraph，但 state 必须有 `messages` 键。

### 文档跨语言残留

Subagents 页同时出现正确的 camelCase 表格和 Python 的 `general_purpose_subagent`、`excluded_middleware`、`ValueError`、`False`。TypeScript 禁用或定制默认 `general-purpose` 的精确 profile 字段应以 `profiles` 页/API Reference 为准，不能复制 Python 参数。

## Dynamic subagents

Dynamic subagents 是 QuickJS interpreter 内的 `task()` 桥：Agent 用 JavaScript 循环、分支和并发批次选择与调用子代理。适用模式包括：

- 分类后路由到不同专家。
- fan-out 后汇总。
- 两阶段对抗验证。
- 多候选生成与过滤。
- 淘汰赛式比较。
- 去重并循环直到没有新结果。

提示中使用“workflow”会触发内置解释器提示倾向动态编排，但它不是确定性的 API flag。文件发现等外部动作还需 PTC allowlist。`task()` 同样绕过普通工具审批路径；需要人审时 gate `eval`。

## Async subagents

异步子代理是 `deepagents` 1.9.0 的 preview。它连接 Agent Protocol 服务，启动后立即返回 task ID，主 Agent 可继续对话，并用五个工具管理任务：start、check、update、cancel、list。

与同步子代理相比：

- 非阻塞，可中途更新和取消。
- 每个任务有独立 thread，跨交互保存状态。
- task metadata 存在主图的专用 `asyncTasks` channel，不依赖可能被摘要掉的 ToolMessage。
- update 会中断上一 run，并在同一 thread 上携带完整历史重新启动。

同部署优先省去 URL，使用进程内 transport；跨部署 HTTP 适合独立扩缩容与不同资源配置。开发时 worker 数至少为“主 Agent 1 + 最大并行子代理数”，否则启动会排队。状态报告前必须实时 check/list，不能信任历史消息中的旧状态。

## OpenWiki 的边界

`/oss/javascript/deepagents/openwiki` 当前 307 跳转到共享 `/oss/openwiki/overview`，且正文主要链接 Python Deep Agents。OpenWiki 是独立 CLI：生成仓库 Markdown wiki，并在根 `AGENTS.md` / `CLAUDE.md` 写入发现指针；它不是 TypeScript SDK API。其价值是把稳定仓库知识做成 Agent 可检索的持久上下文，而不是把全仓代码每次重读。