AIREITERAnthropic Python SDK v1.0 已于 2026 年 8 月 20 日登陆 PyPI。对大多数项目来说，原有调用代码可以原封不动地继续运行，但真正危险的变化藏在 HTTP 层：SDK 从 httpx 切换到了 httpx2。这意味着，依赖修改 httpx 的链路追踪、APM Agent 和测试 Mock 可能照常启动，却悄悄记录不到任何 SDK 请求。升级后测试全绿，并不能证明一切正常。
两天内连发三个版本，然后进入 1.0
anthropic 的 PyPI 发布记录很能说明问题：0.123.0、0.124.0 和 0.125.0 都在 2026 年 8 月 19 日发布，随后 1.0.0 于 8 月 20 日通过标准 Trusted Publishing 流程上线。
根据官方更新说明，这次主要变化包括：
- HTTP 层从
httpx切换到httpx2，后者是一个持续维护且 API 兼容的分支。 - 最低 Python 版本提升至 3.10；分类器列出的版本范围为 3.10 至 3.14。
- 长期弃用的功能被正式移除：旧版 Text Completions API、Messages 方法中的
temperature、top_p和top_k参数，以及工具运行器客户端侧的compaction_control。 - 如果没有配置 AWS region，
AnthropicBedrock现在会直接抛出错误，不再静默使用默认值us-east-1。
GitHub 上的 v1.0.0 标签将这次更新概括为“升级到 httpx2，以及一些小幅破坏性变更”。更新说明里还有一个容易被忽略的细节：parse、stream 和 tool_runner 辅助方法上的 beta 警告已经消失。版本号进入 1.0，且不再附带 beta 限制，说明 Anthropic 已将这组 API 视为稳定接口。
从 httpx 切到 httpx2，实际会影响什么
如果你只是按默认方式创建客户端，基本不会遇到变化；但只要碰到 HTTP 层，迁移就绕不过去。
关键区别在于传给客户端的对象类型。数值参数仍然有效，例如 Anthropic(timeout=30.0) 的行为与以前完全相同；但对象不再通用：现在把普通的 httpx.Client 通过 http_client= 传入，会在构造客户端时直接抛出 TypeError，而不是等到第一次请求才报错。自定义客户端、超时对象和传输层都必须改用 httpx2 构建；原先的 httpx.Timeout 对象则应替换为 anthropic.Timeout（或 httpx2.Timeout）。
# 0.x
client = Anthropic(http_client=httpx.Client(proxy="http://proxy:8080"))
# 1.0
client = Anthropic(http_client=DefaultHttpxClient(proxy="http://proxy:8080"))DefaultHttpxClient 和 DefaultAsyncHttpxClient 的名称与行为都没有变化：它们仍然保留 SDK 推荐的超时、连接池和重定向默认设置，只是底层现在改由 httpx2 提供。Anthropic 平台开发者体验工程师 @cjav_dev 在员工公告中也指向了同一个起点：官方 MIGRATION.md。这份文档列出了所有变更，并提供了新旧代码对照。
这并不是第一次发生类似切换。OpenAI Python SDK 的 httpx2 迁移指南更早走过了同一条路：使用相同的分支、类似的 DefaultHttpx2Client 辅助模式，也遇到了相同的 respx 兼容性提醒。已经迁移过 openai 的团队，几乎可以直接复用原有方案。
v1.0 移除了哪些 API
| v1.0 移除项 | 替代方案 |
|---|---|
client.completions.create()（Text Completions） | client.messages.create() |
HUMAN_PROMPT / AI_PROMPT 常量 | 采用 Messages 格式的内容块 |
方法签名中的 temperature、top_p、top_k | 对于仍接受这些参数的旧模型，使用 extra_body={"temperature": ...} |
messages.parse(stream=True) | messages.stream(...) |
tool_runner(compaction_control=...) | 服务端压缩配置 |
anthropic.Transport、anthropic.ProxiesTypes 别名 | httpx2 传输类型 |
底层请求方法中的 body= | content= |
Beta API 中的 output_format schema 字典 | output_config={"format": ...}（结构化输出辅助方法仍接受 output_format=MyModel） |
isinstance(stream, anthropic.Stream) 检查 | 改为检查具体的 MessageStream 类型 |
这张表还有两个补充点。Pydantic v1 和 v2 仍然同时受支持，因此模型类无需调整。另一个变化是请求头合并现在不区分大小写：如果你曾用不同大小写重复设置同一个请求头，行为就会改变。这个场景比较少见，但触发时不会报错。
异步变化：主要影响使用原始响应的代码
异步部分的改动范围不大，但如果使用了 .with_raw_response，就可能踩坑。在异步客户端中，parse()、read()、text() 和 json() 现在都必须使用 await。同步客户端则将 .text 和 .content 从属性改成了方法。两种情况都不会在导入阶段报错：同步用法会明确抛出属性错误，异步用法则可能因为没有 await 而得到一个始终未执行的协程，问题更隐蔽。
另外，异常对象和原始响应结果中的请求、响应对象，现在也都是 httpx2 类型。大多数属性访问方式没有变化，但 isinstance(x, httpx.Response) 检查和类型注解必须更新。这类问题正好可以交给 pyright 或 mypy 提前找出来。
最容易被忽略的迁移故障
更新日志把它压缩成了一句话，但监控系统可不会替你兜底。根据 Anthropic 的迁移指南，任何通过修改 httpx 来观测或 Mock HTTP 流量的工具——包括 OpenTelemetry、Sentry、respx、pytest-httpx 和 vcrpy——在升级后都可能继续运行，却悄悄漏掉 SDK 请求。这些工具仍然可以导入、启动和上报，只是 SDK 的流量已经不再经过它们修改的那个库。若测试没有断言拦截确实发生，基于这类 Mock 的测试甚至可能“空跑”通过：请求没有到达 Mock，自然也就没有失败。
解决办法是 httpx2.alias_httpx()。应在应用或测试启动的最早阶段调用它；Python SDK 文档明确要求在任何 httpx 导入之前完成。它会让 httpx2 以 httpx 的名称提供，从而继续兼容现有的修改工具。迁移指南同时提醒，不要在库代码中调用它，而应只放在应用入口。
“启动过程干净，并不能证明你的 AI 调用仍在被追踪或 Mock。”——@MarMarLabs，发布于版本上线次日
这条帖子值得完整阅读。作者建议把这种隐形故障作为第一项迁移测试：完成升级后，主动验证一个被追踪的请求和一个被 Mock 的请求是否仍然成功记录。同一讨论还提到了另外两个静默风险：自定义传输层需要手动迁移到 httpx2，以及 Python 3.10 的最低版本要求可能在安装阶段就让旧版 CI 镜像失败。
哪些代码可以原样继续运行
对很多代码库来说，最诚实的答案是：什么都不用改。如果你从未构建自定义客户端、传输层或超时对象，那么 HTTP 层迁移不会影响你。以下内容也没有变化：
client.messages.create(...)使用普通参数的调用：请求和响应模型都不变。- 数值形式的超时参数和 SDK 默认值：连接错误、408、409、429 以及 5xx 状态码会触发带指数退避的 2 次重试；默认超时时间为 10 分钟。
base_url路由。如果你将 SDK 指向网关或兼容 API 的中继服务，例如 AIReiter 的 Claude API 端点，v1.0 不会改变这一层——发生变化的是客户端，而不是 URL。- Pydantic v1 和 v2 模型、SSE 流式传输辅助方法，以及文件上传接口。
唯一的硬性门槛是 Python 3.10+。所谓“安全清单”中的其他内容，都建立在你先满足这一要求的前提上。
一套经得起代码审查的迁移顺序
- 先有意识地固定版本：如果暂时还没准备好，使用
anthropic>=0.125,<1可以先维持现状，之后再安排迁移。 - 在代码库中搜索
import httpx和httpx.——SDK 周边代码里的每一处命中，都是潜在迁移项。 - 在 Claude Code 中运行
/claude-api upgrade python。这是@cjav_dev 的版本发布公告推荐的命令，可以生成项目变更 diff。 - 使用
httpx2或DefaultHttpxClient辅助方法重建自定义客户端、传输层和超时对象。 - 如果有工具会修改
httpx，就在应用入口加入httpx2.alias_httpx()。 - 运行 pyright 或 mypy，让它们找出 httpx2 类型变化带来的注解和
isinstance错误。 - 在 CI 中为每个测试套件至少断言一个被追踪的请求和一个被 Mock 的请求。启动日志显示绿色，不代表请求真的被观测到了。
Anthropic Python SDK v1.0 常见问题
Anthropic Python SDK v1 已经存在，还是仍然处于 0.x？
已经存在。anthropic 1.0.0 于 2026 年 8 月 20 日上线 PyPI，并在 GitHub 标记为 v1.0.0；前一个版本 0.125.0 则在前一天发布。PyPI 项目页面现在也会将 0.x 用户引导至 v1 迁移指南。
v1.0 之后如何传入 temperature、top_p 或 top_k？
这些参数已经从方法签名中移除。对于服务端仍接受它们的旧模型，可以使用 extra_body={"temperature": 0.7} 传入。不过需要注意，当前模型无论如何都会对非默认采样值返回 400——这是模型层面的变化，不是 SDK 引起的。
respx、pytest-httpx 或 vcrpy 测试还能正常工作吗？
如果针对的是 SDK 默认客户端，不能保证，而且它们不会报错，只会匹配不到任何请求。你可以在测试启动阶段、任何 httpx 导入之前调用 httpx2.alias_httpx()，也可以将 Mock 迁移到 httpx2.MockTransport。只修改旧版 httpx 的 respx 版本无法拦截 SDK 流量。
/claude-api upgrade python 会做什么？
这是 Claude Code 的一个命令，Anthropic 开发者体验工程师 @cjav_dev 在公告中推荐过它。该命令会扫描使用 anthropic 0.x 的项目，生成迁移 diff，覆盖导入、超时对象和原始响应调用等内容，让你可以先审查变更，而不是等 traceback 出现后再排查。
锁定 0.125，还是直接升级到 1.0
这件事没有放之四海而皆准的答案，关键要看实际取舍。继续停留在 1.0 以下，可以让现有 Mock、追踪器和自定义传输层完全保持不变；但你仍然使用的是尚未稳定的 SDK，其版本策略允许在次版本更新中引入不兼容变更，而且你依赖的弃用功能——completions 和采样参数——如今已经正式成为历史包袱。升级到 1.0，则可以获得稳定、非 beta 的 API，但代价是现在就完成 HTTP 层全面审计，而不是把问题留到以后。决定因素在于你维护了多少 HTTP 层代码：只有一个普通 Anthropic() 调用的服务，升级会非常简单；而拥有自定义传输层和 respx 测试套件的平台，则应在发布前完成静默失效检查。
相关阅读：同一周退出 beta 的 Skills API，以及于 8 月 10 日转为永久价格的 Sonnet 5——它们都属于 Claude Platform 同一阶段的版本更新。