Anthropic Python SDK 1.0への移行：手作業か、Claude Codeか

Pythonプロジェクトをanthropic 0.xから1.0へ移行するのに必要なのは、インストールコマンド1つ、pip install --upgrade "anthropic>=1,<2"と、決まった破壊的変更のリストを一巡することだけです。HTTP層はhttpx2の上で動くようになり、非同期の.with_raw_responseリーダーはコルーチンになり、Text Completionsとtemperature/top_p/top_kパラメータは削除され、AnthropicBedrockはリージョンなしでは構築できなくなりました。¹ そのリストを公式の移行ガイドを片手に手作業でたどるか、Claude Codeに/claude-api upgrade pythonで編集を任せて差分をレビューするか、どちらかです。¹³ Claude Codeのリリースノートでは/claude-api upgradeという名前で呼ばれています。移行ガイドはそこにpython引数を加えており、実際に入力するのはこちらの形です。¹³ どちらの道も行き着く先は同じです。以下のページでは両方を取り上げます。内容はanthropic 1.0.0時点のものです（2026年8月20日にPyPIで公開、8月25日に確認）。²

TL;DR

• pip install --upgrade "anthropic>=1,<2"でアップグレードし、続けてpyrightかmypyを実行しましょう。移行ガイドによれば、型チェッカーが破壊的変更のほぼすべてを検出するため、そのまま出来合いのチェックリストになります。¹
• Python 3.10が新しい最低要件です。 環境について変わるのはそれだけで、SDKは引き続きPydantic v1とv2の両方をサポートします。¹
• httpxはhttpx2になりました。 timeout=30.0のような素の値はそのまま動きます。クライアントに渡すhttpxオブジェクトはhttpx2由来でなければならず、httpxにパッチを当てるライブラリはhttpx2.alias_httpx()を呼ぶまでSDKのリクエストが見えなくなります。¹
• 削除されたもの：Text Completions、サンプリングパラメータ、output_format内のスキーマ辞書。 client.completions.create()、temperature、top_p、top_kはなくなり、スキーマ辞書はoutput_config={"format": {...}}へ移ります。¹
• Claude Code v2.1.239（2026年8月21日）で/claude-api upgradeが追加され、Pythonプロジェクトをanthropic 0.xから1.xへ移行できるようになりました。³ その出力は他の自動移行と同じように扱ってください。コミットする前に差分を読むことです。

anthropic 1.0にアップグレードすると何が壊れますか？

重みの大半を占めるのは6つの変更です。ガイドのクイックリファレンスをこの6つに凝縮し、より小さな削除項目はその後に続けます。¹ 最大の変更には明快な理由があります。SDKのHTTP層が、すでに活発にメンテナンスされていないhttpxから、PydanticチームがメンテナンスするAPI互換フォークのhttpx2へ移ったのです。クラスも挙動も同じで、セキュリティ修正が含まれています。¹

より小さな削除項目と1つの挙動変更も同時に入っており、それぞれに代替があります。¹

最後の行は静かに噛みついてきます。default_headers={"USER-AGENT": "my-app/1.0"}は、両方を送る代わりにSDK自身のUser-Agentを置き換えるようになりました。¹

手作業で移行するには？

順番に3ステップです。アップグレードし、型チェッカーに壊れた箇所を見つけさせ、カテゴリごとに修正します。

pip install --upgrade "anthropic>=1,<2"
pyright   # or mypy

最初にhttpxのインポートを直します。 もっとも派手に失敗するからです。SDK自身の再エクスポート（anthropic.Timeout、anthropic.DefaultHttpxClient、anthropic.DefaultAsyncHttpxClient、anthropic.DefaultAioHttpClient）はすでにhttpx2を指しており、そのまま動きます。エイリアスが必要なのは、httpxから直接構築するオブジェクトだけです。¹

# Before
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",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# After
import httpx2 as httpx  # or `import httpx2` and rename the references
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

