MCP、多代理、检索与长期记忆

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

总体判断

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

优先顺序通常是：单 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 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 是用户交互，不应自动代答敏感字段。

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

五种模式

官方性能示例说明一个重要趋势：单次简单请求中 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 架构

评估要拆开：检索相关性/召回、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 防护。

逐页覆盖索引

延伸

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