遷移至 Claude Sonnet 5.5

本指南列出從 Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Sonnet 4、Claude 3.7 Sonnet 或 Claude Haiku 4.5 遷移至 Claude Sonnet 5.5 時所需的程式碼變更。請先閱讀前兩個章節，然後往下閱讀至您目前模型對應的章節。遷移檢查清單依起始模型列出所有變更。

Claude Sonnet 5.5 的價格與 Claude Sonnet 5 相同。請參閱 Claude 定價。關於其「context window」（上下文視窗）與輸出限制，請參閱 Claude Sonnet 5.5 模型頁面。關於功能與提示撰寫，請參閱 Claude Sonnet 5.5 的新功能和提示 Claude Sonnet 5.5。

向 Claude Sonnet 5.5 傳送請求

此請求可直接在 Claude Sonnet 5.5 上運作。它設定了「effort」（努力程度）等級，而各 SDK 分頁會依區塊類型讀取回覆。它省略了五項會傳回 400 錯誤的設定：思考預算、取樣參數、助理預填、強制工具選擇，以及 thinking: {"type": "disabled"}。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

預設會執行思考

在 Claude Sonnet 5.5 上，未包含 thinking 欄位的請求會以「adaptive thinking」（自適應思考）執行，thinking: {"type": "adaptive"} 亦同。在 Claude Sonnet 4.6 及更早的模型以及 Claude Haiku 4.5 上，這類請求會在不進行思考的情況下執行。若要繼續在不進行前置思考的情況下執行，請參閱關閉前置思考。

在回應中處理思考

原本在不進行思考的情況下執行的程式碼需要以下全部三項。來自 Claude Sonnet 5 的程式碼可能已具備前兩項。

• 依 type 讀取內容區塊。 回應可能以 thinking 區塊開頭，因此讀取 content[0].text 的程式碼會出錯。
• 在工具使用迴圈中原封不動地傳回 thinking 區塊，包括空的區塊。請參閱保留思考區塊。
• 重新檢視 max_tokens。 它同時涵蓋思考與文字，且思考 token 會以輸出 token 計費。請參閱成本控制。

思考文字預設會被省略。thinking 區塊送達時會帶有空的 thinking 欄位和一個 signature。若要取得可讀的摘要，請設定 display: "summarized"，這是 Claude Sonnet 4.6 及更早模型以及 Claude Haiku 4.5 上的預設值。請參閱控制思考顯示。

關閉前置思考

若要在 Claude Sonnet 5.5 上關閉前置思考，請傳送 thinking: {"type": "between_tools"}。這是最低的思考設定。它在工具呼叫之間的進度更新仍會以帶有摘要文字的 thinking 區塊傳回。若沒有工具，回應只會包含文字。Claude Sonnet 5 則改用 thinking: {"type": "disabled"} 關閉思考，而更早的模型預設不進行思考。在 Claude Sonnet 5.5 上，disabled 會傳回 400 invalid_request_error：

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

between_tools 可在所有提供 Claude Sonnet 5.5 的平台上使用，無需 beta 標頭。它可在 low、medium 和 high effort 下使用。在 xhigh 或 max 下，它會傳回 400 錯誤。若要在這些等級下執行，請使用自適應思考：省略 thinking 欄位，或傳送 thinking: {"type": "adaptive"}。between_tools 不接受其他欄位：與其一同傳送 display、budget_tokens 或 block_binding 會傳回 400 錯誤。使用「server-side fallback」（伺服器端備援）時，備援至 Claude Sonnet 5 的 between_tools 請求會在該模型上以 thinking: {"type": "disabled"} 執行。

使用 between_tools 時，effort 無法在對話中途變更：與目前生效等級不同的逐訊息 output_config.effort 會傳回 400 錯誤。若要逐輪變更 effort，請使用自適應思考。如需提示撰寫指引，請參閱在不進行前置思考的情況下執行。

在未定義 between_tools 的 SDK 版本中，Python 和 TypeScript 範例將無法通過型別檢查。請更新 SDK，或如 C#、Go 和 Java 範例那樣，以原始 JSON 傳遞該值。

