Anthropic 官方迁移指南：Claude Sonnet 5.5 API 配置与 breaking changes

一句话结论

Claude Sonnet 5.5 的迁移重点是改用 claude-sonnet-5-5、适配默认开启的 adaptive thinking、移除非默认的 temperature、top_p 和 top_k 及旧版 assistant prefill、将强制工具调用改成 auto 加 strict tool，并按 block type 读取和回传 thinking blocks。

适用场景

• 适合的任务：把 Claude Sonnet 5、Sonnet 4.6 及更早 Sonnet、或 Haiku 4.5 的 Messages API 集成迁移到 Sonnet 5.5，检查 Agent loop、工具调用、电脑使用和 thinking 处理。

• 不适合的任务：把本指南当作其他模型或非 Messages API 产品的完整迁移说明；直接假设旧 effort、thinking budget、token 成本或 block 处理方式仍然等价。

• 适用的模型版本：目标模型 claude-sonnet-5-5；指南覆盖 Claude Sonnet 5、Sonnet 4.6、Sonnet 4.5、Sonnet 4、Claude 3.7 Sonnet 和 Claude Haiku 4.5。

• 适用的客户端、Agent 或 API：Messages API。Claude Managed Agents 只需更新模型名；使用 Amazon Bedrock 或 Google Cloud 时，需要按页面给出的平台差异调整模型 ID、电脑使用工具和结构化输出能力。

• 推荐的推理档位和参数：Sonnet 5.5 有 low、medium、high、xhigh、max 五档；Claude API 默认 high。定义清楚的 Agent 编码和多步工具任务从 medium 开始，困难任务升到 high；迁移后重新做 effort sweep 和成本基线。

可直接使用的内容

1. 可工作的基础请求

以下 Python 请求是迁移指南公开的 Sonnet 5.5 示例。它设置 effort，并按 block type 读取返回内容；示例省略了会返回 400 的五类设置：thinking budget、采样参数、assistant prefill、强制 tool choice 和 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)

2. 关闭预先思考的 before / after

Sonnet 5.5 没有 thinking 字段时默认使用 adaptive thinking。若要保持“工具调用之间才更新”的低思考模式，使用 thinking: {"type": "between_tools"}；该设置只接受 low、medium、high，xhigh 和 max 会返回 400。

Before（Claude Sonnet 5）：

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

After（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": "..."}],
)

官方边界：between_tools 不需要 beta header；不能与 display、budget_tokens 或 block_binding 一起发送；使用 server-side fallback 时，回退到 Sonnet 5 会在回退模型上使用 thinking: {"type": "disabled"}。

3. 旧 thinking budget 的 before / after

从 Sonnet 4.6 或更早模型迁移时，固定 thinking budget 会返回 400；官方建议改用 adaptive thinking 加 effort，并重新做两到三个档位的评估，没有 budget 到 effort 的固定换算。

Before（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": "..."}],
)

After（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": "..."}],
)

4. 强制工具调用的 before / after

Sonnet 5.5 拒绝 tool_choice 类型 tool 和 any，包括 token counting endpoint。迁移时使用 auto；若要让输入匹配 schema，将需要严格校验的工具标记为 strict: true，并在 prompt 中说明何时调用工具。严格工具调用要求每个 object 都有 additionalProperties: false，且每个请求最多 20 个 strict tools。Amazon Bedrock 不提供 Sonnet 5.5 的 structured outputs，因此在 Bedrock 上使用 auto（不加 strict），在代码中校验 tool input。

Before（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?"}],
)

After（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    # strict tool use: every call matches the tool's 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.",
        }
    ],
)

5. 自动化迁移命令

指南给出 Claude Code 中的 Claude API skill 命令。它会先要求确认迁移范围，再应用模型 ID、breaking parameter、prefill replacement 和 effort calibration 的修改，并输出人工核对清单：

/claude-api migrate this project to claude-sonnet-5-5

该命令属于 Anthropic 页面公开的 Claude Code 工作流；是否可用取决于当前 Claude Code 和 skill 环境。

迁移检查清单

所有起始模型都要检查

• 将模型 ID 改为 claude-sonnet-5-5；其他平台使用 Availability 中对应 ID。

• 按 block type 读取 content，并在 tool-use loop 中原样回传 thinking blocks，包括空 block。

• 若不需要预先思考，在 high 或更低 effort 使用 between_tools。

• 将 forced tool use 改为 auto 加 strict tools；Amazon Bedrock 使用 auto 且不加 strict。

• 保持 conversation append-only；改变指令或工具时使用 mid-conversation system messages。

• Claude API 和 Google Cloud 的 computer use 改用 computer_toolset_20260801，并移除 fine-grained-tool-streaming-2025-05-14 beta header。

• advisor tool 只搭配支持的 advisor，并接受加密的 advisor_redacted_result。

• 从 thinking blocks 读取工具调用之间的文本。

• 处理 refusal 并配置 fallback。

• 重新扫描 effort，并重新建立成本基线。

从 Sonnet 4.6 或更早模型迁移

