Anthropic Python SDK 1.0 迁移指南：httpx2 替换与重大 breaking change

Anthropic Python SDK 1.0 迁移检查清单

原文首发于 IndieSeek。

Anthropic Python SDK 1.0.0 于 2026 年 8 月 20 日发布，是一个真正的迁移版本。它要求 Python 3.10 及以上版本，将传输层从 httpx 迁移到 httpx2，移除了旧的 Text Completions 接口和若干已废弃的参数，改变了原始响应的消费方式，用服务端上下文管理替代了客户端工具运行器压缩，并不再静默为 Bedrock 选择 us-east-1。

不要一开始就做全包范围的查找替换。先盘点应用程序实际用到的接口，在锁定分支中升级，验证可观测性后再切流量。最危险的失败不一定是崩溃：追踪或 HTTP mock 如果是 patch httpx 实现的，在 SDK 开始使用 httpx2 后可能会静默地无法感知到 Anthropic 的请求。

本指南面向直接调用 Claude Messages API、使用自定义传输层或代理、消费 .with_raw_response、运行带压缩的工具循环、或通过 Amazon Bedrock 路由的 Python 团队。也帮助那些测试依赖 respx、pytest-httpx、vcrpy、OpenTelemetry 或 Sentry 的维护者。

如果你同时还需要将保存的 prompt 从已废弃的 Claude 接口迁移出去，请使用 Workbench-to-Playground 迁移检查清单。本文聚焦于 Python 运行时契约。

发生了什么——以及它如何失败

官方迁移指南还涉及原始字节 body、header 合并、流式类型检查、结构化输出 schema 位置和未知 Bedrock 流事件的变更。将那个表格视为分诊依据，而不是上游指南的完整替代品。

按失败顺序排列的迁移工作流

1. 冻结一个可逆的基准线

记录 Python、anthropic、httpx、代理、追踪、mock、模型、API 路由和云提供商版本。在修改 lockfile 之前，捕获一条成功的 Messages 响应、请求 ID、追踪、mocked 测试、工具循环检查点以及 Bedrock 区域。

用明确的主版本范围升级：

python -m pip install --upgrade "anthropic>=1,<2"
python -m pip check

在所有支持的 Python 镜像上运行项目。本地 Python 3.12 成功并不能证明较旧的 CI 或 serverless 镜像满足新的 3.10 门槛。

2. 在运行测试前盘点已移除的接口

使用仓库扫描将运行时意外转换为编辑清单：

rg -n 'client\.completions|HUMAN_PROMPT|AI_PROMPT|temperature=|top_p=|top_k=|compaction_control|with_raw_response|AnthropicBedrock|import httpx'

将旧的 completions 迁移到 client.messages.create()。从生成的 Messages 方法中移除采样参数，除非较旧的 pinned 模型仍然需要通过 extra_body 接收这些参数。将原始结构化输出 schema 放到 output_config 下；只在 helper 期望模型类型的地方保留 output_format=ModelClass。

3. 选择一种 httpx2 集成策略

如果只有 Anthropic 客户端需要 HTTP 定制，直接导入 httpx2 并从中构造每个 client、transport、timeout、proxy、request 和 response 类型。这是范围最窄的变更。

如果应用级追踪或 mock 仍在 patch httpx，在应用程序最开头或 early pytest 插件中调用 httpx2.alias_httpx()——在任何代码导入 httpx 之前。不要把这个全局别名放在可复用库内部；上游指南明确将这个决策权交给应用程序。

然后用 httpx2.MockTransport 运行一个无载荷的正向控制：返回一个合成的 Messages 响应，断言恰好有一个请求到达 /v1/messages，并断言追踪或 mock 记录了它。一次成功 API 调用但没有预期的追踪记录意味着迁移失败。

4. 修复原始响应消费者

对于异步客户端，响应元数据仍然是普通属性访问，但 body 操作是异步的：

response = await client.messages.with_raw_response.create(...)
request_id = response.headers["request-id"]
message = await response.parse()
body = await response.read()

对于同步客户端，使用 response.parse()、response.text() 和 response.read()。搜索存储的 .text 或 .content 属性；那些旧访问模式可能在类型盲测试中存活下来，只在受影响的路径上才失败。

5. 显式迁移压缩和 Bedrock 配置

