/claude-api upgradeでPython SDKをv0.xからv1へ移行する

/claude-api upgradeとは何か

/claude-api upgradeは、プロジェクトが依存するAnthropicのSDKをメジャーバージョンをまたいで移行するClaude Codeのコマンドです。対象は現状Pythonのanthropicパッケージに限られ、v0.x系からv1系への移行を担います。claude-apiスキルに含まれるサブコマンドの1つです。最低版はスキル解説の表ではv2.1.236以降、変更履歴ではv2.1.239での追加とされ、確実に使うならv2.1.239以降です。

anthropicパッケージは2026年8月20日にv1.0.0をリリースし、HTTPライブラリの刷新や非推奨パラメータの削除など複数の破壊的変更を伴いました。手作業で1つずつ潰していくと見落としが出やすい変更点ですが、/claude-api upgrade pythonはこの差分をコード側に反映する提案をdiffとして生成します。

2026年10月21日にはv2.0.0が出ており、APIバージョン2026-10-21への切り替えを伴います。Claude Codeのスキル解説はupgradeの対象を「0.xから1.xへの移行」としており、v1からv2への移行はv2.0.0の変更点の節にある項目を、公式の移行ガイドに沿って自分で確認する形になります。claude-apiスキル自体の自動起動条件やほかのサブコマンドとの役割分担はclaude-apiスキルでAPI移行を自動化するにまとめています。

実行前に確認する前提条件

Claude CodeのバージョンとプロジェクトのPython実行環境の2点を先に確認します。upgradeサブコマンドを確実に使えるのはClaude Code v2.1.239以降です。/statusでバージョンを確認し、足りなければ更新してから進めます。

Python側では、v1系のanthropicパッケージがサポートする最低バージョンが3.9から3.10へ引き上げられています。プロジェクトが3.9で動いている場合は、SDKのアップグレードに先立ってPythonランタイム自体の更新が必要です。Pydantic v1・v2はどちらも引き続きサポートされるため、Pydanticのバージョンを気にする必要はありません。

対象言語はPythonのみです。TypeScript版の@anthropic-ai/sdkはこのサブコマンドの対象に含まれず、/claude-api upgradeを実行してもPythonプロジェクト向けの提案しか出てきません。

/claude-api upgrade pythonを実行する手順

プロジェクトのルートでClaude Codeを開き、次のコマンドを実行します。

/claude-api upgrade python

実行するとClaude Codeがプロジェクト内のanthropicパッケージの使用箇所を走査し、v1移行に必要な変更点をdiffとして提示します。ここで重要なのは、提案されたdiffをそのまま適用せず内容を確認することです。破壊的変更にはhttpxからhttpx2への切り替えのように影響範囲が広いものと、非推奨パラメータの削除のように該当箇所が少ないものが混在しており、プロジェクト固有の使い方(独自のHTTPクライアント設定やBedrock経由の呼び出しなど)によって、提案された変更で十分かどうかが変わります。

diffを確認したうえで問題なければ適用し、型チェッカー(pyrightやmypy)があれば合わせて走らせます。移行ガイドの多くの変更は型エラーとして検出できる設計になっているため、型チェッカーを普段使っていない場合でも、このタイミングだけ走らせるとチェックリスト代わりになります。

手動でアップグレードする場合の手順

Claude Codeを使わずに手動でアップグレードすることもできます。まずパッケージをv1へ更新します。v2へ進む場合は<2の上限を外し、次の節の変更点を合わせて確認します。

pip install --upgrade "anthropic>=1,<2"

この時点でインポートやAPI呼び出しの多くが型エラーまたは実行時エラーになります。次の3節で扱う変更点を1つずつ潰していく作業が必要です。手動で進める場合は、後述の「何が壊れるか」を上から順にチェックリストとして使うと、/claude-api upgradeが生成するdiffに近い網羅性を手作業でも再現できます。

何が壊れるか — httpx2への移行が影響する範囲

v1系のSDKは、HTTP層をhttpxからhttpx2という別パッケージへ切り替えています。httpx2はPydanticチームが保守するフォークで、クラス構成・挙動ともにhttpxと互換性がありますが、パッケージとしては別物です。影響が出るのは、SDKにhttpxのオブジェクトを渡している、またはSDKから返ってきたhttpxオブジェクトを直接扱っているコードに限られます。タイムアウトやリトライ回数を数値で渡しているだけのコードには影響しません。

# 移行前
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",
    ),
)
 
# 移行後
import httpx2 as httpx
from anthropic import Anthropic, DefaultHttpxClient
 
client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
    ),
)