• 适应没有 thinking 字段时默认开启 thinking，并重新检查 max_tokens。

• 移除固定 thinking budget，改用 effort。

• 移除非默认 temperature、top_p 和 top_k；Sonnet 5.5 的非默认值会返回 400。

• 如果要展示 thinking 文本，设置 display: "summarized"。

• 重新计算 token，并重新预算图片 token。

从 Sonnet 4.5 或更早模型迁移

• 移除 assistant prefill。分类用 structured outputs 或带 enum 字段的工具；续写、上下文提醒和 preamble 改放 user turn 或 system prompt。

• 用标准 JSON parser 解析 tool call input。

• 电脑使用不再接受 computer_20250124；按平台切换到 toolset 或 computer_20251124。

• 显式设置 output_config.effort。

• 移除 context-window beta header。

• 移除 interleaved-thinking-2025-05-14；将 fine-grained-tool-streaming-2025-05-14 改成需要的工具上的 eager_input_streaming: true。

• 将 output_format 移到 output_config.format；旧字段需要 structured-outputs beta header，且已被标记为 deprecated。

从 Sonnet 4 或 Claude 3.7 Sonnet 迁移

• 按官方迁移指南核对旧版 text_editor_20250728 和 code_execution_20260521 工具、model_context_window_exceeded 错误及工具字符串尾部换行的行为变化。

• 移除旧版 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19 beta headers。

• Sonnet 4 已从 Claude API 退役，但仍可在 Amazon Bedrock 和 Google Cloud 使用；迁移计划须区分平台。

从 Haiku 4.5 迁移

• 将 claude-haiku-4-5-20251001 或 claude-haiku-4-5 替换为 claude-sonnet-5-5。

• 重新统计 token 并建立成本基线；页面说明 Sonnet 5.5 单 token 价格更高，且相同文本会产生更多 token。

• 按 Sonnet 5.5 的最低可缓存 prompt 长度重新检查 prompt caching；官方列出的门槛从 Haiku 4.5 的 4,096 tokens 降为 Sonnet 5.5 的 512 tokens。

• 移除 interleaved thinking beta header；adaptive thinking 会自动在工具调用之间运行。

• 从 Haiku 4.5 切换到 Sonnet 5.5 时，Sonnet 5.5 可以读取 Haiku 4.5 的 thinking blocks；反向切回 Haiku 4.5 会丢弃 Sonnet 5.5 的 blocks。

关键 API 变化与边界

thinking blocks 绑定模型和会话。Sonnet 5.5 可以读取 Sonnet 5、Opus 4.8、Haiku 4.5 及更早模型的 blocks，但不能读取 Opus 5、Opus 5.5、Fable 或 Mythos 的 blocks；API 会丢弃不可读取的 blocks，仍返回 200 且不计费。Sonnet 5.5 生成的 thinking blocks 只适用于生成它们的账号或关联账号。

工具调用之间较长的文本会作为 progress-update thinking blocks 返回，默认 display 下 thinking 字段为空；需要进度时，adaptive thinking 可使用 display: "updates" 和页面所述 beta header，或使用 display: "summarized"。每个非空 thinking block 应在后续 tool_use block 前渲染。

安全拒绝可能返回 stop_reason: "refusal"，类别包括 cyber、bio、frontier_llm、reasoning_extraction 和 general_harms。Claude API 的 server-side fallback 会重试 cyber 和 frontier_llm，不会重试其他三类。

结论与边界

迁移 Sonnet 5.5 时，最容易造成 400 或静默行为变化的地方是 thinking 配置、采样参数、assistant prefill、forced tool choice、电脑使用 toolset，以及 thinking blocks 的读取和回传。API 能成功返回也不代表 Agent loop 正确：如果客户端只读取文本 block，长工具调用可能看起来没有进度；如果丢弃 thinking blocks，后续工具交互可能失去模型需要的上下文。

迁移后的质量、延迟和成本不能按旧模型同名档位推断。指南要求重新做 effort sweep；它明确比较了 Sonnet 4.6、Sonnet 4.5 和 Haiku 4.5 的 token 变化：相同文本约多 30% token，图片最高分辨率和视觉 token 预算也发生变化。该数字不可直接外推到 Sonnet 4 或 Claude 3.7 Sonnet。指南中的价格说明称 Sonnet 5.5 与 Sonnet 5 价格相同，但 prompt cache reads 为每百万 token $0.10，是 Sonnet 5 的一半；具体价格仍应以当前 Claude pricing 页面为准。

复现说明

可依照本页 before/after 代码，对同一 Messages API 请求分别测试 Sonnet 5、Sonnet 4.6 或 Haiku 4.5 与 Sonnet 5.5，记录 HTTP 状态、stop_reason、content block 类型、tool choice、thinking 回传、token 计费和延迟。要完整复现指南中的迁移行为，还需固定平台、模型部署、SDK 版本、beta headers、工具 schema、账号创建时间、fallback 配置及会话历史；这些环境条件不会由本文代码单独确定。