Anthropic GitHub 修复 LangChain 1.5.3 中两项隐藏故障

LangChain 于 2026 年 7 月 28 日发布 1.5.3 版本时，Anthropic 集成获得了两项针对性修复。这次 Anthropic GitHub 更新解决了可能以 HTTP 400 错误中断 Claude agent 循环的故障。两项改动都没有增加可见的模型能力，但均保护了 agent 所依赖的消息历史。

其中一项修复确保 LangChain 处理流式签名数据时保留空的 thinking 字段。缺少该字段时，原本有效的 Claude 响应在下一次模型调用中被重放时可能变成无效消息。第二项修复则会在将系统消息内容块发送给 Anthropic 前，移除 LangChain 专有标识符。

这一组合使其不只是一次常规补丁。该版本揭示了 agent 基础设施中的持续冲突：框架希望采用统一、可移植的消息格式，而模型提供商则执行更严格的 API schema。OpenAI、Google、Anthropic 及其他提供商都在最终请求边界施加各不相同的规则。

LangChain 正处于这些格式之间。它的抽象帮助开发者切换模型并组合工具，但每次转换也都会增加有效状态丢失的风险。1.5.3 版本表明，一个缺失的空字符串或一个额外的标识符，就可能让原本正常运行的 agent 停摆。

LangChain Anthropic 1.5.3 有何变化

LangChain Anthropic 1.5.3 修复了两条消息转换路径，它们此前会生成被 Claude API 拒绝的请求。

官方 Anthropic 发布说明列出了相较 1.5.2 版本的两项修复：一项涉及流式 thinking 块，另一项则在传输前清理系统消息内容。

流式修正针对涉及自适应 thinking 的特定事件序列。自适应 thinking 让 Claude 在提供商配置的限制内，决定应用多少内部推理。API 可以在可见回答之外，返回结构化 thinking 内容和加密签名。

在流式传输中，这些结果不一定以一个完整对象的形式到达。LangChain 会接收多个事件并将其合并为 AIMessage，即其标准化的模型响应表示。随后，该组装后的消息可能成为另一项请求的一部分。

据报告，当一个 thinking 块包含空字符串但仍接收到 signature_delta 时，故障就会出现。签名增量是携带 thinking 块签名数据的流式片段。由于没有可添加的推理文本，因此不会随后出现 thinking_delta。

LangChain 最初丢弃了空块状态。之后，它从签名事件重建该块，生成只包含 type 和 signature 字段的对象。然而，必需的 thinking 键缺失了。

该消息保存在应用内部时看似无害。只有当 agent 将该历史重放给 Claude 时才会失败。随后 Anthropic 会拒绝该请求，因为 thinking 块缺少必需字段。

流式修复在处理签名增量时使用 setdefault("thinking", "")。该操作会保留已有值，或在键缺失时插入空字符串。因此，它能保留提供商所期望的对象结构，而不会凭空生成推理文本。

系统消息修复则解决了相反的问题。LangChain 不是丢失必需字段，而是转发了不受支持的字段。

LangChain v1 内容块可以包含内部 id。该标识符帮助框架一致地表示和跟踪内容。Anthropic 的系统消息 schema 不接受在该位置出现同一字段。

在 1.5.3 版本之前，_format_messages 可以转发基于列表的 SystemMessage 内容，却不会收窄其中的每个文本块。通过 create_text_block() 创建的块因此可能会将其内部标识符带入出站负载。

Anthropic 会以“不允许额外输入”的错误拒绝该请求。同一格式化路径还会通过 get_num_tokens_from_messages 影响 token 计数。应用可能仅在估算请求大小时，就在生成前失败。

系统块修正将共享格式化辅助函数应用于系统文本块。它保留 type、text、cache_control 和引用等受支持属性，同时移除不受支持的元数据。

这些改动在代码量上很小，但运营影响更大，因为它们都发生在 agent 应用反复使用的边界上。一项在流式传输期间保护响应状态，另一项则在传输前清理应用状态。

Anthropic GitHub 修复为何对 Agent 循环至关重要

关键故障具有延迟性：LangChain 可以接收 Claude 的响应并将其保存，却只在下一轮发现状态已损坏。

基础聊天机器人可以发送一个提示词并显示一个回答。Agent 循环则执行更长的序列：模型选择工具，应用执行工具，模型随后接收其先前消息和工具结果。

这种重放需求使消息保真度至关重要。应用不能只安全地保留可见文本。为了正确延续对话，它可能需要保留结构化工具调用、thinking 块、签名和提供商专有元数据。