importをhttpx2 as httpxに変えるだけで済むケースが大半です。アプリケーション側にもhttpxを使っているコードが残っていて、SDKと同じクライアントやtransportを共有したい場合は、起動時に一度だけhttpx2.alias_httpx()を呼ぶ方法もあります。これを呼ぶと、以降のimport httpxが自動的にhttpx2に解決されます。ただしalias_httpx()は他のどこかが先にhttpxをimportした後に呼ぶとRuntimeErrorになるため、エントリーポイントの一番先頭で呼ぶ必要があります。

もう1つ見落としやすいのが、OpenTelemetryのHTTPXClientInstrumentorやSentryのhttpx連携、respx・pytest-httpx・vcrpyのようなトレーシング・モックライブラリです。これらはhttpxパッケージ自体にパッチを当てる方式のため、SDKがhttpx2に切り替わるとエラーにならずに黙って計測・モックの対象から外れます。テストが通っているように見えても実際にはHTTPリクエストがモックされていない、という事故につながるため、該当するライブラリを使っている場合はalias_httpx()を早期に呼ぶ対応が要ります。

レガシーAPIと非推奨パラメータの削除

v1では、長らく非推奨だったAPIとパラメータがまとめて削除されています。

Text Completions APIは2023年以降Messages APIへの移行が案内されてきた経緯があり、v1での削除はその総仕上げにあたります。temperature・top_p・top_kはAPI自体からパラメータが消えたわけではなく、現行モデルが参照しなくなったためSDKのメソッド引数から外れました。まだこれらのパラメータを使う旧モデルにピン留めしている場合、v1ではextra_body={"temperature": 0.2}のように生のリクエストボディへ渡す形に書き換えられます。ただしこの回避策が使えるのはv1までです。v2が送るAPIバージョン2026-10-21では、この3つを含むリクエストは既定値のままでも400エラーになります。

.with_raw_responseが返すクラスも変わりました。従来は同期・非同期どちらもLegacyAPIResponseでしたが、v1では.with_streaming_responseと同じAPIResponse / AsyncAPIResponseに統一されています。非同期クライアントでは.parse() / .text() / .read() / .json()がawait必須のコルーチンになった点が、実行時エラーとして最も気づきやすい変更です。

型・エクスポート名の変更もいくつかあります。ベータ版のPDFブロック型BetaBase64PDFBlockParamはBetaRequestDocumentBlockParamに、anthropic.Transport / anthropic.ProxiesTypesはhttpx2.BaseTransport / httpx2.Proxyに、エージェントツールセットのagent_toolset.READ_MAX_BYTESはagent_toolset.DEFAULT_MAX_FILE_BYTESに、それぞれ名前が変わっています。aiohttpを使っている場合、pip install anthropic[aiohttp]というインストール手順自体は変わりませんが、これまで別パッケージとして入っていたhttpx_aiohttpはSDK内部に同梱される形になったため、依存関係の一覧から明示的に外せます。

Bedrockを使っている場合に増える確認点

AnthropicBedrock / AsyncAnthropicBedrock経由でClaudeを呼んでいるプロジェクトには、追加の変更が2つあります。1つ目はリージョン指定の必須化です。従来はリージョンが特定できないと警告を出したうえでus-east-1へ暗黙にフォールバックしていましたが、v1ではクライアント生成時にValueErrorを送出するようになりました。aws_region=引数、AWS_REGION / AWS_DEFAULT_REGION環境変数、boto3プロファイルの設定のいずれかでリージョンを明示する必要があります。

2つ目はストリーミングイベントの扱いです。Bedrock APIが返す未知のストリーミングイベントは、従来はそのまま素通しされていましたが、v1では読み飛ばされるようになりました。公式ドキュメントが影響を挙げているのはamazon-bedrock-invocationMetricsイベントのみです。このイベントを参照する実装をしていた場合は、値の取得方法を作り直す必要があります。

v2.0.0で増える変更点

v2.0.0(2026年10月21日)は、v1の移行を済ませたコードにもう一段の破壊的変更を持ち込みます。SDKが送るAPIバージョンが2023-06-01から2026-10-21に変わるため、パラメータの削除はSDKの型だけでなく、リクエストを受けるAPI側でも効きます。

APIキーの送り方も変わります。v1まではX-Api-Keyヘッダーでしたが、v2のAnthropic / AsyncAnthropicはAuthorization: Bearer <キー>で送ります。APIはどちらのヘッダーも受け付けるので、SDKから直接APIを呼ぶだけなら何も起きません。影響が出るのは、X-Api-Keyを読む社内プロキシやゲートウェイ、ログのマスク処理、テストのスタブです。extra_headers={"X-Api-Key": omit}でキーを外していたコードは{"Authorization": omit}に、extra_headers={"X-Api-Key": 別のキー}で上書きしていたコードは{"Authorization": f"Bearer {別のキー}"}に直します。後者は直さないとキーが2つ送られます。AnthropicFoundryは従来どおりx-api-keyで、AnthropicBedrockMantleは元からBearerトークンです。