用服务端压缩 beta 和 context_management 替代工具运行器的 compaction_control。官方示例使用 compact-2026-01-12，要求至少 50,000 的输入 token 触发。重新运行一个长的可丢弃工具循环，证明检查点出现、任务恢复、且没有工具结果被重复。Claude agent memory 迁移指南提供了更广泛的持久化边界。

对于 Bedrock，设置 aws_region、AWS_REGION、AWS_DEFAULT_REGION 或一个配置好的 profile。添加一个负向 canary，清除所有区域来源并期望 ValueError；然后添加一个正向 canary，记录目标区域而不产生付费模型调用。

6. 对边缘契约做金丝雀验证

在生产流量之前，验证七个关卡：

• Python 3.10+ 解析并导入了锁定的 SDK。
• 自定义 httpx2 transport 收到一个合成的 Messages 请求。
• 追踪和 HTTP mock 在传输层迁移后看到同一个请求。
• 同步和异步原始响应路径用新契约解析 body。
• 已移除的 completions、prompt 常量和方法参数已从代码库中消失。
• 一个长的工具循环压缩并恢复，没有重复的工具效果。
• 缺失的 Bedrock 区域失败关闭；配置的区域与部署环境匹配。

还要验证重复的 header 大小写、字节值 header、低级原始 body，以及任何 isinstance(..., anthropic.Stream) 检查——如果你的代码使用了这些不常见的接口。

你的应用是传递自定义 httpx 对象还是全局 patch httpx？
  否 -> 使用 SDK 默认值；仍需验证追踪和原始响应
  是 -> 只有 Anthropic 专用代码改变了吗？
           是 -> 直接导入 httpx2
           否  -> 在任何 httpx 导入之前的应用程序入口点做别名

你的应用使用了已移除的 API 或辅助参数吗？
  是 -> 迁移每个调用并回放其 fixture
  否  -> 继续

所有七个 canary 都通过了吗（附证据）？
  否 -> 保持 v0 锁定并修复失败的接口
  是 -> 金丝雀小流量切片，然后推广

常见错误

将 HTTP 200 视为追踪、mock 和重试仍然正常工作的证明。

在框架已经导入 httpx 之后才调用 httpx2.alias_httpx()。

保留已移除的采样参数而不检查 pinned 模型契约。

修复了异步 parse() 但保留了旧的 .text 或 .content 属性读取。

替换了客户端压缩但没有回放一个长的工具循环及其副作用。

让 Bedrock 通过生产环境没有的ambient 开发者凭证选择区域。

一起升级 lockfile 和生产镜像而没有回滚产物。

可复制的验收记录

python / anthropic / httpx2 / lock digest:
runtime image / provider / model / API route:
custom client / proxy / transport / alias strategy:
trace canary / mock canary / request-id captured:
sync raw response / async raw response:
removed-surface scan result:
compaction trigger / resume / duplicate-effect result:
bedrock region source / missing-region negative canary:
traffic slice / error delta / rollback artifact:
decision: hold | canary | promote | rollback

常见问题

必须每个应用都调用 httpx2.alias_httpx() 吗？

不必。当变更可以局限在 Anthropic 集成内部时，直接使用 httpx2 对象。全局别名主要用于 patch httpx 且必须观察新传输层的应用级工具。

Claude API 是否移除了 temperature、top_p 和 top_k？

v1 生成的 Messages 方法移除了这些参数。Anthropic 的迁移指南指出，仍然支持这些参数的较旧模型可以通过 extra_body 接收它们。请验证确切的模型契约，而不是假设要么全量移除要么全量支持。

1.0.0 安全吗，因为版本已经稳定了？

该版本是稳定的，但你的集成可能依赖于已移除或静默变更的接口。只有在传输层可观测性、原始响应、工具循环状态和提供商配置在你的环境中通过之后，才能推广。

链接

Claude Platform release notes: Python SDK v1.0

Anthropic Python SDK v1.0.0 release

Official Python SDK v1 migration guide

Anthropic Python SDK source at v1.0.0

PyPI metadata for anthropic==1.0.0

Anthropic SDK issue #1755: httpx2 migration request

在 IndieSeek 阅读维护版本。

如需进一步操作，你可以考虑屏蔽此人或举报滥用。