Anthropic Python SDK 1.0迁移：手动操作还是使用Claude Code

将Python项目从anthropic 0.x迁移到1.0，只需一条安装命令pip install --upgrade "anthropic>=1,<2"，然后逐项处理一份固定的破坏性变更清单：HTTP层现在运行在httpx2之上，异步.with_raw_response的读取方法变成了协程，Text Completions以及temperature/top_p/top_k参数已被移除，AnthropicBedrock在未指定区域时拒绝构造。¹ 您可以对照官方迁移指南手动逐项处理，也可以让Claude Code通过/claude-api upgrade python完成修改，然后审阅diff。¹³ Claude Code的发布说明将其称为/claude-api upgrade；迁移指南加上了python参数，这才是实际要输入的形式。¹³ 两条路线殊途同归，下文分别介绍，内容以anthropic 1.0.0为准（2026年8月20日发布于PyPI；8月25日核对）。²

TL;DR

• 使用pip install --upgrade "anthropic>=1,<2"升级，然后运行pyright或mypy：迁移指南指出，类型检查器几乎能标记出每一处破坏性变更，这就是一份现成的检查清单。¹
• Python 3.10是新的最低版本。 环境的其他方面无需改动；SDK仍然同时支持Pydantic v1和v2。¹
• httpx变成了httpx2。 像timeout=30.0这样的普通值继续可用；传给客户端的httpx对象必须来自httpx2，而那些给httpx打补丁的库在您调用httpx2.alias_httpx()之前将看不到SDK的请求。¹
• 已移除：Text Completions、采样参数，以及output_format中的schema字典。 client.completions.create()、temperature、top_p和top_k均已移除；schema字典改为放入output_config={"format": {...}}。¹
• Claude Code v2.1.239（2026年8月21日）新增了/claude-api upgrade，用于将Python项目从anthropic 0.x迁移到1.x。³ 对待它的输出要像对待任何自动化迁移一样：提交之前先阅读diff。

升级到anthropic 1.0时会有哪些破坏性变更？

六项变更占据了大部分分量；我将指南中的快速参考浓缩为这六项，较小的移除项随后列出。¹ 其中最大的一项原因很简单：SDK的HTTP层从已不再积极维护的httpx迁移到了httpx2，后者是由Pydantic团队维护的API兼容分支，类相同、行为相同，并包含安全修复。¹

此外还有一些较小的移除项和一处行为变更，每一项都有对应的替代方案：¹

最后一行的影响不易察觉：default_headers={"USER-AGENT": "my-app/1.0"}现在会替换SDK自身的User-Agent，而不是两者同时发送。¹

如何手动迁移？

三个步骤，按顺序进行：升级，让类型检查器找出破坏之处，然后按类别修复。

pip install --upgrade "anthropic>=1,<2"
pyright   # or mypy

先修复httpx的导入，因为它们的报错最为显眼。SDK自身的重新导出（anthropic.Timeout、anthropic.DefaultHttpxClient、anthropic.DefaultAsyncHttpxClient、anthropic.DefaultAioHttpClient）已经指向httpx2并继续可用；只有直接从httpx构建的对象才需要别名。¹

# Before
import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# After
import httpx2 as httpx  # or `import httpx2` and rename the references
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

如果应用中的其他代码仍然导入httpx并与SDK共享客户端或异常类型，或者您使用了OpenTelemetry的HTTPXClientInstrumentor、Sentry的httpx集成、respx、pytest-httpx或vcrpy，请在入口文件的开头调用一次httpx2.alias_httpx()。它必须在任何代码导入httpx之前运行（否则会抛出RuntimeError），而且指南将其限定为应用程序专用：库绝不应代替其用户调用它。¹ 在pytest环境下，指南给出的侵入性最小的方案是一个早期加载的插件，即一个调用httpx2.alias_httpx()的tests/_alias_httpx.py模块，并在pyproject.toml中注册，使其先于respx、pytest-httpx和您的测试模块加载：¹

# tests/_alias_httpx.py
import httpx2

httpx2.alias_httpx()  # makes `import httpx` / `import httpcore` resolve to httpx2 / httpcore2

# pyproject.toml
[tool.pytest.ini_options]
addopts = "-p tests._alias_httpx"
pythonpath = ["."]

响应和错误对象现在都是httpx2类型。 这次包的更换不仅影响您传入的内容，也影响SDK返回的内容。APIStatusError.response、APIConnectionError.request、原始响应上的response.http_response/.headers/.url，以及自定义http_client事件hook接收到的response=参数，全都是httpx2对象。它们携带的属性与之前完全相同，因此只有那些明确写出httpx.Response/httpx.Request/httpx.Headers的isinstance检查和类型注解需要改为httpx2。¹ isinstance这种情况值得再看一眼。指南只说这类检查必须改过来；¹ 而它们之所以重要，是因为除非httpx2.alias_httpx()已经让httpx解析为httpx2，否则像isinstance(err.response, httpx.Response)这样针对旧包的检查会静默返回False而不抛出任何异常，处理程序随即跳过对应的分支。

# Before
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx.Response = err.response
    print(response.status_code, response.headers.get("request-id"))


# After
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx2.Response = err.response
    print(response.status_code, response.headers.get("request-id"))

