升级模型后，一种故障很明显：请求返回 400。另一种更难发现：请求成功、工具也在运行，但用户长时间看不到进度。Claude Sonnet 5.5 同时改变了请求兼容规则和部分返回内容，迁移不能只替换模型名称。
本文面向维护 Claude Messages API 集成的人，依据 Anthropic 的迁移和提示文档展开。Claude Managed Agents 的迁移范围不同：官方说明只需更新模型名称。通过产品界面使用模型的人，也不需要自行修改下面的 API 参数。
先确定旧模型，而不是复制一份通用清单
从 Sonnet 5 升级，优先检查关闭思考、强制工具调用、历史消息回放、computer use 和 advisor 配对。从 Sonnet 4.6 或更早版本升级，还要检查手动思考预算、采样参数和 tokenizer；从 4.5 或更早版本升级，再检查 assistant prefill 与旧 beta header。
这一区分会影响排查顺序。同样是 token 消耗变化，从 Sonnet 5 升级时 tokenizer 没变；从 Sonnet 4.6、4.5 或 Haiku 4.5 升级，官方说同一文本大约会多出 30% token，具体取决于内容。不能把所有来源模型的变化混成一个统一涨幅。
先记录生产模型 ID、平台、SDK 版本、工具定义、thinking 配置和最后一轮原始响应。后续每次只改一个兼容问题，保留可回滚的旧配置。
400 错误：优先查这三组旧设置
Sonnet 5.5 的 API ID 是 claude-sonnet-5-5。默认启用 adaptive thinking，Claude API 的默认 effort 为 High。旧的 thinking: {"type":"disabled"} 不再被接受；如果要关闭前置思考，改用 between_tools。
但这不是任意组合都有效：between_tools 只支持 Low、Medium、High，不能配 Xhigh 或 Max；其中也不能再附带 display、budget_tokens、block_binding。这种模式不允许在对话中改变 effort。如果需要按轮次调整，使用 adaptive thinking 并核对对应 beta 功能。
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
thinking={"type": "between_tools"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "Summarize the supplied release notes."}],
)
这是请求结构示例，不是生产实测。对于不使用工具、但需要推理的任务，between_tools 会直接作答而不进行前置思考，不能把它当作所有任务的默认优化。
第二组是强制工具调用：tool_choice 的 any、tool 类型会返回 400。改用 auto，在提示中明确工具适用条件；在支持的平台上给必要工具配置 strict: true，并检查 JSON Schema 限制。Strict 保证的是实际调用时的参数形状，不保证一定调用工具。Amazon Bedrock 上该模型不支持 strict tool use，需要应用层校验。
第三组主要影响更早版本：移除手动 enabled thinking budget、非默认 temperature / top_p / top_k，替换 assistant prefill。不要把预算数值直接换算成某个 effort 档位，官方没有固定映射。
HTTP 200 却“沉默”：检查渲染器，不要先加重试
Sonnet 5.5 会把工具调用之间较长的进度说明放进 thinking blocks，较短说明仍可作为 text。Adaptive thinking 的默认 display 是 omitted：块存在，但其 thinking 文本为空。只显示 text blocks 的界面就可能看起来没有进展。
先区分三个层次：请求是否返回、工具循环是否推进、可显示的进度块是否被渲染。无差别重试可能重复执行工具，却没有解决显示问题。
在 adaptive 模式下，display: "updates" 可只返回进度更新，需要 thinking-display-updates-2026-08-18 beta header；summarized 则会把更新与思考摘要一起返回。between_tools 下更新自带摘要，不要加 display 字段。
解析最终答复也要按块类型，而不是访问 content[0].text。工具循环应原样回传全部 assistant blocks，包括空 thinking blocks 与签名。显示给用户的摘要和需要回传的完整协议块不是同一种数据。
历史编辑和平台差异：成功调用不代表保留了全部上下文
Sonnet 5.5 的 thinking blocks 绑定生成模型和此前对话。对于 2026 年 8 月 31 日 00:00 UTC 起创建的账户，官方默认执行前缀一致性检查：改过更早的消息、system prompt 或工具，再回放旧块，可能触发 400。
更稳妥的集成方式是追加消息，不去修改已经产生 thinking blocks 的历史前缀；需要更新指令或工具时，核对 mid-conversation 功能。跨模型时，不可读取的 thinking blocks 可能被 API 丢弃，但请求仍然成功。不要把 HTTP 200 当作“原有推理上下文全部保留”的证明。
Computer use 也有平台差异：Claude API 与 Google Cloud 需要 computer_toolset_20260801；Amazon Bedrock 仍接受 computer_20251124。如果使用 advisor，旧的 Sonnet 5 或 Opus 4.8 等配对需要检查支持列表，返回的建议也可能是加密块。不要把一份 Claude API 示例直接搬到所有云平台。
一次迁移排错：不要同时改模型、参数和消息历史
下面是基于官方接口规则构造的排错案例，不是生产事故记录。假设一个旧集成原先使用 Sonnet 5：关闭思考，强制调用查询工具，界面只读取 text blocks；应用还会在每轮结束后把历史压成一段摘要。这个集成直接改成 Sonnet 5.5，可能接连遇到三种不同问题。
第一步，先解决请求拒绝。 旧请求同时带有 thinking.type=disabled 和 tool_choice.type=any。只修其中一个，另一个仍可能使请求失败。先留住原始错误响应，在隔离环境改为有效的 thinking 配置，再把工具选择改为 auto。不要为了尽快得到 200，把所有工具和历史一并删除：那样只是测试了一个新请求，没有证明原来的工具工作流可用。
第二步，单独验证工具调用。 Auto 不是“必然调用”。测试输入应确实需要查询工具，工具返回一个可辨认的测试标记；验收时同时核对调用名称、参数、返回内容是否进入最终答复。若任务依赖最新库存，模型没查工具却写出库存数，不能因为响应成功而通过。需要应用强制保证的业务前置条件，仍应由应用检查和拦截，而不是寄希望于 strict 工具参数。
第三步，修复进度与历史。 请求已成功，但界面没有说明，先查看原始 content 和流式事件。把可展示的进度更新送到显示层，同时保留完整协议块供下一轮回传；不要用一个经过“去空块、只留文字”的数组承担这两种职责。长会话压缩也要单独测试，不能把旧集成的任意历史改写当作新模型支持的压缩协议。
这三个阶段的停止条件不同：请求有效、工具完成、历史可继续。前一个通过，并不替后一个背书。实际响应格式与 SDK 版本应以当前文档为准，案例中的步骤不是可直接复制的完整适配器。
为迁移日志留下能区分故障的证据
应用日志至少应能回答五个问题：用了什么模型和 thinking/effort；哪个请求及工具调用出了问题；停止原因是什么；哪类 content block 出现过；这次执行是否已经产生副作用。涉及签名、客户数据和工具凭据的原始块需要访问控制，不能直接写入公开日志。
| 观察到的现象 | 先检查什么 | 还不能据此断言什么 |
|---|---|---|
| 请求返回 400 | 完整错误字段、旧 thinking 和 tool_choice、平台差异 | 模型的任务能力下降 |
| 200，但没有可见进度 | block 类型、display 配置、渲染与流式解析 | 工具没有运行 |
| 工具返回成功，最终答复没用结果 | tool_result 对应关系和完整下一轮消息 | 工具数据已经被模型正确采用 |
| 修改历史后才失败 | 签名块、前缀变化、账户和跨模型规则 | 重试一次会解决 |
| 回复在任务完成前结束 | stop_reason、max_tokens、工具结果和任务状态 | 收到文字就是完成 |
日志的目的不是保存更多字，而是防止错误的恢复动作。尤其是有副作用的工具：执行已经成功但显示层断开时，自动重新跑整轮可能造成重复写入。应用需要依据自己的业务事务状态判断是否重试；模型迁移不会替应用提供去重或回滚。
用三段回归，决定是否切换生产流量
第一段只测协议：无工具文本请求、一次真实工具循环、进度渲染、拒绝与 max_tokens 结束原因。第二段测历史：追加一轮、跨模型、应用确实支持的压缩流程，以及旧存档的重放。第三段才测业务：同一输入完成一项有验收标准的任务，记录通过率、时间、token 与返工。
可以先用只读工具和测试数据。只有确认不会重复写入、不会丢掉业务字段、可以回滚后，才扩大到有副作用的执行任务。Effort 校准另见本组的设置文章；它不能替代接口兼容检查。
FAQ
只换模型 ID 就够了吗？
Messages API 不一定。需要按起始模型检查兼容项；Claude Managed Agents 则有不同的官方迁移说明。
Strict 工具能替代强制调用吗？
不能。它约束已发生调用的参数，应用仍要处理模型未调用工具的分支。
空 thinking block 可以删掉吗？
显示层可以不展示空文本，但工具循环应按官方协议原样回传，不能为了界面简洁修改签名块。
没有 400 就算迁移完成吗？
不算。还要验证进度、历史、工具副作用和实际交付质量。