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

> `/multi-agent` 是模式总览的无 `index` 入口；它与本笔记已学习的 `/multi-agent/index` 共同保留，以覆盖站内两条可点击路由。

## 总体判断

这四组能力都在解决“agent 自身上下文不够”的问题，但边界不同：

| 能力 | 扩展的对象 | 最重要的边界 |
|---|---|---|
| MCP | 外部工具、资源、提示词与交互协议 | server 信任、transport、session、auth |
| Multi-agent | 专业上下文、并行执行与团队所有权 | 路由语义、状态归属、token/调用成本 |
| Retrieval/RAG | 查询时外部知识 | ingestion 质量、召回、grounding 与评估 |
| Long-term memory | 跨 thread 的用户/应用记忆 | namespace 隔离、写入策略、隐私与生命周期 |

优先顺序通常是：单 agent + 高质量 tools/retrieval → 动态上下文/skills → 只有确需隔离或并行时才采用多代理。

## MCP：把远程能力适配成 LangChain 原语

安装 `langchain-mcp-adapters` 后，`MultiServerMCPClient` 可以把多个 MCP server 暴露的 tools 转成 LangChain tools，再交给 `create_agent`。自建 server 可用 FastMCP。

### Transport 与 session

- HTTP/streamable HTTP 适合远程服务；headers 和 `httpx.Auth` 可承载认证，OAuth 由 MCP SDK 支持。
- stdio 由 client 启动本地子进程，适合本地工具；进程连接本身有状态，但 `MultiServerMCPClient` 默认每次工具调用仍创建新 session。
- client **默认无状态**；server 必须跨多次调用保存上下文时，用 `client.session(server_name)` 显式管理 `ClientSession` 生命周期。
- 旧 SSE transport 已被规范弃用，新增实现优先 streamable HTTP。

### 三类核心能力

| MCP 能力 | LangChain 表示 | 注意点 |
|---|---|---|
| Tools | LangChain tools / `ToolMessage` | 默认 MCP tool error 可作为 `status="error"` 返回模型；transport/session/conversion error 仍抛异常 |
| Resources | `Blob` | 可按 server/URI 加载文本或二进制；资源不会自动成为模型上下文 |
| Prompts | messages | 可按名称和参数加载，再由应用决定如何进入 workflow |

MCP tool 的 `structuredContent` 放在 `MCPToolArtifact`，不会天然等于“模型已经看见结构化 JSON”；若模型需要读取，可由 interceptor 明确转换/追加。多模态结果会转换为标准 content blocks，仍需目标模型支持对应 modality。

### Interceptor 与安全

MCP server 在独立进程，不能直接读取 LangGraph state/store/runtime；tool interceptor 是连接桥梁，可注入可信用户上下文、动态 header、过滤参数、重试、短路、返回 `Command` 更新 state 或跳转。多个 interceptor 采用洋葱顺序，列表首项最外层。

安全原则：

- 远程 server、其 schema、资源和 UI 都视为外部输入；做 allowlist、最小权限、超时、限流和审计。
- 用户/租户身份从 runtime 注入，不由模型生成；认证 material 不进入 prompt、trace 或 tool args 日志。
- 区分 tool 返回的业务错误和 transport 异常，重试只用于幂等、瞬时错误。
- progress/log callbacks 用于可观察性；elicitation 的 `accept`/`decline`/`cancel` 是用户交互，不应自动代答敏感字段。

## 多代理：先选协调语义，再写代码

### 五种模式

| 模式 | 控制方式 | 最适合 | 主要代价 |
|---|---|---|---|
| Subagents | supervisor 把 specialist 当 tools 调用 | 上下文隔离、多域并行、中央控制 | 每次子代理通常无状态，结果要回 supervisor 再总结 |
| Handoffs | tool 更新 `active_agent`/阶段 state，改变 prompt/tools/路由 | 多轮顺序流程、直接与用户对话 | 并行弱，历史随阶段增长，状态机需严谨 |
| Skills | 单 agent 按需加载专业提示词/资源 | 很多轻量专业知识、渐进披露 | 首次加载多一次 tool call，已加载上下文会持续占 token |
| Router | 分类步骤 fan-out 到一个或多个 agent，再合成 | 清晰垂直域、多源并行查询 | 通常无状态；分类和合成各有成本 |
| Custom workflow | LangGraph 显式节点、分支、循环、并行 | 确定性与 agentic 步骤混合 | 设计、状态和测试工作最多 |

官方性能示例说明一个重要趋势：单次简单请求中 handoff/skills/router 可少一次 supervisor 回程；重复请求中有状态 handoff/skills 能复用上下文；多域任务中 subagents/router 通过隔离和并行通常比积累全部 skill 内容更省 token。文档中的调用数是说明性模型，不是所有应用的固定指标，最终要用自己的 trace/eval 测量。

### 模式细节

**Subagents**：主 agent 保存会话记忆，子代理默认每次干净启动。可为每个 specialist 定义独立 tool，也可用单一 dispatch tool；description 是 supervisor 的路由说明。输入要给足任务上下文，输出要压缩成 supervisor 可合并的结果；checkpoint/state inspection 需明确主图与子图边界。

**Handoffs**：工具更新持久 state，middleware 根据阶段切换 system prompt 和 tools，或路由到不同 agent subgraph。状态转换必须校验前置字段；handoff tool 是纯路由还是同时执行副作用要拆清楚。客服教程以 warranty → issue classification → resolution/escalation 展示单 agent 动态配置，并补充返回上一步和消息历史治理。

**Skills**：系统提示只暴露轻量 metadata，agent 需要时调用 `load_skill` 读取完整知识。SQL skills 教程给出 metadata → core content → detailed resources 的渐进披露，以及内存、文件、远程存储、registry/RAG discovery、分页/搜索/层级加载等实现。小 skill 可直接缓存进 prompt，中大型内容更适合按需和分段加载；尺寸阈值只是未校准经验，要用实际 token/质量测试。