之前（Claude Sonnet 5）：

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

之後（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

依起始模型的遷移檢查清單

請依序往下處理各組，並在列出您模型的那一組之後停止。若使用 Claude Haiku 4.5，請套用除「Claude Sonnet 4 或更早版本」以外的所有組別，最後以「僅限 Claude Haiku 4.5」結束。

所有起始模型

• 將模型 ID 變更為 claude-sonnet-5-5。
• 依 type 讀取內容區塊，並原封不動地傳回 thinking 區塊。
• 若要繼續在不進行前置思考的情況下執行，請在 high effort 或以下發送最低的思考設定。
• 將強制工具使用替換為 auto 搭配 strict 工具，或在 Amazon Bedrock 上僅使用 auto。
• 保持對話為僅附加。
• 在 Claude API 和 Google Cloud 上，將電腦使用移至工具集，且不使用 fine-grained-tool-streaming-2025-05-14 beta 標頭。
• 將 advisor 工具與受支援的 advisor 搭配使用，並預期會收到加密的建議。
• 從 thinking 區塊讀取工具呼叫之間的文字。
• 處理拒絕，並設定備援。
• 重新執行您的 effort 掃描，並重新建立成本基準。

Claude Sonnet 4.6 或更早版本

• 預期未包含 thinking 欄位的請求會進行思考，並重新檢視 max_tokens。
• 以 effort 等級取代思考預算。
• 移除非預設的 temperature、top_p 和 top_k 值。
• 若您會顯示思考文字，請設定 display: "summarized"。
• 重新計算 token，並重新編列圖片 token 預算。

Claude Sonnet 4.5 或更早版本

• 取代助理「prefill」（預填）。
• 使用標準 JSON 剖析器剖析工具呼叫輸入。
• 在 Amazon Bedrock 上，將電腦使用從 computer_20250124 移至 computer_20251124。
• 明確設定 output_config.effort。
• 移除任何上下文視窗 beta 標頭。
• 移除 interleaved-thinking-2025-05-14，並以 eager_input_streaming 取代 fine-grained-tool-streaming-2025-05-14。
• 將 output_format 移至 output_config.format。

Claude Sonnet 4 或更早版本

• 將工具版本更新為 text_editor_20250728 和 code_execution_20260521。
• 處理 refusal 和 model_context_window_exceeded 停止原因。
• 檢查工具字串參數是否有結尾換行字元。
• 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。
• 檢閱您的提示。

僅限 Claude Haiku 4.5

• 取代 claude-haiku-4-5-20251001 或其別名。
• 以較高的每 token 價格重新建立成本基準。
• 檢閱在 Claude Haiku 4.5 上因過短而無法快取的提示。

從 Claude Sonnet 5 遷移至 Claude Sonnet 5.5

所有起始模型都需要本節中的變更。請將您的模型 ID 替換為 claude-sonnet-5-5，此 ID 沒有日期後綴。在其他平台上，請使用可用性下列出的 ID。

不支援強制工具使用

本頁上所有較早的模型都接受類型為 any 或 tool 的 tool_choice。Claude Sonnet 5.5 會以 400 錯誤拒絕這兩者，包括在 token 計數端點上：

tool_choice: type "tool" and "any" are not supported for this model.

請發送 tool_choice: {"type": "auto"}，並將工具標記為 strict: true，使其輸入符合結構描述。如此一來，模型可以在不呼叫工具的情況下回答，因此請在提示中說明何時使用該工具。「Strict tool use」（嚴格工具使用）支援 JSON Schema 的子集，且每個物件都需要 additionalProperties: false。請參閱 JSON Schema 限制。在 Amazon Bedrock 上，Claude Sonnet 5.5 無法使用結構化輸出（包括嚴格工具使用）。在該平台上，請發送不含 strict 的 auto，在提示中說明何時呼叫工具，並在您的程式碼中驗證工具輸入。

之前（Claude Sonnet 5）：

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

之後（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    # 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