認証情報も1クライアントにつき1つになりました。api_key・auth_token・credentials・config・profileのうち2つ以上をコンストラクタやcopy()・with_options()に渡すとValueErrorになります。v1ではAPIキーと認証トークンを両方持たせると、それぞれ別のヘッダーで送られていました。ゲートウェイ向けのトークンとAPI向けのキーを併用していた構成は、組み直しが必要です。

型まわりでは、MessageParamとBetaMessageParamがUserMessageParam・AssistantMessageParam・SystemMessageParamの3種のユニオンになりました。{"role": "user", "content": "Hello"}のような辞書リテラルと、list[MessageParam]のような型注釈はそのまま動きます。壊れるのはMessageParam(role=..., content=...)と呼び出す書き方と、継承する書き方で、どちらもTypeErrorです。呼び出しは辞書に、継承は役割ごとの型に変えます。roleが変数で複数の値を取りうる辞書は、型チェッカーが3種のどれにも一致させられないので、役割ごとに分岐して辞書を作ります。

そのほか、リクエスト側では、assistantメッセージに直接置いたdocumentブロックと、userメッセージのtextブロックに付けたcitationsが400になります。client.models.retrieve()とclient.models.list()はbetasを受け取らなくなり(TypeError)、client.beta.models側を使います。Amazon Bedrockで2026-10-21が使えるのはClaude 4.7以降のモデルだけなので、それより古いモデルを呼ぶ呼び出しは、今のSDKバージョンのまま据え置くか、モデルを移してからv2へ進みます。

よくあるつまずき

• importを変えたのにisinstanceチェックが効かない: client.messages.stream()が返すMessageStream / AsyncMessageStreamは、以前からStream / AsyncStreamを継承していません。互換性のためのDeprecationWarning付きシムがv1で削除され、isinstance(obj, Stream)は常にFalseを返すようになりました。ストリームオブジェクトの判定にはMessageStreamを直接使います
• ヘッダーを2通りの大文字小文字で送っていたコードが1通りに減る: v1ではヘッダー名の大文字小文字を区別せずに扱うため、default_headersとextra_headersで同名ヘッダーを別の大文字小文字で重ねて送る使い方は、後から指定した側に上書きされます。2行分のヘッダーを意図的に送っていた場合は、カンマ区切りで1つの値にまとめる書き方に直します
• bytes型のヘッダー値がエラーになる: 型注釈上は許可されていなかったものの実際には動いていたbytes型のヘッダー値が、v1では例外を送出するようになりました。.decode()して文字列にしてから渡します
• 低レベルのclient.post()などでbody=bytesを渡すコードが壊れる: body=は常にJSONシリアライズされる仕様になったため、生バイト列を送る場合はcontent=引数に切り替えます
• messages.parse(stream=True)が動かなくなる: この引数はもともと機能していなかった経緯がある引数で、parse() / beta.messages.parse()から削除されました。ストリーミングしながら構造化出力を受け取りたい場合はmessages.stream(..., output_format=Model)に置き換えます
• tool_runner(compaction_control=...)が使えなくなる: クライアント側で会話を要約していたcompactionは廃止され、API側で要約するサーバーサイドcompactionに一本化されました。betas=["compact-2026-01-12"]とcontext_managementのeditsでトリガー条件(閾値は5万トークン以上)を指定する形に書き換えます

手動アップグレードと/claude-api upgradeの使い分け

いずれの方法でも、pyright・mypyのような型チェッカーを一度走らせておくと、移行ガイドに載っている変更のほとんどが型エラーとして表面化します。型チェッカーを普段使っていないプロジェクトでも、アップグレード作業の最終確認としてこのタイミングだけ導入する価値があります。

まとめ

/claude-api upgrade pythonは、Claude Code v2.1.239以降なら確実に使えるPython版anthropicパッケージのv0.x→v1移行コマンドです。破壊的変更の中核はhttpxからhttpx2への切り替えで、SDKにhttpxオブジェクトを直接渡していないコードへの影響は限定的です。一方でText Completions APIの削除、temperature等パラメータの削除、.with_raw_responseの非同期化、Bedrockのリージョン必須化は、使っていれば確実に手を入れる必要がある変更です。Claude Codeに提案させたdiffもそのまま適用せず、型チェッカーで再確認してから反映するのが安全な進め方です。v2.0.0ではサンプリング引数が400になり、APIキーがBearerで送られるため、v1への移行を終えたコードでもプロキシの設定とモデルごとのtemperature依存を洗い直す必要があります。関連するモデル移行の作業は/claude-api prompt-auditで古いモデル向けの記述を検出する、Agent SDK側の破壊的変更はAgent SDK移行ガイドで扱っています。