結論：versionだけ上げず、互換性を5領域で先に確認する

Anthropic Python SDK v1への移行は、Python実行環境、削除されたAPI、HTTP client、非同期response、provider設定の5領域を検査してから行います。2026年8月20日の公式release notesではv1.0公開、Python 3.10以上、HTTP層のhttpx2移行、長期非推奨機能の削除などが案内されました。安全な順序は依存箇所の棚卸し、test固定、staging更新、少量traffic、全体更新です。

読者の具体的な困りごとは、requirementsのversionだけを書き換えた結果、起動時ではなく本番の特定経路でparseやparameter errorが起きることです。読了後には、自社serviceを今すぐ更新できるか、改修後に更新するか、当面固定するかを判断できます。次の行動は、repositoryごとにPython version、SDK version、Text Completions、sampling parameter、raw response、Bedrock regionの利用有無を一枚へ記録することです。

公式仕様、提供条件、料金、制限を確認する

Claude Platform release notesはAnthropic Python SDK v1.0を正式公開し、HTTP層がhttpxからAPI互換forkのhttpx2へ移ったと説明しています。v1.0はPython 3.10以上を要求します。旧Pythonを使うLambda layer、container base image、社内batchが一つでもあれば、SDKだけを先に上げられません。CIのversion表記ではなく、本番image内のinterpreterを正本にします。

公式migration guideでは、削除・変更されたsurfaceをbefore/afterで確認できます。長期非推奨のText Completions API、Messages method上のtemperature、top_p、top_k、tool runnerのclient側compaction_controlが対象です。これはClaude API全体でsamplingが使えないという意味ではなく、SDKの特定methodからの渡し方が変わるため、使用methodと現行signatureを照合します。

SDK v1への更新そのものに追加料金が設定されたという案内ではありません。費用は選ぶClaude model、input/output token、prompt caching、batch、AWS Bedrockなど利用経路の公式料金で決まります。SDK更新によりretryやrequest数が変われば請求へ影響し得るため、更新前後のrequest数とtoken量を比較します。rate limitもSDKのversionではなく、Claude APIの契約tierと公式rate limitsを公開直前に確認します。

現行版とv1を5軸で比較する

  1. 実行環境：旧環境はPython 3.9以下でも動く場合がありますが、v1は3.10以上が必須です。
  2. HTTP層：直接patchしない通常利用は影響を抑えやすい一方、trace、mock、custom transportはhttpx2対応を確認します。
  3. API surface：非推奨機能を残すcodeは失敗します。名前検索だけでなくruntime testで確認します。
  4. 非同期処理：.with_raw_responseの結果はawait response.parse()が必要です。
  5. provider：AnthropicBedrockはAWS region未設定時に既定のus-east-1へ進まずerrorになります。

比較表を作る時は「変更あり」だけで終えず、対象service、owner、test case、rollback version、完了日を付けます。sync clientしか使わないserviceにasync変更を広げる必要はありません。Bedrockを使わないserviceへAWS対応を持ち込む必要もありません。影響範囲を小さく分けるほど、障害時に原因を戻しやすくなります。

custom HTTP clientではtimeout、proxy、TLS、connection pool、retry、telemetryを確認します。DefaultHttpxClient helperは変更なしと案内されていますが、内部module名を前提にしたinstrumentationは別です。unit testがHTTP responseを固定し過ぎている場合、実serviceへ到達しないcontract testを一つ追加します。

安全に移行する8手順

  1. 全repositoryでAnthropic SDKのversion、Python runtime、deployment imageを台帳化します。
  2. 公式release notesとv1 migration guideを読み、該当する変更だけをchecklistへ移します。
  3. Text Completions、削除parameter、client-side compactionを使う経路へ回帰testを追加します。
  4. custom client、trace、mock、proxyを使うserviceはhttpx2で接続・timeout・例外型をtestします。
  5. async raw responseはparse完了までawaitし、parse失敗とHTTP失敗を別々に観測します。
  6. Bedrock利用環境ではregionを明示し、認証情報、model availability、data locationも確認します。
  7. stagingで代表request、stream、tool use、retry、429、5xxを実行し、旧版との差分を保存します。
  8. 一部instanceへcanary配備し、error率、latency、request数、token費用が許容内なら全体へ進めます。

rollbackはlock fileを戻すだけでなく、container image、Lambda layer、fixture、databaseへの保存形式まで対象にします。v1向けcodeを旧SDKで動かせない場合は、feature flagで両経路を混在させず、deploy単位で戻します。更新期間中は自動dependency updateを止め、意図したversion以外が混ざらないようhashを固定します。

企業運用チェックリストとHOLD条件

  • 公式情報を2件以上確認した
  • Python 3.10以上を本番で確認した
  • 全SDK利用serviceを列挙した
  • 削除APIを確認した
  • sampling parameterの渡し方を確認した
  • httpx2のtraceをtestした
  • mockが実requestを隠していない
  • async parseをtestした
  • AWS regionを明示した
  • 429と5xxのretry上限がある
  • canary指標がある
  • 費用差分を観測する
  • rollback imageがある
  • 更新ownerと期限がある

HOLD条件は、本番Python versionが不明、Text Completionsの残存を判断できない、custom transportのtestがない、async responseを未検証、Bedrock regionとdata locationが未承認、rollback artifactがない場合です。v1は正式版でも、自社の依存packageと運用が自動的に互換になるわけではありません。

よくある質問と次の行動

すべてのserviceを同日に更新すべきですか？

いいえ。依存が少ないserviceからcanaryし、共通library、重要batch、顧客向けAPIの順に影響度で分けます。

Python 3.10へ上げれば十分ですか？

不十分です。削除surface、HTTP層、async parse、Bedrock regionも個別に確認します。

旧版を固定し続けてもよいですか？

短期rollbackには有効ですが、security修正とsupport期間を追跡し、期限付きの移行計画を置きます。

一次情報はClaude Platform release notes、Python SDK公式文書、公式v1 migration guideです。関連するhttpx2移行、Bedrock region確認、API費用削減も確認してください。Miraigentの無料診断では、SDK依存、test、canary、rollbackを60秒で整理します。