**Router**：单目标用 `Command`，多目标并行 fan-out 用 `Send`，结果通过 reducer 汇总再 synthesize。无状态 router 适合独立请求；多轮最简单的做法是把 router 包成有记忆 agent 的 tool。若 router 自身持久化历史，必须处理不同 agent 的语气、上下文选择和并行结果历史。

**Custom workflow**：当流程包含“先确定性分类/验证，再让 agent 探索，最后确定性检查”时，用 LangGraph 表达，而不是让 prompt 隐式承担状态机。

### 三个完整案例的可复用点

- Personal assistant：calendar/email 两个 specialist 由 supervisor 协调；外发邮件加入 HITL；可控制给子代理的会话上下文和返回 supervisor 的结果。
- Multi-source knowledge base：分类 GitHub/Notion/Slack 子问题，`Send` 并行调用 specialist，通过 reducer 收集并合成；需要来源归属和失败降级。
- Customer support：单 agent 按 state 变换 prompt/tools，比把每个步骤都做成 agent 更简单；阶段转换、回退和持久化是核心。

## Retrieval 与 RAG

如果已有 SQL、CRM、文档平台或搜索服务，不必为使用 LangChain 重建知识库；可以把现有查询能力包装成 tool/retriever。需要自建语义索引时，流水线为：

> source → loader → `Document` → splitter → embeddings → vector store → retriever → model

每个组件可替换，但 metadata、chunk 边界、版本/删除同步与访问控制必须贯穿全链路。VectorStoreRetriever 常见 search type 包括 similarity、MMR、similarity score threshold；不同 provider 的分数语义可能不同，不能硬编码统一阈值而不校准。

### 三种 RAG 架构

| 架构 | 优点 | 风险/适用 |
|---|---|---|
| 2-step | retrieval 必定先于 generation，调用上限和延迟更可预测 | 灵活性低；适合 FAQ、文档问答 |
| Agentic | agent 决定何时、用哪个检索 tool、是否继续 | 延迟/成本可变；适合研究、多源工具 |
| Hybrid | 查询改写、召回验证、答案检查形成受控循环 | 复杂度中高；适合对质量有明确门槛的领域 |

评估要拆开：检索相关性/召回、context 是否充分、答案 groundedness、答案正确性。只测最终回答无法定位是召回失败还是生成失败。

### SQL agent 边界

SQL agent 的典型循环是列出表 → 选择相关表 → 获取 schema → 生成并复核 SQL → 执行 → 根据数据库错误修正 → 回答。模型生成 SQL 有固有风险：使用专用只读/最小权限账号，限制 schema/table/row，设置 statement timeout、行数和成本上限，对写语句显式 HITL；不能把“LLM 再检查一次”当作数据库安全控制。

## 长期记忆：跨 thread 的 Store

长期记忆由 LangGraph store 保存 JSON document，使用 `(namespace, key)` 组织；namespace 通常包含 tenant/user/application scope。它与短期 memory 的 checkpointer 不同：前者跨 thread，后者保存单个 thread state。

- 工具通过 `runtime.store.get/put/search` 读写，通过 runtime context 获得可信 user ID。
- store 可配置 embedding index 做语义搜索，也可使用 filter；`InMemoryStore` 仅适合测试，生产使用数据库 backed store。
- 写入记忆是高风险产品决策：只保存可复用、经用户授权的信息；支持 TTL/删除/更正；记录来源和置信度；避免从一次模型推断永久写入身份、偏好或敏感事实。
- namespace 必须服务端构造和校验，防止模型跨租户读取；记忆内容进入 prompt 前还要做最小化和 prompt-injection 防护。

## 逐页覆盖索引

| 页面 | 学习结论 |
|---|---|
| MCP | client/server、HTTP/stdio、stateless/stateful session、tools/resources/prompts、interceptor、progress/logging/elicitation。 |
| Multi-agent index | 为什么/何时使用多代理，五类模式与调用数/token/并行权衡。 |
| Subagents | supervisor-as-tools、无状态 specialist、sync/async、dispatch 设计、输入输出与 checkpoint。 |
| Personal assistant | calendar/email specialists、supervisor、HITL 与上下文/返回值控制的完整案例。 |
| Handoffs | 通过 state 更新行为/路由，单 agent middleware 与多 subgraph 两种实现。 |
| Customer support | warranty/分类/解决/升级的状态机、动态 tools/prompt、回退与历史治理。 |
| Skills | 单 agent 渐进披露专业 prompt/resources，可扩展动态工具与层级 skills。 |
| SQL skills | skill metadata、load tool、middleware、约束 state、存储/发现/分页/搜索等实现选择。 |
| Router | `Command` 单路由、`Send` 并行 fan-out、stateless/stateful 的取舍。 |
| Router knowledge base | GitHub/Notion/Slack 分类、并发 specialist、reducer 汇总与 synthesize 的完整案例。 |
| Custom workflow | 用 LangGraph 组合顺序、分支、循环、并行和 agentic node。 |
| Retrieval | 知识库构建、模块化检索流水线与 2-step/agentic/hybrid RAG。 |
| Knowledge base | PDF → Document → split → embed → vector store → retriever 的语义搜索教程。 |
| Long-term memory | store 的 namespace/key、数据库持久化、语义搜索及 tool 读写。 |
| SQL agent | schema discovery、query checking/execution/error correction 与最小数据库权限。 |

## 延伸

- [[04-Middleware-Context-and-Runtime]]
- [[06-Frontend-and-Generative-UI]]
- [[07-Production-Testing-and-Migration]]