此範例將清單中的每個工具都標記為嚴格。一個請求最多可有 20 個嚴格工具，且 MCP、電腦使用和瀏覽器使用工具集項目不接受 strict。在較長的工具清單中，請只標記需要的工具。

思考區塊與模型及對話綁定

Claude Sonnet 5.5 可讀取來自 Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5 及更早模型的思考區塊。它無法讀取來自 Claude Opus 5、Claude Opus 5.5 或任何 Claude Fable 或 Claude Mythos 模型的區塊。API 會捨棄模型無法讀取的區塊。請求仍會傳回 200，且被捨棄的區塊不會計費。請參閱在對話中途切換模型。

每個 Claude Sonnet 5.5 思考區塊也會針對其之前的對話內容進行簽署。對於在 2026 年 8 月 31 日 00:00 UTC 或之後建立的帳戶，API 預設會強制執行此規則，適用於 Claude API、Amazon Bedrock 和 Google Cloud。在這些帳戶上，於編輯較早的歷史記錄後重播區塊的請求會傳回 400 錯誤。請保持對話為僅附加，並使用對話中途系統訊息變更指示或工具。Claude Sonnet 5.5 產生的思考區塊只能在產生它們的帳戶或與該帳戶連結的帳戶中使用。請參閱保留的思考。

在 Claude API 和 Google Cloud 上，電腦使用需要工具集

在 Claude API 和 Google Cloud 上，Claude Sonnet 5.5 僅透過 computer_toolset_20260801 工具集支援電腦使用。在這些平台上，computer_20251124 會傳回 400 錯誤。Claude Sonnet 5.5 在任何平台上都不接受 computer_20250124。請找出您目前傳送的版本：

若您會傳送 fine-grained-tool-streaming-2025-05-14 beta 標頭，請在移至工具集時將其移除。與工具集項目一同傳送時，它會傳回 400 錯誤。請改為在每個需要的工具上設定 eager_input_streaming: true。

已傳送工具集的程式碼無需變更。從 computer_20251124 遷移列出了請求與代理迴圈的變更。其他平台請參閱相容性。

顧問工具接受的顧問較少

使用顧問工具時，Claude Sonnet 5.5 執行者需要搭配下列其中一個顧問：Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5、Claude Fable 5.1、Claude Mythos 5 或 Claude Mythos 5.1。Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 和 Claude Sonnet 4.6 顧問會傳回 400 錯誤。建議會以 advisor_redacted_result 區塊加密傳回，因此其文字在回應中無法讀取。請參閱模型相容性。

工具呼叫之間的文字會在思考區塊中傳回

在 Claude Sonnet 5.5 上，模型在工具呼叫之間撰寫、長度超過一兩句的說明，會以進度更新 thinking 區塊傳回，且在預設 display 下為空。較短的評論仍為 text。在 Claude Sonnet 5 及更早的模型上，工具呼叫之間的所有文字都會以 text 區塊傳回。不會有請求失敗，但顯示這些說明的介面會變得沒有內容。

使用自適應思考時，將 display 設為 "updates"（beta，thinking-display-updates-2026-08-18 標頭）可單獨取得更新，設為 "summarized" 則可取得與推理混合的更新。請在每個非空 thinking 區塊之後的 tool_use 區塊之前呈現該 thinking 區塊。使用 between_tools 時，文字會在不需設定 display 的情況下傳回。請參閱面向使用者的進度更新。

安全分類器與備援

Claude Sonnet 5.5 會拒絕的類別比 Claude Sonnet 5 更多。拒絕會傳回 stop_reason: "refusal"，其 stop_details 可能會指出下列其中一個類別：

• "cyber"： 該請求可能促成網路危害，例如惡意軟體或漏洞利用程式開發。
• "bio"： 該請求可能促成生物危害，例如危險的實驗室方法。
• "frontier_llm"： 該請求可能協助開發競爭的 AI 模型。
• "reasoning_extraction"： 該請求要求模型在回應文字中重現其內部推理。
• "general_harms"： 該請求屬於其他使用政策領域。良性工作也可能觸發此類別。