アプリケーション内の他のコードがまだhttpxをインポートしていてSDKとクライアントや例外型を共有している場合、あるいはOpenTelemetryのHTTPXClientInstrumentor、Sentryのhttpxインテグレーション、respx、pytest-httpx、vcrpyを使っている場合は、エントリポイントの先頭でhttpx2.alias_httpx()を一度だけ呼びます。何かがhttpxをインポートするより前に実行しなければならず（そうでなければRuntimeErrorを送出します）、ガイドはこれをアプリケーション専用としています。ライブラリがユーザーの代わりに呼ぶことは決してあってはなりません。¹ pytest環境では、ガイドが挙げるもっとも侵襲性の低い選択肢は早期ロードのプラグインです。httpx2.alias_httpx()を呼ぶtests/_alias_httpx.pyモジュールをpyproject.tomlに登録し、respx、pytest-httpx、テストモジュールより先に読み込まれるようにします。¹

# tests/_alias_httpx.py
import httpx2

httpx2.alias_httpx()  # makes `import httpx` / `import httpcore` resolve to httpx2 / httpcore2

# pyproject.toml
[tool.pytest.ini_options]
addopts = "-p tests._alias_httpx"
pythonpath = ["."]

レスポンスとエラーのオブジェクトも今はhttpx2型です。 パッケージの変更は、渡すものだけでなくSDKが返すものにも及びます。APIStatusError.response、APIConnectionError.request、raw responseのresponse.http_response / .headers / .url、そしてカスタムhttp_clientのイベントフックが受け取るresponse=引数は、すべてhttpx2オブジェクトです。属性は以前とまったく同じなので、httpx2へ切り替える必要があるのは、httpx.Response / httpx.Request / httpx.Headersを名指しするisinstanceチェックと型アノテーションだけです。¹ isinstanceのケースはもう一度見ておく価値があります。ガイドはそうしたチェックを切り替えなければならないとしか述べていません。¹ それが重要な理由は、httpx2.alias_httpx()によってhttpxがhttpx2に解決されていない限り、古いパッケージに対するisinstance(err.response, httpx.Response)のようなチェックが例外を出さずにFalseを返し、ハンドラがその分岐を素通りしてしまうからです。

# Before
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx.Response = err.response
    print(response.status_code, response.headers.get("request-id"))


# After
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx2.Response = err.response
    print(response.status_code, response.headers.get("request-id"))

次はraw responseのリーダーです。 .with_raw_responseは以前、両方のクライアントでLegacyAPIResponseを返していました。今は.with_streaming_responseがすでに使っていたのと同じAPIResponse / AsyncAPIResponseクラスを返します。¹

続いて削除されたパラメータです。 現行のモデルはtemperature、top_p、top_kを使わないため、生成されたメソッドはもうこれらを受け付けません。変更以前のモデルならextra_body経由で引き続き有効で、SDKはこれをそのままリクエストJSONにマージします。¹

# Before
client.messages.create(..., model="claude-sonnet-4-6", temperature=0.2)

# After
client.messages.create(..., model="claude-sonnet-4-6", extra_body={"temperature": 0.2})

スキーマ辞書も同じ形で移動します。beta.messages.create()のoutput_format={"type": "json_schema", "schema": ...}はoutput_config={"format": {"type": "json_schema", "schema": ...}}になります。parse() / stream() / count_tokens() / tool_runner()ヘルパーはクラスを渡すoutput_format=Orderを維持しますが、そこにスキーマ辞書を渡すと今はTypeErrorを送出します。¹

最後にBedrockです。 AnthropicBedrockとAsyncAnthropicBedrockは以前、警告をログに出してus-east-1にフォールバックしていました。今は構築時にValueErrorを送出します。リージョンはaws_region=、次にAWS_REGION / AWS_DEFAULT_REGION、その次に指定したaws_profileのboto3セッションの順に解決されます。¹ また、SDKは以前は流していた未知のBedrockストリーミングイベントをスキップするようになりました。既知の唯一のケースはamazon-bedrock-invocationMetricsです。¹

Claude Codeで移行するには？

