---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - typescript
  - mcp
  - multi-agent
  - retrieval
  - memory
topic: LangChain TypeScript MCP、多代理、检索、长期记忆与 SQL Agent
sources:
  - https://docs.langchain.com/oss/javascript/langchain/knowledge-base.md
  - https://docs.langchain.com/oss/javascript/langchain/long-term-memory.md
  - https://docs.langchain.com/oss/javascript/langchain/mcp.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/custom-workflow.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/handoffs-customer-support.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/handoffs.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/index.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/router-knowledge-base.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/router.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/skills-sql-assistant.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/skills.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/subagents-personal-assistant.md
  - https://docs.langchain.com/oss/javascript/langchain/multi-agent/subagents.md
  - https://docs.langchain.com/oss/javascript/langchain/retrieval.md
  - https://docs.langchain.com/oss/javascript/langchain/sql-agent.md
last_verified: 2026-08-11
---
# LangChain TypeScript：MCP、多代理、检索与记忆

## 决策顺序

先问“单 agent + 合理 context engineering 是否已足够”，再选择能力：

1. 需要连接外部标准化工具 → MCP；
2. 需要私有知识 → loader/splitter/vector store/retriever 或检索工具；
3. 需要跨会话偏好/事实 → long-term store；
4. 工具太多但任务仍由同一主体完成 → skills 或动态工具选择；
5. 确有 context 隔离、并行或责任边界 → multi-agent；
6. 流程必须确定性 → custom LangGraph workflow。

多 agent 不是质量开关。它会增加 token、延迟、失败面、状态和观测复杂度；文档的性能示例是特定任务/模型的比较，不应外推成普遍结论。

## MCP：TypeScript adapter 的真实语义

客户端使用 `@langchain/mcp-adapters` 的 `MultiServerMCPClient`，自建 server 使用 `@modelcontextprotocol/sdk`。配置可连接多个 server，再把加载出的 tools 交给 agent。

### 会话与 transport

- `MultiServerMCPClient` **默认无状态**：每次工具调用新建 `ClientSession`，执行后清理；需要 server-side 会话连续性时不能假设自动保持。
- `stdio` 适合受控本地子进程。命令、参数、cwd、环境和可执行文件必须允许列表化，不能让模型直接拼 shell。
- `http` / `streamable-http` 是远程 server 的现代传输；鉴权 header、TLS、超时、重试、代理和出网策略需要显式配置。
- 页面仍保留一个 SSE custom server 示例，但 transport 章节以当前 streamable HTTP 为主。新系统应以当前 MCP specification 和 SDK 版本为准，不因旧示例优先选择 SSE。

### 错误与内容差异

JS adapter 的关键差异：当 MCP 返回 `CallToolResult.isError: true` 时，adapter 抛出 `ToolException`；**它不会像 Python adapter 那样自动把失败变成给模型看的 failed ToolMessage**。调用者或 `wrapToolCall` 必须捕获、分类、记录并决定：重试、返回受控工具错误、fallback 或终止。

工具结果可包含 text、image、audio 等多模态 content。必须限制大小、MIME、来源和反序列化，避免把任意远程内容直接渲染到浏览器。

当前 JS MCP 页面重点只覆盖 tools 和 multimodal tool content，没有像 Python 页面那样完整记录 resources、prompts、interceptor 或 stateful-session API。不存在于本页的能力不能据此宣称已由 JS adapter 支持；需查当前 SDK reference。

## Multi-agent 五种模式

| 模式 | 控制者 | 上下文隔离 | 适用 |
|---|---|---|---|
| Subagents | 主 agent 调用 specialist tool | 强 | specialist 有复杂独立任务、结果回传 supervisor |
| Handoffs | 当前 agent/状态切换 active agent | 可连续 | 客服分流、用户直接继续与 specialist 对话 |
| Skills | 同一 agent 按需加载知识/流程 | 无新 agent | 工具和知识很多，主要问题是 prompt 膨胀 |
| Router | router 分类后派发一个或多个 worker | 可配置 | 输入可清晰分类、并行 fan-out/fan-in |
| Custom workflow | LangGraph 显式节点/边 | 完全自定义 | 确定性阶段与 agentic 节点混合、复杂状态合并 |

### Subagents

主 agent 保留对话历史，subagent 通常每次从新上下文开始，只接收任务描述并返回最终结果。这减少主上下文污染，也便于并行。工具可以“一 specialist 一个工具”，也可以用单一 dispatch tool + enum/registry。

文档的 sync/async 是**阻塞委派与后台任务**之分，不是 TypeScript 是否使用 `async/await`：

- synchronous：主 agent 等子任务结束，适合结果立即用于推理；
- asynchronous：提交后台 job，返回 job ID，之后轮询/通知；需要真正的外部 worker/process/service、持久 job state、取消和重试，不是忘记 `await`。

subagent 输入只给完成任务所需上下文，输出用结构化短摘要/artefact 引用。若共享 checkpointer，需理解 namespace；不要让 specialist 意外读取其他租户 thread。

个人助理教程把 calendar/email 领域委派给 specialists，展示 supervisor 如何保留用户对话、parallel tool calls 和结果整合。它是 pattern 示例，不自带真实 OAuth、权限或幂等保证。

### Handoffs

handoff 通常用 `Command` 更新 active-agent state，并把必要消息传给下一方。单 graph + middleware 的实现较简单，优先于多个 agent subgraph；后者只有在状态、工具或团队边界确需独立时使用。

多个 subgraph 共享消息时，tool-call/result 必须完整成对，否则恢复后模型会收到非法历史。customer support 教程演示分类、转交、active agent 和往返，但生产还需权限、SLA、升级人工、审计和防止无穷转交。

### Router