接下来是原始响应的读取方法。 .with_raw_response过去对两种客户端都返回LegacyAPIResponse；现在它返回的是.with_streaming_response早已在用的APIResponse/AsyncAPIResponse类。¹

然后是已移除的参数。 当前的模型不再使用temperature、top_p或top_k，因此生成的方法不再接受它们。早于这一变更的模型仍然可以通过extra_body识别这些参数，SDK会将其原样合并进请求JSON。¹

# Before
client.messages.create(..., model="claude-sonnet-4-6", temperature=0.2)

# After
client.messages.create(..., model="claude-sonnet-4-6", extra_body={"temperature": 0.2})

schema字典的迁移方式相同：beta.messages.create()上的output_format={"type": "json_schema", "schema": ...}变为output_config={"format": {"type": "json_schema", "schema": ...}}；parse()/stream()/count_tokens()/tool_runner()这些辅助方法在传入类时仍使用output_format=Order，而在那里传入schema字典现在会抛出TypeError。¹

最后处理Bedrock。 AnthropicBedrock和AsyncAnthropicBedrock过去会记录一条警告并回退到us-east-1；现在它们会在构造时抛出ValueError。区域的解析顺序为：先看aws_region=，再看AWS_REGION/AWS_DEFAULT_REGION，最后看指定aws_profile对应的boto3会话。¹ SDK现在还会跳过过去会产出的未知Bedrock流式事件；目前已知的唯一案例是amazon-bedrock-invocationMetrics。¹

如何使用Claude Code迁移？

迁移指南本身就点明了这条捷径：在项目中运行/claude-api upgrade python，然后审阅diff。¹ 该命令随2026年8月21日发布的Claude Code v2.1.239落地；发布说明全文如下：“Added /claude-api upgrade to migrate Python projects from anthropic 0.x to 1.x, and updated the skill’s Python reference for 1.x (timeouts use anthropic.Timeout, not httpx.Timeout)”（大意：新增/claude-api upgrade用于将Python项目从anthropic 0.x迁移到1.x，并将该skill的Python参考更新至1.x，超时设置使用anthropic.Timeout而非httpx.Timeout）。³

这句话就是全部已验证的信息：一条/claude-api skill命令，把项目中的0.x用法迁移到1.x。关于它如何决定所做的修改，我没有找到更多文档，所以就把它当作它本来的样子：一次由您来审阅diff的自动化迁移。更新到v2.1.239或更高版本（执行claude update，或参阅安装与更新参考），在项目根目录打开一个会话，然后运行：

/claude-api upgrade python

然后逐块阅读diff，运行类型检查器，再运行测试套件，就像审阅贡献者提交的迁移PR一样。类型检查这一步在这里比平时更重要，因为几乎每一处1.0的破坏性变更都是类型错误，而类型检查并不在乎修改出自谁手。¹ 发布说明特别点出的一个细节，即使用anthropic.Timeout而非httpx.Timeout，与指南一致：该重新导出已经指向httpx2。¹³

初次接触Claude Code？快速入门介绍了第一次会话，完整指南则涵盖内置skills和slash命令。

常见问题

anthropic 1.0是否仍然支持Pydantic v1？

是的。SDK仍然同时支持Pydantic v1和v2；Python 3.10的最低版本要求是唯一的环境变化。¹

为什么升级后我的OpenTelemetry或respx配置看不到SDK的请求了？

这些库给httpx打补丁，而SDK已不再使用httpx。请在任何代码导入httpx之前调用httpx2.alias_httpx()；此后整个进程中的import httpx都会解析为httpx2。¹

我还能向较旧的模型传递temperature吗？

可以，通过extra_body={"temperature": 0.2}传递，SDK会将其合并进请求JSON。对于messages.batches.create()，请将该键直接放入请求的params字典中。¹

tool_runner中的客户端压缩被什么取代了？

服务端压缩：向tool_runner()传入betas=["compact-2026-01-12"]和context_management={"edits": [{"type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100_000}}]}。在指南的示例中，这一对参数取代了compaction_control={"enabled": True, "context_token_threshold": 100_000}；触发阈值必须至少为50,000个token。¹

我需要从requirements中移除httpx_aiohttp吗？

需要。anthropic[aiohttp]和http_client=DefaultAioHttpClient()的用法与之前相同，但该extra不再安装httpx_aiohttp，因为它现在已随SDK内置。¹

要点回顾

对于应用开发者： - 锁定"anthropic>=1,<2"，运行类型检查器，然后按类别依次修复：httpx导入、原始响应的await、已移除的参数、Bedrock区域。¹ - 如果进程中还有其他代码与SDK共享httpx对象或对httpx进行监测埋点，请把httpx2.alias_httpx()放在入口文件的最前几行。¹

对于库维护者： - 绝不要在库内部调用httpx2.alias_httpx()；改用导入别名（import httpx2 as httpx）。¹ - 弃用anthropic.Transport/ProxiesTypes，改用httpx2.BaseTransport/httpx2.Proxy。¹

对于使用Claude Code的团队： - 更新到v2.1.239或更高版本，在项目根目录运行/claude-api upgrade python；审阅diff，然后在提交前运行类型检查器和测试。¹³

参考资料