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相容的分支（fork），類別相同、行為相同，並納入了安全性修正。¹

此外還有幾項較小的移除與一處行為變更，每一項都有對應的替代方案：¹

最後一列的影響不易察覺：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與斜線指令。

常見問題

anthropic 1.0是否仍支援Pydantic v1？

是的。SDK仍同時支援Pydantic v1與v2；Python 3.10的最低版本要求是唯一的環境變化。¹

為什麼升級後我的OpenTelemetry或respx設定看不到SDK的請求了？

這些函式庫對httpx打補丁，而SDK已不再使用它。請在任何程式碼匯入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，然後在提交前執行型別檢查器與測試。¹³

參考資料