Router 可返回一个 `Command` 选择单 worker，或用 LangGraph `Send` 并行派发。无状态 router 适合单次请求；需要对话连续性时，可以把 worker 包为工具或给完整 graph 持久化。并行结果必须定义 reducer、超时、部分失败和输出顺序。

知识库路由教程按数据源把问题发给 GitHub、Notion、Slack 等 specialist，再汇总。真实系统的 connector credentials、ACL 和 source-level citation 必须贯穿检索，不能因为进入同一 agent 就合并权限域。

### Skills

Skill 用 progressive disclosure 控制上下文：启动时只暴露 name/description；模型需要时再读 `SKILL.md`，必要时读取 scripts/references/assets。核心原则是元数据清晰、目录边界稳定、按需加载，不把所有 skill 正文预塞 system prompt。

SQL assistant 教程展示 core skill + 数据库特定 skill + resources，适合把 schema 约定、查询工作流和领域规则分层。Skill 是指导材料而非安全边界；SQL 权限仍由数据库账号、allowlist/parser、limit/timeout 和 HITL 控制。

### Custom workflow

显式 graph 可把 retrieval、generation、验证、fallback 和人工节点排成确定流程，同时在个别节点使用 agent。适合严格顺序与可恢复分支；代价是 state/reducer、并行、错误和迁移都由团队负责。

## Retrieval 与知识库

语义检索管道：加载 `Document` → `RecursiveCharacterTextSplitter` 分块 → embedding → vector store → similarity search/retriever → 把相关片段用于回答。

TypeScript 语义：`Document.pageContent` 是正文，`metadata` 保存 source、page、ACL 等，`id` 可选。知识库教程以 in-memory store 展示流程；生产要评估持久 vector DB、批量写入、embedding 版本、重建、删除传播、租户隔离、metadata filter 和引用。

三种常见 RAG：

- 2-step：每次先检索再生成，延迟和路径可预测；
- agentic：检索作为工具，模型决定是否/如何查，灵活但轨迹不稳定；
- hybrid：确定性 routing/validation + agentic query refinement。

`/oss/javascript/langchain/retrieval` 当前 308 到 `/oss/javascript/deepagents/retrieval`，已经跨出 LangChain 栏目。该页仍计入可点击路由，但正文属于 Deep Agents retrieval 视角。页面与 knowledge-base 中可见 `dict`、`as_retriever`、Python reference 等模板残留；TypeScript 真实方法应查 JS reference（例如 camelCase）并由编译器验证。

## Long-term memory

Store 以 `namespace: string[] + key` 组织跨 thread 数据，工具通过 `runtime.store` put/get/search。常见类型：

- semantic memory：用户偏好和事实；
- episodic memory：历史案例；
- procedural memory：长期规则/指令。

写入策略可由用户显式触发，也可由 agent 热路径或后台任务提取。生产必须设计：tenant/user namespace、数据来源、置信度、冲突合并、TTL、删除/导出、embedding 更新和 prompt injection 防护。不要把模型生成的“记忆”直接当权威业务事实。

短期 checkpointer 与长期 store 职责不同：前者恢复一个 thread 的执行 state，后者跨 thread 检索信息。两者都不是应用数据库的替代品。

## SQL Agent 的安全底线

教程使用 SQLite 和精简 DB wrapper，明确不是 production-ready。真实部署至少需要：

- 只读或最小权限账号；写操作单独工具与审批；
- 允许 schema/table/statement 类型，禁止任意 DDL/DML；
- 参数化、行数/执行时间/资源限制；
- explain/cost gate、取消、审计和脱敏；
- 数据库错误转换为有限信息，避免泄漏 schema/凭证；
- 对关键查询做 golden/eval，并验证真实数据库版本。

## 路由闭包与 orphan 边界

- `/multi-agent`（sitemap）和 `/multi-agent/index`（llms）当前都 HTTP 200，正文相同；两条可点击路由均列入 sources，但只学习一次内容。
- 可直接访问的 `/oss/javascript/langchain/deep-agent-from-scratch` 是完整 JS 教程，但它不在 llms、sitemap、common-errors 或已抓页面内链中，属于不可点击 orphan。本任务按“每个能点的选项”口径不把它计入覆盖或 sources；若未来进入官方导航，应单独补录。

## 逐页覆盖

| 页面组 | 学习结论 |
|---|---|
| MCP | JS adapter 包、stateless session、HTTP/stdio、SSE 遗留示例、ToolException 和 multimodal。 |
| Multi-agent overview | 五种 pattern、选择标准、context/tool-call/性能权衡；canonical 与 index 两路同文。 |
| Subagents + personal assistant | supervisor、隔离上下文、同步/后台委派、dispatch tool 和个人助理实例。 |
| Handoffs + customer support | Command、active agent、单 agent middleware 优先、subgraph 消息完整性和客服实例。 |
| Router + knowledge base | Command/Send、无状态/持久 router、并行 fan-out 与多源知识实例。 |
| Skills + SQL assistant | metadata-first progressive disclosure、core/resources 分层与 SQL 领域实例。 |
| Custom workflow | 确定性 LangGraph + agentic nodes 的混合 RAG。 |
| Knowledge base / retrieval | Document、split/embedding/vector/retriever、RAG 类型与跨栏重定向。 |
| Long-term memory | namespace/key、runtime.store、记忆类型与治理。 |
| SQL agent | 自然语言查库 loop、SQLite demo 和生产安全缺口。 |

## 延伸

- [[04-TypeScript-Middleware-Context-Runtime-and-HITL]]
- [[06-TypeScript-Frontend-and-Generative-UI]]
- [Python 对照](../Python/05-MCP-Multi-Agent-Retrieval-and-Memory.md)