Python SDK を 2.0.0 に上げて動かなくなる3か所

個人開発の小さな Python スクリプトで、依存をまとめて更新しようとした日のことです。pip install -U anthropic を流す前に、念のため公式のリリースノートを開きました。

そこで目に入ったのが、10月21日公開の API バージョン 2026-10-21 と、それを既定で送る新しい SDK 群（Python は 2.0.0）が載っていたのです。

本物の API を叩く前に、通信を差し替えられるモックの上で、何が変わるのかを一つずつ確かめました。この記事は、その記録です。

先に結論です

最初にお伝えしたいのは、壊れやすい場所が3つに絞れる、ということです。

症状	原因	最初に見る場所
`temperature` を渡した呼び出しが TypeError になる	サンプリング引数が SDK から削除された	`messages.create` の呼び出し箇所
プロキシやゲートウェイ越しで認証が通らない	鍵が `X-Api-Key` ではなく `Authorization: Bearer` で送られる	ゲートウェイ側のヘッダ設定
起動時に ValueError、または警告が出る	クライアントが持てる認証が一つになった	コンストラクタと環境変数

上げる順番は、コードの修正を先に用意してから、SDK を上げることです。公式の移行ガイドも、アップグレードと修正を同時にリリースするよう案内しています。

1. temperature を渡した呼び出しは、送る前に止まります

公式の移行ガイドによると、2026-10-21 では temperature・top_p・top_k を送るとサーバーが 400 を返します。既定値のままでも同じです。

SDK 側はそれより手前で止まります。モックに差し替えたクライアントで試すと、通信が走る前に次の結果になりました。

# SDK 2.0.0 で temperature を渡した場合（モック越し）
c.messages.create(model="claude-sonnet-4-6", max_tokens=10,
                  temperature=0.2, messages=[{"role": "user", "content": "hi"}])
# TypeError: Messages.create() got an unexpected keyword argument 'temperature'

エラーの出どころが SDK なので、ログに API の 400 は残りません。「通信していないのに失敗している」ように見えて、最初は少し戸惑いました。

直し方は引数を消すだけですが、一つだけ判断が要ります。Claude 4.7 以降のモデルは、もともと既定値しか受け付けないので、挙動は変わりません。一方で Sonnet 4.6 のように別の値を受けるモデルでは、温度を下げて出力を安定させていた呼び出しが、その効果を失います。

代わりになる設定は、公式ガイドによれば用意されていません。固定したい呼び出しがあるなら、その呼び出しだけ旧 API バージョンに残す、という選び方になります。

2. 鍵のヘッダが変わるので、ゲートウェイ側を見ます

2つ目は、気づきにくい変更です。新しい SDK は、API キーを X-Api-Key ではなく Authorization: Bearer <鍵> で送ります。

モックに届いたヘッダを実際に覗いてみました。

authorization: Bearer sk-ant-test
anthropic-version: 2026-10-21

Claude API 自体はどちらのヘッダも受け付けます。ですから、直接つなぐ構成なら何も起きません。

困るのは、間にプロキシやゲートウェイを置いている構成です。X-Api-Key を見て鍵を差し替えたり、ログから伏せたりしている場合、今度は別のヘッダを見る必要があります。

ゲートウェイ側を直せない事情があるときは、公式ガイドの方法で SDK 側から鍵を元のヘッダへ戻せます。同じ関数をモックで動かし、x-api-key だけが届くことを確かめました。

import httpx2
from anthropic import Anthropic, DefaultHttpxClient
 
def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    # Authorization に載った鍵を、X-Api-Key へ付け替える
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request
 
client = Anthropic(api_key=api_key,
                   http_client=DefaultHttpxClient(auth=send_x_api_key))

付け替えた結果、モックに届いたのは x-api-key だけでした。この関数は再試行のたびに走るので、一度書けば抜けは出ません。

3. 認証が二つ重なると、止まるか警告が出ます

3つ目は、鍵とトークンを両方持っている環境で起きます。新しい SDK では、クライアントが持てる認証は一つだけです。

コンストラクタで二つ渡すと、その場で止まります。

Anthropic(api_key="a", auth_token="b")
# ValueError: Pass at most one of `api_key=`, `auth_token=`, `credentials=`,
#             `config=`, or `profile=`. Received `api_key=`, `auth_token=`.

環境変数の場合は止まらず、優先順位で一つが選ばれます。ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN を両方入れて試すと、警告が一度だけ出て、鍵のほうが使われました。

Anthropic: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both set. Using ANTHROPIC_API_KEY.

ここが、いちばん見落としやすいと感じました。止まってくれるなら気づけますが、静かに鍵が選ばれると、トークンのつもりで書いた設定が使われないまま動き続けるからです。

以前のように「ゲートウェイ向けにトークン、その先の API に鍵」と両方を送っていた方は、トークンを auth_token で渡し、鍵は default_headers に入れる形へ組み替えます。ゲートウェイ側で Authorization を外してから転送する、という約束も必要です。

上げる前の確認順

私は、いくつか試したうえで次の順番に落ち着きました。短く、手順だけにします。

呼び出し箇所を検索し、temperature top_p top_k を探します
固定したい呼び出しがあれば、その呼び出しだけ旧 API バージョンに残すと決めます
ゲートウェイや社内プロキシが X-Api-Key を見ていないか確認します
環境変数に ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN が同居していないか見ます
モックで一度通してから、本物の鍵で一回だけ呼びます

ほかにも、MessageParam(...) のように関数として呼ぶ書き方は、2.0.0 では型の合併になったため TypeError: Cannot instantiate typing.Union になります。辞書で書いていれば影響はありません。Bedrock で古いモデルを呼んでいる場合は、新しい API バージョンが使えないので、今の SDK のまま残す必要もあります。

線引きとして残したいこと

依存の更新は、本物の鍵を使う前に、通信を差し替えたモックで一度通すようにしています。壊れる場所は、リリースノートより先に、手元の出力が教えてくれます。

今回の3か所は、どれも公式の移行ガイドに書かれていました。それでも、自分の環境でどこに当たるのかは、動かしてみるまで分からなかったのだと、いま思えば感じます。

まずはお手元のスクリプトで、temperature の検索から始めてみてください。

SDK 2.0.0 への更新は、依存の更新日を一つ決めて、モックの確認とあわせて回しております。

Python SDK を 2.0.0 に上げて動かなくなる3か所 — モック越しに再現して決めた確認の順番