千里之行，始于足下

官方原话：Trim / Remove 的问题在于剔除消息时可能丢失信息，因此一些应用受益于用 chat model 对历史做摘要。Agent 中直接使用内置model="gpt-5.4-mini", # 用便宜的小模型做摘要trigger=("tokens", 4000), # token 达到 4000 触发keep=("messages", 20), # 摘要后保留最近 20 条],← 多轮 + 摘要后依然记得摘要中间件可以指定一个更小更便宜的模型（如上例的），与主力模型解耦。

目标不是"把信息塞满"，而是三个"对"——

中间件 API 本身不复杂，真正的难点在——理解执行顺序、状态合并规则、以及每个中间件的适用边界。下面六个点是最容易卡住的地方。

Hook（钩子）是框架在执行流程的固定位置预留的"回调点"。你把函数挂上去，框架跑到那儿就会调用它。这是软件工程里非常经典的设计模式——Web 框架（Django 中间件、Express middleware）、前端路由守卫、Git hooks，都是同一个思想。# ===== 装饰器写法：用 state_schema= 参数声明 =====# ===== 类写法：用类属性 state_schema 声明 =====# 调用时传入自定义状态})

层中间件排在这里的理由① 安全PII 脱敏必须在最外层——敏感信息一旦流进内层（限流计数、日志、摘要）就到处都是了。脱敏永远第一。② 资源限流 + 工具筛选越早拦截越省钱。如果先重试 3 次再限流，那 3 次的钱已经花出去了。③ 容错Fallback 在 Retry外Retry 是对同一个模型重试；只有重试都失败后，才该由外层 Fallback 换模型。顺序反了会导致一失败就换模型，永远不重试。④ 工具容错ToolRetry贴着工具执行层，只重试工具、不牵连模型调用。⑤ 治理。

这一章快速过一遍另外内置中间件。它们没有第 2 章那四个常用，但在特定场景下是。按"限流 → 容错 → 选择 → 模拟 → 上下文 → 文件 → 子智能体"的顺序展开，每个都给参数表 + 可运行示例。

触发 → 裁剪 → 总结 → 保留最近消息 → 用摘要替换早期历史内置类型只覆盖通用场景。真实业务里的敏感信息——API Key、手机号、身份证号、内部订单号、病历号——都需要自己定义。detector函数形态的价值在于——可以做校验逻辑，不只是模式匹配。下面的例子会剔除掉"看起来像但不是真 SSN"的号码。import re# 校验：前三位不能是 000、666，也不能落在 900-999"start": match.start(), # ← 必填：命中位置。

中间件（Middleware）是一组挂在执行流程固定位置的钩子函数（hook），用于在 Agent 运行的各个阶段拦截、检查、修改行为。它以列表形式传给*,middleware: Sequence[AgentMiddleware] = (), # ← 就是这里...# 官方释义：A sequence of middleware instances to apply to the agent.middleware=[ # ← 一串中间件，顺序很重要（第 4 章讲）

外部 API 调用、纯计算、联网检索、读写状态。注意每个工具的 docstring 都写清了"什么时候用"。# tools.py# ---------- 工具 1：天气查询（模拟外部 API，可能失败）----------@tool"""查询指定城市的当前天气。当用户询问任何城市的天气、气温、是否下雨/下雪、穿衣建议时使用。参数 city 为中文城市名，如'杭州'、'北京'。

官方定义：——在工具或节点内部主动推送任意数据（进度、日志、部分结果）。这是最灵活的一种，常用于长时间运行的工具。# ① 在 Agent 的工具里用 runtime.stream_writer 推送进度@toolwriter(f"正在查询 {city} 的数据...") # ← 立即推送给用户# ... 耗时操作 ...writer(f"数据获取完成，正在解析")# ② 消费端print("进度:", chunk["data"])# 进度: 正在查询 杭州 的数据...