Anthropic 的扩展 thinking 指南说明，thinking 块可以携带签名。当这些块进入后续请求时，应用必须保留其相关结构。因此，框架充当的是状态序列化器，而不只是文本包装器。

最初的 bug 报告提供了无需真实 API 调用的确定性复现方式。它模拟了内容为空的 thinking 块开始事件，随后接收一个签名增量。聚合后的结果缺少 thinking 键。

这一遗漏未必会破坏首次流式回答。用户可能收到正常响应，agent 也可以执行其选择的工具。故障会在下一次请求包含该畸形的历史消息时出现。

这种时序使该 bug 更难诊断。开发者可能会归咎于工具输出、第二个提示词或检查点恢复。实际缺陷则是在前一轮中 LangChain 组装流式消息时进入对话的。

持久化检查点进一步提高了风险。检查点机制会保存 agent 状态，使工作流可以在中断后恢复，或跨进程继续运行。如果它保存了畸形块，重启 worker 并不能修复对话。

由于无效对象保留在历史中，agent 可能反复遇到同一拒绝。恢复可能需要删除或转换已保存状态，而不仅仅是重试失败请求。

设想一个要求 Claude 检查代码仓库的编程 agent。Claude 选择了搜索工具，框架则保存 assistant 的流式消息。工具返回匹配文件，但后续调用在 Claude 分析这些文件之前就失败了。

搜索操作本身没有问题。Agent 失败的原因是，被重放的 thinking 块带有签名，却没有空的 thinking 字段。1.5.3 版本重建了第二次调用所需的结构。

客服 agent 也会呈现相同模式。它可以成功检索客户记录，但在要求 Claude 解读结果时失败。即便模型和数据源仍然可用，该缺陷仍会表现为不稳定的业务工作流。

系统消息问题可能更早暴露。许多应用通过可复用内容块构建系统指令。这些块在经过通用 LangChain API 后，可能携带框架标识符。

如果 Anthropic 拒绝该元数据，模型就无法开始生成。由于 token 估算使用相同的格式化逻辑，它也可能失败。因此，规划代码可能在应用提交预期的完成请求之前就停止运行。

Anthropic 流式修复与系统清理改动处理的是相反方向的数据流。流式处理将提供商事件转换为 LangChain 对象；消息格式化则将 LangChain 对象转换回提供商请求。

二者共同保护了一次往返过程：Claude 生成结构化状态，LangChain 将其保存，应用随后再次将其返回。Agent 的可靠性取决于该循环能在需要处保持无损，并在必要处执行严格限制。

一个框架 Schema 面对更严格的提供商边界

LangChain 必须保留有意义的提供商状态，同时移除框架元数据，而这两个目标可能在同一段对话中发生冲突。

核心矛盾并非 LangChain 与 Anthropic 之间的对立，而是可移植性与精确 schema 合规性之间的关系。LangChain 提供共享消息抽象，而 Anthropic 则验证其 API 所期望的请求结构。

标准化内容块可以包含对整个框架都很有用的信息。开发者可能附加标识符、引用、工具信息或缓存控制。提供商适配器随后会将这一通用表示转换为更严格的传输格式。

这一设计有助于应用在不同集成之间切换。团队可以针对 Claude、OpenAI 模型或 Google 模型，使用相似的编排模式。但最终负载仍必须遵守每个提供商各不相同的契约。

1.5.3 版本展示了两种可能的适配器错误。

第一种是过度过滤或重建不完整。LangChain 丢失了空字段的存在性，因为在普通应用逻辑中，空字符串通常看起来等同于缺失值。Anthropic 的 schema 则将这两种状态区别对待。

空的 thinking 值表示该字段存在，但不含文本。缺失的键则表示该对象不满足预期结构。语义内容为空，但结构上的区别仍然重要。

第二种错误是过滤不足。LangChain 允许内部 id 通过系统文本块离开框架。该标识符在 LangChain 内部可以有效，但在 Anthropic 的边界处仍可能无效。

因此，正确的适配器行为看起来并不对称。它必须保留一个表面上为空的提供商字段，同时删除一个表面上有用的框架字段。诸如“移除空值”或“保留所有元数据”这样的通用规则，都会在其中一侧失效。

这也是提供商适配器仍是重要工程组件的原因。它们不只是重命名属性，还要协调关于身份、状态、流式传输、验证、工具和对话重放的不同假设。

