Claude Media
/claude-api upgradeでPython SDKをv0.xからv1へ移行する
Claude Codeチュートリアル

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

Claude Codeの/claude-api upgradeがPython SDKをv1へ移行する仕組みと、手動アップグレード時に必要なhttpx2移行・削除パラメータへの対応をまとめます。

読了目安 約11分

/claude-api upgradeとは何か

/claude-api upgradeは、プロジェクトが依存するAnthropicのSDKをメジャーバージョンをまたいで移行するClaude Codeのコマンドです。対象は現状Pythonのanthropicパッケージに限られ、v0.x系からv1系への移行を担います。claude-apiスキルに含まれるサブコマンドの1つで、Claude Code v2.1.236以降で使えます。

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

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

Claude CodeのバージョンとプロジェクトのPython実行環境の2点を先に確認します。upgradeサブコマンドはClaude Code v2.1.236以降でのみ利用できるため、古いバージョンでは/claude-apiのサブコマンド一覧に表示されません。/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を使わずに手動でアップグレードすることもできます。まずパッケージを更新します。

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とパラメータがまとめて削除されています。

削除された対象代替
client.completions.create()(Text Completions API)、HUMAN_PROMPT、AI_PROMPT代替client.messages.create()(Messages API)
messages.create()等のtemperature / top_p / top_k代替現行モデルは未使用のため削除。旧モデル向けに残す場合はextra_body経由
output_format={スキーマ辞書}代替output_config={"format": {...}}。ヘルパー引数のoutput_format=は型を渡す用途のみ残る

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

.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イベントのみです。このイベントを参照する実装をしていた場合は、値の取得方法を作り直す必要があります。

よくあるつまずき

  • 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の使い分け

状況おすすめ理由
単一リポジトリでSDKの使用箇所が把握できているおすすめどちらでも可理由手動でもMIGRATION.mdのチェックリストで足りる規模
複数リポジトリ・大規模コードベースでSDK呼び出しが散在おすすめ/claude-api upgrade python理由該当箇所の洗い出しをClaude Codeに任せられる
CIパイプラインに組み込んで自動化したいおすすめ手動(pip install+型チェッカー)理由スラッシュコマンドは対話的な実行が前提
Bedrock経由でリージョン設定が環境ごとに違うおすすめ手動での個別確認理由環境差分はdiffの提案だけでは拾いきれないことがある

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

まとめ

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

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →