AIREITERAnthropic Python SDK v1.0 在 2026 年 8 月 20 日登上 PyPI。多數既有呼叫程式碼升級後照樣能跑，真正需要警惕的反而是看不見的變化：SDK 的 HTTP 層從 httpx 換成 httpx2。原本透過 patch httpx 監控流量的 tracing、APM agent 與測試 mock，可能完全不報錯、持續運作，卻悄悄地記錄不到任何 SDK 請求。升級後測試全綠，不代表事情真的沒問題。
兩天內連發三版，接著直接進入 1.0
從 anthropic 的 PyPI 發布紀錄，可以很清楚看出這次節奏：0.123.0、0.124.0 與 0.125.0 都在 2026 年 8 月 19 日推出，隔天 8 月 20 日便透過標準 Trusted Publishing 流程發布 1.0.0。
依照官方 release notes，這次重點如下：
- HTTP 層由
httpx改為httpx2，後者是仍在維護、且 API 相容的 fork。 - 最低版本要求改為 Python 3.10；套件 classifiers 列出支援 3.10 至 3.14。
- 長期標記為 deprecated 的功能正式移除，包括舊版 Text Completions API、Messages 方法上的
temperature、top_p、top_k參數，以及 tool runner 在 client 端的compaction_control。 AnthropicBedrock未設定 AWS region 時，現在會直接拋出錯誤，不再默默預設為us-east-1。
GitHub 的 v1.0.0 tag 將這次更新描述為「升級至 httpx2，以及一些小型 breaking changes」。還有一個在 release notes 裡不太顯眼的變化：parse、stream 與 tool_runner helper 上的 beta 警告已經移除。版本來到 1.0、同時拿掉 beta 註記，代表 Anthropic 現在應已將這組 API 視為穩定介面。
httpx 換成 httpx2，實際影響在哪裡？
只要你用最單純的方式建立 client，幾乎不會感覺到變化；一旦碰到 HTTP 層，影響就全面浮現。
關鍵在於傳給 client 的東西是數值還是物件。數值仍可直接使用，例如 Anthropic(timeout=30.0) 行為完全不變。但傳入一般 httpx.Client 作為 http_client=，現在會在建立 client 當下就拋出 TypeError，不是等到第一次送出請求才失敗。自訂 client、timeout 與 transport 都必須改用 httpx2 建立；原本是 httpx.Timeout 物件的 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 建議的 timeout、連線池與 redirect 預設值，只是底層現在改走 httpx2。Anthropic 平台 devx 工程師 @cjav_dev 的公告也指向同一個起點：官方的 MIGRATION.md，裡面列出了每項變更的前後程式碼範例。
這種遷移方式其實已有先例。OpenAI Python SDK 的 httpx2 遷移指南先走過幾乎一樣的路：同一個 fork、相同的 DefaultHttpx2Client helper 模式，也有同樣的 respx 相容性警告。已經遷移過 openai 的團隊，大致可以直接沿用原有做法。
v1.0 正式移除的功能清單
| v1.0 移除項目 | 替代做法 |
|---|---|
client.completions.create()（Text Completions） | client.messages.create() |
HUMAN_PROMPT / AI_PROMPT 常數 | 採用 Messages 格式的 content blocks |
方法簽名中的 temperature、top_p、top_k | 仍接受這些參數的舊版模型可使用 extra_body={"temperature": ...} |
messages.parse(stream=True) | messages.stream(...) |
tool_runner(compaction_control=...) | 改用 server-side compaction 設定 |
anthropic.Transport、anthropic.ProxiesTypes aliases | httpx2 transport types |
低階 request 方法的 body= | content= |
beta API 的 output_format schema dict | output_config={"format": ...}（structured-output helpers 仍接受 output_format=MyModel） |
isinstance(stream, anthropic.Stream) 檢查 | 檢查具體的 MessageStream 型別 |
這份表還有兩點值得補充。Pydantic v1 和 v2 都仍受支援，因此 model classes 不受影響。此外，header 合併現在不分大小寫；如果你曾用不同大小寫重複設定同一個 header，行為會有所改變。這是少見情境，但發生時不會出現任何錯誤提示。
只有 raw response 使用者會踩到的 async 變更
非同步相關的調整範圍不大，但若你使用 .with_raw_response，可能相當棘手。async client 上的 parse()、read()、text()、json() 現在都必須加上 await。至於 sync client，.text 與 .content 已從 property 改成 method。這兩類問題都不會在 import 時暴露：sync 版本會很明顯地噴出 attribute error；async 版本則更隱晦，因為你可能拿到一個從未執行的 coroutine，卻沒有 await 它。
另外，exceptions 與 raw results 中的 request、response 物件現在都是 httpx2 型別。大部分 attribute 存取方式相同，但像是 isinstance(x, httpx.Response) 這類判斷，以及型別註記，都得一併更新。這正是 pyright 與 mypy 很適合協助揪出的問題。
最危險的是你根本看不見的遷移失敗
changelog 對這件事只有一句話，但你的監控儀表板可能不會這麼寬容。根據 Anthropic 的遷移指南，若工具是透過 patch httpx 來觀察或 mock HTTP 流量，例如 OpenTelemetry、Sentry、respx、pytest-httpx、vcrpy，升級後可能繼續正常執行，卻完全漏掉 SDK 請求。這些工具照樣能 import、照樣跑、照樣產出報告，只是它們 patch 的函式庫已不再承接 SDK 流量。若測試中的 mock 沒有明確斷言攔截確實發生，測試甚至可能在沒有任何流量抵達 mock 的情況下空泛地通過。
解法是 httpx2.alias_httpx()。請在應用程式或測試啟動流程的最早位置呼叫它；Python SDK 文件明確要求必須在任何 httpx import 之前執行。它會將 httpx2 以 httpx 的名稱建立 alias，讓既有 patch 工具繼續發揮作用。不過遷移指南也提醒：不要在 library code 裡呼叫它，只能放在 application entry point。
「應用程式能乾淨啟動，不代表你的 AI 呼叫仍有被 trace 或 mock。」— @MarMarLabs，在發布隔天的貼文
這篇貼文很值得完整閱讀。它建議把這種無形失效列為第一個遷移測試：完成升級後，刻意驗證一次 traced call 與一次 mocked call 是否仍有被記錄。同一串討論也點出其他隱性風險，包括需要手動遷移到 httpx2 的自訂 transport，以及 Python 3.10 最低版本要求會在安裝階段讓舊版 CI image 直接失敗。
哪些程式碼完全不用改？
對不少 codebase 而言，坦白說答案是：什麼都不用做。只要你從未建立自訂 client、transport 或 timeout 物件，HTTP 層的遷移就不會影響你。以下項目維持不變：
- 使用一般參數的
client.messages.create(...)呼叫，request 與 response models 都不變。 - 數值 timeout 和 SDK 預設行為：連線錯誤、408、409、429 與 5xx 時，維持 2 次指數退避重試；預設 timeout 仍是 10 分鐘。
base_url路由。若你將 SDK 指向 gateway，或是類似 AIReiter's Claude API endpoint 的 API 相容 relay，v1.0 不會改變這一層；變動的是 client，不是 URL。- Pydantic v1、v2 models、SSE streaming helpers 與檔案上傳介面。
唯一的硬性門檻是 Python 3.10 以上。上述「安全」項目都建立在你已先跨過這條門檻的前提下。
一套經得起 code review 的遷移順序
- 先明確 pin 住版本：如果現在還不能升級，使用
anthropic>=0.125,<1，先固定在 1.0 以下，安排好工作再處理。 - 在 codebase 中搜尋
import httpx與httpx.；所有出現在 SDK 相鄰程式碼中的結果，都是遷移項目。 - 在 Claude Code 執行
/claude-api upgrade python。這是 @cjav_dev 的發布公告建議的指令，可產生專案中的變更 diff。 - 使用
httpx2或DefaultHttpxClienthelpers 重建自訂 client、transport 與 timeout。 - 若任何工具會 patch
httpx，就在 application entry point 加上httpx2.alias_httpx()。 - 執行 pyright 或 mypy；httpx2 的型別變動通常會以 annotations 與
isinstance錯誤浮現。 - 在 CI 中，每個 test suite 都要斷言至少有一筆 traced request 與一筆 mocked request。啟動 log 全綠不是證據。
Anthropic Python SDK v1.0 常見問題
Anthropic Python SDK v1 已經發布了，還是仍在 0.x？
已經發布。anthropic 1.0.0 在 2026 年 8 月 20 日於 PyPI 上線，GitHub 也標記為 v1.0.0 on GitHub，前一天剛發布 0.125.0。PyPI 專案頁面目前也會將 0.x 使用者導向 v1 遷移指南。
v1.0 之後要怎麼傳入 temperature、top_p 或 top_k？
它們已從方法簽名中移除。若舊版模型在 server-side 仍接受這些值，可使用 extra_body={"temperature": 0.7} 傳入。但要注意，目前模型無論如何都會對非預設取樣值回傳 400；這是模型層的變動，不是 SDK 造成的。
respx、pytest-httpx 或 vcrpy 測試還能用嗎？
無法直接攔截 SDK 的預設 client，而且它們不會報錯，只會完全 match 不到請求。你可以在測試啟動時、任何 httpx import 之前呼叫 httpx2.alias_httpx()，或將 mock 改為 httpx2.MockTransport。僅 patch 舊版 httpx 的 respx 版本，無法攔截 SDK 流量。
/claude-api upgrade python 是做什麼的？
這是 Claude Code 指令，也是 Anthropic devx 工程師 @cjav_dev 的公告所建議的工具。它會掃描使用 anthropic 0.x 的專案，並產生遷移 diff，涵蓋 imports、timeout objects、raw-response calls 等項目，讓你先審查變更，而不是等到 tracebacks 出現才逐一處理。
繼續 pin 在 0.125，還是直接升級 1.0？
這題沒有放諸四海皆準的答案，真正的取捨如下。維持在 1.0 以下，可以讓既有 mock、tracer 和自訂 transport 完全照原本方式運作；但你會繼續使用一個尚未進入穩定版的 SDK，其版本政策允許 minor release 出現向後不相容變更，而你依賴的 deprecated 功能，例如 completions 與 sampling params，現在也已正式成為過時包袱。升級到 1.0，則能取得穩定、非 beta 的 API surface，但代價是現在就必須完整稽核 HTTP 層，而非日後再面對它。判斷關鍵在於你掌握多少 HTTP 層程式碼：只有一個普通 Anthropic() 呼叫的服務，升級幾乎毫不費力；有自訂 transport 與 respx test suite 的平台，則應在部署前先做好隱性失效檢查。
延伸閱讀：同一週脫離 beta 的 Skills API，以及 8 月 10 日 Sonnet 5 的定價轉為永久方案；兩者都屬於同一波 Claude Platform 發布更新。