直接使用 SDK 的用户面对的转换层更少，因为他们会根据单个提供商的原生类型构建请求。这种更窄的方法可以减少歧义，但也会将更多应用逻辑绑定到单一 API 表示。

框架用户获得了组合能力和可移植性，但也继承了适配器风险。框架必须随着每个提供商更新模型、流式事件、内容类型和验证行为而更新。

即使具体字段不同，OpenAI 和 Google 集成也面临相关压力。每个提供商都定义了自身可接受的内容块和工具消息规则。共享抽象无法在网络边界抹平这些差异。

此版本并不能证明直接使用 SDK 在任何情况下都更安全。直接应用同样可能损坏历史记录，或发送不受支持的字段。但它确实表明，抽象层只是转移责任，而非消除责任。

LangChain 需要负责判断哪些细节具有可移植性，哪些属于特定提供商。应用仍需负责升级、回归测试、已存储状态兼容性和可观测性。

LangChain Anthropic 此次发布也凸显了为何架构错误值得在生产环境中受到重视。HTTP 400 响应通常看似意味着开发者使用有误。但在这些案例中，应用即使使用了文档所述的框架对象，仍可能生成被拒绝的负载。

这一区别会影响事故响应。对无效请求在不改变其结构的情况下重试，只会浪费时间，并可能加剧队列积压。监控应保留提供商的验证消息，并标识受影响的内容块索引。

团队还应区分首次调用失败与重放失败。首次请求报错通常指向提示词构造或系统消息格式化问题。工具执行后发生的错误，则表明可能与已存储的助手状态或工具结果排序有关。

这种分类不能替代调试，但能缩小排查范围。当 Anthropic 围绕结构化消息请求失败时，1.5.3 版本为开发者提供了两条可供检查的具体转换路径。

补丁范围有限，既有状态仍是风险所在

升级可以避免文档中描述的转换问题，但并不能自动证明每一段已保存的对话都有效，或每条部署路径都使用了新版本的软件包。

流式修复针对的是一个特定序列：空的自适应思考块之后出现签名数据，但没有 thinking delta。那些从未启用相关思考行为的应用，可能不会遇到这一问题。

系统消息修正同样有明确范围。它会清理系统消息中的文本块，同时保留受支持的属性。根据已合并的改动，非文本系统块会原样通过。

这样的有限范围适合补丁版本发布。大范围重写消息可能改变正常工作的应用，或移除其他路径所需的元数据。聚焦式修复可以降低这种兼容性风险。

不过，聚焦的代码变更也需要聚焦的验证。团队应复现自己的消息模式，而不是把成功安装软件包视为充分证据。

第一个测试应通过真实的代理循环流式传输 Claude 响应。工作流至少应执行一次工具调用，并继续进行下一次模型调用。这可验证暴露 thinking 字段缺陷的重放路径。

开发者应在下一个请求前检查组装完成的助手内容。带有签名的思考块即使值为空，也应保留 thinking 键。日志必须避免暴露敏感推理内容或用户数据。

第二个测试应使用与生产环境相同的辅助工具构造基于列表的系统消息。它应包含一个内部标识符，以及诸如缓存控制等受支持属性。发往 Anthropic 的负载应移除该标识符，同时保留受支持的数据。

令牌计数需要单独断言。系统消息报告发现，get_num_tokens_from_messages 复用了存在问题的格式化器。仅进行生成测试，可能会遗漏预算、路由或预检验证中的故障。

已保存的检查点带来了另一种不确定性。已合并的拉取请求改变了新流事件的组装方式，但并未声称会迁移应用中已经存储的每一个格式错误的 AIMessage。

使用持久化代理状态的团队，应抽样检查升级前创建的对话。他们可以识别包含签名但缺少 thinking 的思考块。这些记录可能需要受控修复，或重新开启对话。

任何迁移都应保持谨慎。添加空值符合已记录的错误修正，但生产数据可能包含其他块结构。团队应针对自身准确的软件包版本和提供商设置进行验证。

依赖解析也可能掩盖更新。应用可能声明了宽泛的版本范围，但锁定文件仍保留 1.5.2。另一个服务可能基于不同的锁定文件或缓存的容器层构建。

运行时遥测应记录已安装的 langchain-anthropic 版本。这一证据比仅检查源清单更可靠。在运营人员关闭事故前，分布式工作节点应报告相同的已解析版本。

发布页面称，1.5.3 版本紧随 1.5.2，并包含上述两项修正。它并未给出性能基准、延迟改进或新的模型质量声明。开发者不应自行推断这些结果。