伺服器端備援（fallbacks: "default"，beta，僅限 Claude API）會在 Claude Sonnet 5 上重試 "cyber" 和 "frontier_llm" 拒絕。它不會重試 "bio"、"reasoning_extraction" 或 "general_harms" 拒絕。請參閱拒絕與備援以及拒絕如何計費。

對於來自 Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 的程式碼而言，即時網路安全防護措施是新增的。若要進行合法的安全工作，請申請網路安全驗證計畫（Cyber Verification Program）。

其他變更

• 提示快取： 最小可快取提示為 512 個 token，低於 Claude Sonnet 5、Claude Sonnet 4.6 和 Claude Sonnet 4.5 上的 1,024 個。請參閱提示快取。
• 新功能： 關於對話中途系統訊息、對話中途工具變更以及逐訊息 effort，請參閱 Claude Sonnet 5.5 的新功能。使用 between_tools 時，effort 無法在對話中途變更。

建議變更

重新執行您的 effort 掃描。Claude Sonnet 5.5 有五個 effort 等級：low、medium、high、xhigh 和 max。Claude API 上的預設值為 high。這些等級已重新校準，因此同一等級產生的思考量與 Claude Sonnet 5 上不同。除非您的工作負載屬於代理式或對延遲敏感，否則請從 high 開始。對於代理式程式設計和多步驟工具使用，定義明確的任務請從 medium 開始，較困難或較長的任務則改用 high。對於聊天和其他對延遲敏感的工作，請從 medium 或 low 開始。請在 output_config.effort 中設定等級。請參閱 Claude Sonnet 5.5 的建議 effort 等級。接著，請對照提示 Claude Sonnet 5.5 重新評估模型特定的提示指示。

從 Claude Sonnet 4.6 及更早的 Sonnet 模型遷移至 Claude Sonnet 5.5

首先套用前面的所有章節，並替換 claude-sonnet-4-6。然後進行以下變更。若使用 Claude Sonnet 4.5 或更早版本，請繼續閱讀後續的子章節。

破壞性變更

原本省略思考的請求會執行思考。 請參閱預設會執行思考和關閉前置思考。

思考預算會傳回錯誤。 Claude Sonnet 4.6 接受 thinking: {"type": "enabled", "budget_tokens": N} 作為已棄用的設定。Claude Sonnet 4.5 和 Claude Haiku 4.5 的所有思考都使用此設定。Claude Sonnet 5.5 會傳回 400 錯誤：

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

請移除預算並設定 effort 等級。預算與 effort 等級之間沒有固定的對應關係，因此請在兩到三個等級下執行您的評估。

之前（Claude Sonnet 4.6）：

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

之後（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

取樣參數會傳回錯誤。 Claude Sonnet 4.6 及更早的模型以及 Claude Haiku 4.5 接受 temperature、top_p 和 top_k。在 Claude Sonnet 5.5 上，非預設值會傳回 400 錯誤。請將其移除。

思考文字預設會被省略。 請參閱在回應中處理思考。

其他變更

• token 約增加 30%： Claude Sonnet 5.5 使用 Claude Sonnet 5 的「tokenizer」（分詞器）。與 Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 相比，相同文字產生的 token 約多 30%，實際數量視內容而定。請使用 token 計數重新計算，並重新檢視 max_tokens 和成本。
• Effort： xhigh 為新增等級，且各等級已重新校準。請參閱建議變更。
• 圖片： Claude Sonnet 5.5 使用高解析度圖片層級，長邊最多 2576 像素，每張圖片最多 4,784 個視覺 token。Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 的上限為 1568 像素和 1,568 個 token。一張 2000×1500 的圖片在 Claude Sonnet 5.5 上耗用的 token 約為 2.5 倍。請參閱解析度與 token 成本。

從 Claude Sonnet 4.5 或更早版本遷移

若使用 Claude Sonnet 4.5、Claude Sonnet 4 或 Claude 3.7 Sonnet，請先套用前面的所有章節，再進行以下變更。