移行ガイド自身がこの近道を挙げています。プロジェクト内で/claude-api upgrade pythonを実行し、差分をレビューする、というものです。¹ このコマンドが入ったのは2026年8月21日リリースのClaude Code v2.1.239で、リリースノートの全文はこうです。「/claude-api upgradeを追加し、Pythonプロジェクトをanthropic 0.xから1.xへ移行できるようにした。また、スキルのPythonリファレンスを1.x向けに更新した（タイムアウトはhttpx.Timeoutではなくanthropic.Timeoutを使う）」。³

検証済みの情報はこの一文がすべてです。つまり、プロジェクトの0.x利用を1.xへ移行する/claude-apiスキルのコマンドだということです。編集内容をどう選んでいるかについては、これ以上のドキュメントを見つけられていないので、まさにそのとおりのもの、つまり差分を自分でレビューする自動移行として扱ってください。v2.1.239以降に更新し（claude update、またはインストールと更新のリファレンスを参照）、プロジェクトルートでセッションを開いて実行します。

/claude-api upgrade python

その後、差分をハンクごとに読み、型チェッカーを実行し、テストスイートを実行します。コントリビューターの移行PRに対して行うのと同じレビューです。ここでは型チェッカーのステップがいつも以上に重要です。1.0の破壊的変更のほぼすべてが型エラーであり、そのチェックは誰が編集したかを気にしないからです。¹ リリースノートが特に触れている1点、httpx.Timeoutではなくanthropic.Timeoutを使うという点はガイドとも一致しています。この再エクスポートはすでにhttpx2を指しているのです。¹³

Claude Codeが初めてですか？クイックスタートでは最初のセッションを、完全ガイドでは同梱スキルとスラッシュコマンドを扱っています。

FAQ

anthropic 1.0はまだPydantic v1をサポートしていますか？

はい。SDKは引き続きPydantic v1とv2をサポートしています。環境面での変更はPython 3.10の最低要件だけです。¹

アップグレード後、OpenTelemetryやrespxの設定がSDKのリクエストを見なくなるのはなぜですか？

これらのライブラリはhttpxにパッチを当てますが、SDKはもうhttpxを使っていません。何かがhttpxをインポートする前にhttpx2.alias_httpx()を呼んでください。以降、プロセス全体でimport httpxがhttpx2に解決されます。¹

古いモデルにはまだtemperatureを渡せますか？

はい。extra_body={"temperature": 0.2}を使えば、SDKがリクエストJSONにマージします。messages.batches.create()の場合は、リクエストのparams辞書に直接キーを入れてください。¹

tool_runnerのクライアントサイドのコンパクションは何に置き換わりましたか？

サーバーサイドのコンパクションです。tool_runner()にbetas=["compact-2026-01-12"]とcontext_management={"edits": [{"type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100_000}}]}を渡します。ガイドの例では、この組み合わせがcompaction_control={"enabled": True, "context_token_threshold": 100_000}を置き換えています。トリガーのしきい値は最低でも50,000トークンでなければなりません。¹

requirementsからhttpx_aiohttpを外す必要はありますか？

はい。anthropic[aiohttp]とhttp_client=DefaultAioHttpClient()は以前どおり動きますが、このextraはもうhttpx_aiohttpをインストールしません。SDK内部に同梱されるようになったためです。¹

重要なポイント

アプリケーション開発者向け： - "anthropic>=1,<2"にピン留めし、型チェッカーを実行し、この順でカテゴリごとに修正します。httpxのインポート、raw responseのawait、削除されたパラメータ、Bedrockのリージョン。¹ - プロセス内の何かがSDKとhttpxオブジェクトを共有していたりhttpxを計装していたりするなら、エントリポイントの最初の数行にhttpx2.alias_httpx()を置きます。¹

ライブラリメンテナー向け： - ライブラリ内でhttpx2.alias_httpx()を呼んではいけません。代わりにインポートをエイリアスします（import httpx2 as httpx）。¹ - anthropic.Transport / ProxiesTypesをやめてhttpx2.BaseTransport / httpx2.Proxyに移ります。¹

Claude Codeを使うチーム向け： - v2.1.239以降に更新し、プロジェクトルートから/claude-api upgrade pythonを実行します。差分をレビューし、コミット前に型チェッカーとテストを実行してください。¹³

参考文献