升級模型後，一種故障很明顯：請求返回 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 就算遷移完成嗎？
不算。還要驗證進度、歷史、工具副作用和實際交付質量。