預填會傳回錯誤。 Claude Sonnet 5.5 會以 400 錯誤拒絕預填的最後一個助理回合，與 Claude Sonnet 4.6 和 Claude Sonnet 5 相同。Claude Sonnet 4.5、Claude Haiku 4.5 及更舊的模型則接受預填。錯誤內容如下：

This model does not support assistant message prefill. The conversation must end with a user message.

請依每個預填的用途加以取代：

• 輸出格式： 使用結構化輸出，或在分類時使用帶有列舉欄位的工具。
• 開場白： 在系統提示中要求直接回答。
• 不必要的拒絕： 在使用者訊息中提供清楚的指示通常就已足夠。
• 接續： 將其移至使用者訊息，例如「您先前的回應被中斷，結尾為 [previous_response]。請從中斷處繼續。」
• 上下文提醒： 將其放在使用者回合中。

工具輸入跳脫。 工具呼叫引數中的跳脫方式可能不同。請使用標準 JSON 剖析器剖析 input。

電腦使用。 Claude Sonnet 5.5 不接受 computer_20250124。請參閱電腦使用表格。

Effort。 Claude Sonnet 4.5 沒有 effort 參數。請依建議變更所述，明確設定 effort 等級。

上下文與輸出。 Claude Sonnet 5.5 具有更大的上下文視窗（無需 beta 標頭）以及更高的輸出限制。請參閱模型頁面。請移除任何上下文視窗 beta 標頭。

Beta 標頭。 請移除 interleaved-thinking-2025-05-14，因為自適應思考會自動交錯進行。請在每個需要的工具上以 eager_input_streaming: true 取代 fine-grained-tool-streaming-2025-05-14。該標頭與電腦使用或瀏覽器使用工具集項目一同傳送時會傳回 400 錯誤。請參閱細粒度工具串流。

結構化輸出。 output_format 參數已棄用，並將於未來移除。若仍要使用，請加入 structured-outputs-2025-11-13 beta 標頭。若未加入，API 會傳回 400 錯誤。請改用 output_config.format。

從 Claude Sonnet 4 或更早版本遷移

Claude Sonnet 4 已在 Claude API 上停用，但仍可在 Amazon Bedrock 和 Google Cloud 上使用。Claude 3.7 Sonnet 已停用。從這兩個模型中的任一個遷移時，請先套用前面的所有章節，再進行以下變更：

• 工具版本： 使用 text_editor_20250728，工具名稱為 str_replace_based_edit_tool，且沒有 undo_edit 命令。使用 code_execution_20260521。請參閱文字編輯器工具和程式碼執行工具。
• 停止原因： 處理 refusal。Claude 4.5 及更新的模型在達到上下文視窗限制時也會以 model_context_window_exceeded 停止。請參閱處理停止原因。
• 結尾換行字元： Claude 4.5 及更新的模型會在工具呼叫字串參數中保留結尾換行字元。
• 舊版 beta 標頭： 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。
• 提示： 對照提示撰寫最佳實務檢閱您的提示。

從 Claude Haiku 4.5 遷移至 Claude Sonnet 5.5

首先套用直到並包括從 Claude Sonnet 4.5 或更早版本遷移的所有章節，但略過 Claude Sonnet 4 子章節。然後進行以下變更：

• 模型 ID： 將 claude-haiku-4-5-20251001 或別名 claude-haiku-4-5 替換為 claude-sonnet-5-5。
• 成本： 每 token 價格較高，且相同文字會產生更多 token。請重新計算 token 並重新建立成本基準。請參閱 Claude 定價。
• 提示快取： 最小可快取提示從 4,096 個 token 降至 Claude Sonnet 5.5 的最小值。
• 交錯思考： 自適應思考會自動在工具呼叫之間執行，無需 beta 標頭。
• 路由： Claude Sonnet 5.5 可讀取 Claude Haiku 4.5 的思考區塊。向上移轉的對話會保留其推理。移回 Claude Haiku 4.5 的對話則會捨棄 Claude Sonnet 5.5 的區塊。