結論：httpxを直接触る箇所だけを先に特定する
Anthropic Python SDK v1のhttpx2移行では、通常のMessages API呼び出しより、custom http_client、trace、mock、transport、timeoutを直接扱うcodeを優先して確認します。公式情報ではhttpx2は維持されたAPI互換forkで、DefaultHttpxClient helperは変更なしです。したがって全通信処理を書き換えず、直接依存箇所を絞ってcontract testを行います。
読者の具体的な困りごとは、API requestは成功しているのにAPM spanが消える、mockが効かず外部通信する、独自timeoutが適用されないという静かな劣化です。読了後には、aliasで対応できるか、library更新が必要か、custom clientを外すかを判断できます。次の行動は、Anthropic client生成箇所とtest fixtureを開き、httpxのimport、patch、MockTransport、Client、Timeoutの利用を分類することです。
公式仕様、提供条件、料金、制限を確認する
2026年8月20日のClaude Platform release notesは、Python SDK v1.0のHTTP layerがhttpxからhttpx2へ移行したと説明しています。custom http_client、Timeout、transport objectはhttpx2から構築します。一方、SDKのDefaultHttpxClient helperは従来どおりです。単なるclass名の置換ではなく、どのpackageがobjectを生成するかを揃える必要があります。
公式migration guideは、tracingやmocking libraryがhttpxをpatchする場合、application startupでhttpx2.alias_httpx()を呼ぶ方法を案内しています。これは全libraryの互換性を保証する魔法ではありません。import順序、worker fork、test runner、auto instrumentationの開始時刻により挙動が変わるため、実際の起動entry pointで確認します。
提供条件としてPython SDK v1はPython 3.10以上です。Claude APIのmodel料金やrate limitはHTTP layer変更と別で、公式pricingと契約tierが正本です。ただしtimeoutやretryの差で同じ処理が複数requestになれば費用とrate limit消費は増えます。更新前後でrequest ID、retry回数、input/output token、429率を比較し、「client変更だから費用影響なし」と決めつけません。
移行方法を4軸で比較する
- SDK helperを使う：独自要件が少なく最も保守しやすい方法です。proxyや証明書要件を満たすか確認します。
- httpx2 objectへ置換する：custom timeoutやtransportが必要な場合に適します。型と例外をtestします。
- aliasを使う：httpx patch前提のtrace・mockを短期互換させます。起動順と将来のlibrary対応期限を管理します。
- 旧SDKを固定する：緊急回避にはなりますが、supportとsecurity updateを逃すため期限を設定します。
選択基準はcustom要件の必要性、観測の完全性、testの実在性、移行期限です。APM vendorがhttpx2へ正式対応していればlibrary更新を優先します。対応していない場合にaliasを使うなら、span件数、status code、latency、exception、request IDが従来と一致するかをacceptance条件にします。
mockでは「testがPASSした」だけでは足りません。誤ってnetworkへ出たtestもresponse次第でPASSします。CIから外部networkを遮断し、mock呼出回数、request URL、header、bodyをassertします。streamingでは接続開始、chunk受信、途中cancel、timeout、closeまで確認します。syncとasyncはclientもlifecycleも分けてtestします。
安全に切り替える7手順
- dependency graphとlock fileからAnthropic SDK、httpx、trace、mock libraryのversionを記録します。
- client factoryを列挙し、SDK helper、custom sync、custom async、Bedrockなど経路別に分けます。
httpxを直接import・patchする箇所をtrace、test、proxy、transport、timeoutへ分類します。- 公式migration guideに沿い、必要なobjectをhttpx2から生成するbranchをstagingへ作ります。
- aliasが必要ならapplication startupの一箇所だけで実行し、workerとtest runnerのimport順を確認します。
- success、429、5xx、connect timeout、read timeout、stream cancelを実行し、spanとretryを旧版と比較します。
- 少量trafficへ配備し、error率、latency、span欠落、重複request、token費用が許容内なら拡大します。
rollback用に旧lock fileとcontainer imageを保存します。aliasを複数moduleで呼ぶ構成や、serviceごとに異なるclient factoryは運用負債になるため、移行完了後に一つへ統合します。観測が欠けた状態で「requestは成功する」と公開判定してはいけません。障害調査に必要なrequest IDと例外分類が残ることを確認します。
企業運用チェックリストとHOLD条件
- 公式情報を2件以上確認した
- Python 3.10以上を確認した
- client生成箇所を列挙した
- custom transportの理由がある
- syncとasyncを分けた
- trace spanを比較した
- mock外通信を遮断した
- timeoutを再現した
- 429 retry上限がある
- stream cancelをtestした
- request IDを保存する
- 重複requestを監視する
- 費用差分を監視する
- rollback imageがある
HOLD条件は、httpx patchの利用有無が不明、trace欠落を検知できない、mock testが外部通信可能、timeoutとretryを未検証、streamのclose確認がない、rollback versionがない場合です。aliasは暫定策として有効でも、ownerと撤去期限がないまま恒久化しません。
よくある質問と次の行動
httpxをrequirementsから消すべきですか？
他libraryが使う可能性があります。dependency graphを確認し、Anthropic SDK移行だけを理由に無条件削除しません。
aliasはどこで呼びますか？
公式案内はstartupです。instrumentationより前に一度だけ実行し、entry pointごとにtestします。
unit testだけで十分ですか？
不十分です。実network条件を再現するstaging contract testと少量trafficの観測が必要です。
一次情報はClaude Platform release notes、Python SDK公式文書、公式v1 migration guideです。関連するSDK v1全体移行、Bedrock region確認、API model選定も確認してください。Miraigentの無料診断では、client、trace、mock、retryの移行リスクを60秒で整理します。