同样也没有证据表明，这些修复消除了所有 Claude 流式边界情况。它们覆盖的是具有可复现路径的已报告故障。其他事件组合、内容类型或提供商变更仍需测试。

该补丁的测试证据令人鼓舞，但范围有限。系统消息拉取请求在提交说明中报告了 241 个通过的单元测试。GitHub 随后在合并过程中显示了更广泛的检查状态，但这不应被理解为通用的生产验证。

流式改动同样包含针对缺失字段的回归覆盖。确定性测试很有价值，因为它无需依赖提供商可用性即可隔离框架行为。但它仍无法代表每一种实际运行中的代理配置。

因此，应持审慎看法。1.5.3 修正了两个已确认的缺陷，但可靠性取决于整个消息生命周期。存储层、自定义序列化器、中间件和旧检查点都可能重新引入格式错误的状态。

Anthropic 流式修复后开发者应作出的调整

最安全的应对方式是审慎升级，然后执行与真实生产流量相匹配的重放、系统消息和检查点测试。

首先确认每个发送 Claude 请求的进程中安装的软件包版本。检查本地开发环境、持续集成、后台工作节点和已部署的容器。版本混用可能导致对话历史不一致。

接下来，为仅含签名的 thinking delta 添加回归用例。预期聚合后的块必须包含 thinking: ""。随后测试应重放这条消息，并验证负载构建成功。

即使当前模型很少发出这种序列，这一用例也很重要。当代理持续运行时，罕见的结构性事件也可能主导可靠性问题。低频缺陷会在数千次工具调用中显现。

为通过 LangChain v1 辅助工具创建的系统文本块添加第二个测试。包含内部块标识符、受支持文本，以及应用使用的任何缓存控制字段。针对最终提供商负载进行断言。

不要止步于单元测试。让一段预发布环境对话通过完整的代理图执行。包括流式传输、工具调用、检查点持久化、进程恢复，以及再次向 Claude 发起请求。

这一序列会覆盖数据所有权发生变化的边界。Anthropic 客户端发出事件，LangChain 对其聚合，检查点将其保存，之后的工作节点再对其进行格式化。

可观测性应捕捉结构化信息，同时避免记录敏感内容。实用字段包括块类型、字段存在情况、消息位置、软件包版本和提供商错误类别。完整的思考文本不应成为常规应用日志。

对于 HTTP 400 响应，应尽可能保留提供商的字段路径。诸如 messages.1.content.0 的位置指向重放的助手状态。位于 system.0 下的位置则指向系统内容格式化。

应用应避免对架构验证失败进行盲目重试。相同的无效负载通常还会再次失败。重试策略应将暂时性的传输错误与确定性的请求错误区分开来。

检查点所有者应制定恢复策略。一种选择是使受影响的对话失效并重新开始。另一种是经审查的迁移，仅在准确识别的思考块中恢复缺失的空字段。

正确的选择取决于保留需求和审计要求。客服工作流可能需要保存其对话记录。短期编码会话则可以安全地在摘要上下文下重新开始。

评估框架的团队也应调整标准。模型支持不仅仅是可用类的清单，还包括流式传输、工具、消息重放、令牌计数、缓存和持久化方面的保真度。

直接集成 SDK 仍是一个有价值的对照方案。如果应用只使用 Claude，并且需要严格控制原生消息类型，较少的转换可能简化调试。这种选择会牺牲部分框架级可移植性和编排能力。

当应用受益于共享接口、模型路由、图执行或现有框架组件时，LangChain 集成更有意义。1.5.3 并未决定这一取舍，它澄清了随之而来的适配器责任。

未来几个月有三个信号值得关注。

第一，关注涉及思考块、签名或重放工具对话的新报告。如果问题追踪器保持安静，将增强人们对 anthropic 流式修复已覆盖所观察序列的信心。相关故障则表明存在更广泛的重建问题。

第二，关注 LangChain 跨提供商内容块规范化的变化。系统消息缺陷源于内部标识符与提供商架构之间的不匹配。更多共享清理工作将表明维护者正在跨集成解决这一模式。

第三，关注 Anthropic 的架构和流式文档中关于可接受思考内容或系统内容的变化。即使框架代码保持不变，提供商一侧的演进也可能使既有假设失效。

对于当前使用 Anthropic GitHub 集成的开发者，实际行动很明确：升级、验证已解析版本，并重放一个真实的工具调用工作流。然后在假定补丁已修复存储状态之前，检查旧检查点。如果代理依赖长对话，应将消息形状回归测试纳入每一次提供商更新。