Anthropic Python SDK 1.0がhttpx2へ移行、従来のトレーシングやmockが気付かないまま機能しなくなる可能性

Anthropicは8月20日、Python SDK 1.0をリリースした。最も重要な基盤変更は、HTTPクライアントをhttpxから、Pydanticチームが保守する互換フォークhttpx2へ切り替えたことだ。数値のタイムアウト値やリトライ回数など、一般的な値だけを渡すアプリケーションは通常、そのまま動作する。一方、独自にClient、Timeout、transport、proxy、イベントhookを構築しているプログラムは、httpx2のクラスへ移行する必要がある。旧来のhttpx.ClientをSDKへ渡すと直ちにTypeErrorが発生する。しかし、httpxへのpatchによってトラフィックをインターセプトするOpenTelemetry、Sentry、RESPX、pytest-httpx、VCRなどのツールは、実行を継続しながらClaudeへのリクエストを一切検出できない可能性があり、より発見しにくいオブザーバビリティの欠落につながる。公式はプロセス全体に適用する互換策としてhttpx2.alias_httpx()を提供しているが、これはいずれかのモジュールがhttpxを読み込む前に呼び出さなければならず、ライブラリ側が下流アプリケーションに代わって有効化すべきではない。

今回のメジャーバージョンでは、複数の旧インターフェースも整理された。最低実行環境はPython 3.9から3.10へ引き上げられ、client.completions.create()、従来のText Completions型、HUMAN_PROMPT、AI_PROMPTはすべて削除された。Messagesメソッドのtemperature、top_p、top_kは正式なシグネチャから外され、旧モデルでこれらを制御する必要がある場合はextra_body経由でのみ送信できる。非同期の.with_raw_responseにおけるparse()、text()、read()は、今後awaitが必要となる。ツール実行機能のクライアント側compaction_controlも、サーバー側のcontext managementに置き換えられた。BedrockユーザーがAWS regionを設定していない場合も、従来のデフォルト値us-east-1は使用されず、直接エラーが返される。

エンジニアリングチームは、今回のアップグレードを通常の依存関係更新として扱うべきではない。より安全な方法は、まず0.x系を固定し、独立したブランチでアップグレードしたうえで、型チェック、HTTP mock、APM trace、proxy、エンタープライズCAのテストを実行し、さらにStructured Outputsと非同期raw responseのコードパスを確認することだ。公式の移行ガイドは非常に充実しているものの、サードパーティ製モニタリングパッケージによるhttpx2のサポート状況は、個別に検証する必要がある。