结构化输出走工具调用路径，所以会在对话历史里留下一条 ToolMessage。默认内容是——这对用户毫无意义，还占据上下文。让你把它换成一句人话。tools=[],",),# ===== 设置了 tool_message_content 的历史 =====# ✅ 语义清晰# ===== 未设置（默认）的历史 =====# ⚠ 结果被重复写进了历史，白白多占 token① 用了做多轮会话时——历史会被反复重放，这条消息每次都占 token；

系统提示词是 Agent 的。它在每次调用模型时被放在消息列表最前面，——这跟"用户提示词"只在第一轮出现是完全不同的。实践中，它是性价比最高的一处调优点。如果提示词需要依赖（用户姓名、当前时间、会员等级），用中间件实现——LangChain 提供了装饰器，按装饰的函数接收一个1. 基于用户等级/身份动态调整语气2. 基于当前时间/日期动态调整3. 基于会话历史动态注入上下文4. 基于用户偏好动态调整输出格式。

一个请求会经过多个 Agent（主管 → 研究员 → 撰稿人）。没有名字，trace 里全是 "agent" 节点，排查时根本分不清是谁慢、谁错。：主管 Agent（supervisor）把各个专家 Agent 包装成工具来调用。当一个 Agent 作为节点嵌入更大的图时，元组返回，名字让你能区分事件来自哪一层。这是 v1 官方推荐的。——名字起得不好，路由就会错。给编译出来的图起个名字。流式输出时，事件会以。会成为其状态与事件的。

ToolRetryMiddleware 是一个“防故障”层级，它负责在 AI 调用外部工具（如 API、数据库）失败时，自动、安静地重新尝试调用，直到成功或达到最大重试次数，从而提升系统的稳定性和用户体验。max_retries=3, # 首次失败后再试 3 次（共 4 次）backoff_factor=2.0, # 每次等待 ×2initial_delay=1.0, # 第一次等 1 秒max_delay=60.0, # 退避上限，防止等太久。

元素含义类比invoke()执行一个封装好的复杂任务按下一个“启动”按钮input你要问的问题或要处理的数据你放进机器里的原材料config控制这次执行过程的额外设置机器面板上的旋钮和开关（如速度、模式、记录日志）意思是：“启动这个任务，传入我的数据（input），并按照这些额外设置（config）来执行它。这个模式通常出现在一些现代 AI 框架或库中（比如 LangChain、某些 LLM API 封装库、或者自定义的流式处理框架），用于实现流式（streaming）数据生成。参数。

时，先实例化模型对象再传入。

—Agent 是一个能够调用工具、观察结果、并自行决定下一步的模型。Agent 循环的完整流程（以"查天气 + 发邮件"为例）注意关键分支：模型自己决定"再调一个工具"还是"给最终答案"——这就是 Agent 与普通链路的本质区别。

LLM 天生输出的是自然语言文本——为聊天而生，却不适合被程序消费。从一段简历文本里抽出姓名/邮箱/技能列表把用户评价分类成 positive/negative生成一份可入库的订单对象。结构化输出就是让模型"按契约输出"，直接返回可以被程序使用的类型化数据。最小可运行示例（模型层）# ① 定义数据契约：我要什么形状的数据"""一个人的基本信息。""" # ← 类文档字符串会被送进模型的 schema 描述name: str = Field(description="姓名")

前面四章讲的是「能做什么」，这一章讲「怎么做才不会在生产环境翻车」。全部来自真实项目的经验教训，可以直接当 Code Review 清单用。

从「工具是什么」到「怎么写好一个工具」，再到「如何让模型必须用某个工具」—— 一份可以直接当教程、也可以当检索手册的中文讲义。所有 API 与示例均对照 LangChain 官方文档最新版（v1.2+）编写。

历史越长，token 越贵、延迟越高、还会撞上下文窗口上限。（滑窗裁剪）、摘要压缩（summary）、（精确删除）。是一个用于管理 LLM 对话历史长度的实用工具/函数。它通过自动删除列表中较早的消息，确保总 Token 数不超过模型限制，同时尽量保留对当前对话最重要的信息（通常是最近的消息和系统提示）。如果你是在某个具体框架（如chainlit）或代码中看到这个函数，欢迎告诉我具体上下文，我可以为你进一步分析。