LangChain 开发实战

短期记忆让同一段会话的多轮对话接得上。本文讲清实现原理——Agent state 保存 messages、checkpointer 在每步后存检查点、thread_id 隔离会话；给出三步实现：创建 checkpointer、传给 createAgent、invoke 时带同一 thread_id。随后用两种持久化器实战：基于内存的 MemorySaver（进程内有效、重启丢失），以及基于外部存储介质的 SqliteSaver（checkpoint 落到 SQLite 文件，跨进程/重启保留，可直查 checkpoints/writes 表），并用「新实例模拟重启」做对照验证。文末附两者对比、实践要点与 Python 对应写法。

大模型本身无状态，记忆是一套「外部存储 + 检索拼装 + 更新策略」的工程机制。本文先用真实调用演示没有记忆时 Agent 会忘记上一轮，再讲清记忆的价值；随后按四个维度梳理分类——作用范围（短期 thread / 长期 cross-thread）、内容类型（语义 / 情景 / 程序性）、写入时机（热路径 / 后台）、组织形式（Profile / Collection）；最后讲 LangChain 的管理方式：以 Agent state 的 messages 为工作记忆，短期用 checkpointer + thread_id，长期用 store + namespace + key，并用截断/摘要/清理/检索控制上下文。短期与长期记忆的具体实现留待后续文章。

demo-15 讲了四个最常用的中间件，这篇把剩下的 12 个内置中间件各跑一个最小示例，并按用途分为六组：可靠性（toolRetry / modelRetry / modelFallback / toolError）、限流边界（toolCallLimit / modelCallLimit）、上下文（contextEditing）、动态行为（dynamicSystemPrompt）、工具治理（llmToolSelector / toolEmulator / piiRedaction）、厂商能力（providerToolSearch）。每个都给出 JS 用法与实测效果，另附 3 个厂商专属中间件（Anthropic/Bedrock 提示词缓存、OpenAI 内容审核）的介绍、分组对比表和 Python 对应写法。

中间件用法统一——import 后放进 createAgent 的 middleware 数组。本文挑四个最常用的内置中间件逐个上手：summarizationMiddleware 在对话超长时自动摘要、保住上下文；humanInTheLoopMiddleware 让敏感工具执行前暂停等人审批，并用 Command 恢复（批准/修改/拒绝）；piiMiddleware 在发给模型前检测并脱敏邮箱、卡号等隐私信息（block/redact/mask/hash）；todoListMiddleware 给 Agent 装上 write_todos 工具做多步规划并把清单同步到 result.todos。每个都附用法、关键参数与实测效果，另含对比表和 Python 对应写法。

中间件是挂在 Agent 循环上的可插拔钩子，用来处理日志、重试、限流、脱敏、审批等横切关注点，不改 Agent 内部代码即可定制行为。本文讲清中间件的概念、六个生命周期钩子（beforeAgent/beforeModel/wrapModelCall/afterModel/wrapToolCall/afterAgent）及执行顺序，梳理它的作用，并把内置中间件按上下文管理、可靠性、流程控制、安全合规、动态行为、能力扩展六大类做介绍，最后附 Python 对应写法。具体常用中间件的用法留待后续文章。

Agent 返回结构化结果时，createAgent 的 responseFormat 有两种策略：toolStrategy 借「隐藏工具调用」产出，兼容性最好；providerStrategy 走厂商原生 json_schema，约束最强但需厂商支持。本文讲清两者原理与选项（toolMessageContent、handleError、多 schema 自选形状、strict），并演示如何直接给 schema 让框架按模型能力自动选择，最后附 Python 对应写法与选型建议。

介绍如何用 LangChain 的 createAgent（Python 的 create_agent）创建 Agent，并演示 invoke、stream（messages/updates）、streamEvents 及基于 checkpointer 的多轮记忆。

从 Zod 是什么讲起，介绍结构化输出中可选字段（optional vs nullable）的差异，以及枚举、嵌套、判别联合等高阶用法，并指出 refine/transform 与顶层 union 的坑。

对比提示词+手动JSON.parse的老办法与基于 schema 的结构化输出新方案，涵盖 withStructuredOutput、Agent responseFormat 及 Python 实现。

从什么是 tool、为什么需要、怎么实现到调用过程，讲透 LLM 工具机制。

讲清楚 LangChain 的 content block：它和 content 的关系与区别、为什么要引入、支持哪些类型（文本/图片/音视频/工具调用等），以及用标准块传递图片等多模态数据的几种写法和常见坑。

讲清楚多轮对话的本质（每次带上历史），并给出三种实用的历史压缩方案：滑动窗口截断（trimMessages）、摘要压缩、以及推荐的混合方案；另附「压缩对缓存命中的影响」实测分析与检索式/结构化记忆思路。

讲清楚 LangChain 中消息是什么、结构长什么样、有哪些种类（系统/用户/助手/工具等）、四种表示形式（类实例/MessageLike/lc 序列化/StoredMessage），并以工具调用为例演示消息在 AI 与 Tool 之间流转的完整过程。

系统介绍 LangSmith：它是什么、为什么需要、如何创建 API Key 并配置环境变量，以及如何查看调用链。含可运行示例与变量名、网络超时等常见坑的说明。

讲清楚 LangChain JS 中 invoke、stream、batch 三种调用方式的差异：各自的输入参数、返回值结构与适用场景，并澄清 JS 中不存在 ainvoke/astream/abatch 的常见误区。

系统梳理 LangChain 初始化聊天模型时的主要参数：连接与身份、生成与采样、输出控制、可观测与工程、运行时高级能力五大类，含作用说明、调参经验与别名厂商差异。

讲清楚 LangChain 的 initChatModel：它是什么、为什么需要、有哪些优势，以及从基本用法到运行时动态覆盖的完整使用方式（含 DeepSeek 示例）。

讲清楚 ChatOpenAI 兼容写法的本质：用统一客户端 + 可配置 baseURL 驱动不同厂商模型，以及它为什么成为事实标准、具体如何实现（含 DeepSeek 示例）。

手把手演示如何用 LangChain 的 @langchain/deepseek 读取 DEEPSEEK_API_KEY 环境变量并调用 DeepSeek API，含流式输出、多轮对话与版本兼容避坑。