AI

anthropic SDK 2.0 で変わったのはキーの送り方と MessageParam

Python 版 anthropic SDK の 1.17.0 と 2.0.0 をモックと pyright で比較。ボディは同一だが API キーは Bearer ヘッダに移り、MessageParam(...) は実行時 TypeError、認証情報の併用は ValueError。上げる前に grep する 6 項目を表にした。

SoSoraEndo2026年10月22日 09:1227 min2,268 字

動画で読む

anthropic-sdk-python の v2.0.0 が 2026-10-21 に出た。メジャー版なのに、リリースノートの BREAKING CHANGES はこの 1 行しかない。

### ⚠ BREAKING CHANGES

* **api:** add support for new API version 2026-10-21

「API バージョンが上がった」だけなら、自分のコードで変わるのは anthropic-version ヘッダの値くらいのはずだ。本当にそれだけなのか。型や認証の初期化まで壊れるのか。そこを API キー無しで確かめたかった。

やり方は 1.6 → 1.8 のときに組んだ方法とほぼ同じで、venv を 2 つ作り、リクエストを記録するだけのローカルのモックサーバに base_url を向けて、同じコードを両方の版で動かす。型は pyright 1.1.414 で見た。

まず差分の大きさ。コミット 6 本、ライセンスも変わっている

$ ./v1.17.0/bin/pip show anthropic | grep -E '^(Name|Version|License)'
Name: anthropic
Version: 1.17.0
License: MIT
$ ./v2.0.0/bin/pip show anthropic | grep -E '^(Name|Version|License)'
Name: anthropic
Version: 2.0.0
License: Apache-2.0

依存(httpx2 / pydantic / jiter ほか)は両版で同じだった。compare v1.17.0...v2.0.0 を API で取るとコミットは 6 本、変更ファイルは 83 本。目に付いたのはこのあたり。

modified  +197/-4    LICENSE
added     +11/-0     LICENSE-MIT
modified  +3/-3      pyproject.toml
modified  +156/-164  src/anthropic/_client.py
modified  +1/-1      src/anthropic/_constants.py
modified  +6/-49     src/anthropic/types/message_param.py
added     +14/-0     src/anthropic/types/system_message_param.py

_constants.py の 1 行は予想どおり ANTHROPIC_API_VERSION = "2023-06-01" が "2026-10-21" になる変更だった。気になったのは _client.py が 156 行も動いていること。API バージョンを上げるだけで、クライアント本体がこんなに変わるはずがない。

追加された LICENSE-MIT の 1 行目はこうなっている。

This repository changed its license from the MIT License to the Apache License, Version 2.0 (see LICENSE) in version 2.0.0. The MIT License below still applies to every version published under it, and to third-party contributions merged into this repository before the change.

1.x 系を使い続ける分には MIT のまま。コードは何も変わらないけど、依存ライセンスを台帳で管理しているなら 2.0.0 から書き換えが要る。

送られるボディは 1 バイトも変わらない。ヘッダは 5 本変わる

system= と user / assistant の 3 ターンを持つ、ごく普通の messages.create を両版から投げた。モックは受けたリクエストを JSON Lines で書き出すだけの http.server で、レスポンスは Messages API の形をした固定値を返す。

# body(1.17.0 / 2.0.0 の順)
{"max_tokens": 64, "messages": [{"role": "user", "content": "こんにちは"}, {"role": "assistant", "content": "やあ"}, {"role": "user", "content": "1+1は?"}], "model": "claude-sonnet-5-5", "system": "あなたは短く答える。"}
{"max_tokens": 64, "messages": [{"role": "user", "content": "こんにちは"}, {"role": "assistant", "content": "やあ"}, {"role": "user", "content": "1+1は?"}], "model": "claude-sonnet-5-5", "system": "あなたは短く答える。"}
# headers diff
anthropic-version                2023-06-01                     -> 2026-10-21
authorization                    None                           -> Bearer sk-ant-dummy
user-agent                       Anthropic/Python 1.17.0        -> Anthropic/Python 2.0.0
x-api-key                        sk-ant-dummy                   -> None
x-stainless-package-version      1.17.0                         -> 2.0.0

ボディは同一。user-agent と x-stainless-package-version はバージョン番号なので当然として、残りの 3 行のうち 2 行は想定していなかった。

API キーが x-api-key ヘッダから Authorization: Bearer に引っ越している。_client.py の diff を見ると、変わったのは _api_key_auth の 1 行だ。

-        return {"X-Api-Key": api_key}
+        return {"Authorization": f"Bearer {api_key}"}

これがリリースノートに 1 文字も出てこないのは、さすがに不親切だと思う。公式の移行ガイドには「API keys are sent as Authorization: Bearer」という節がちゃんとあって、Claude API はどちらのヘッダでもキーを受け付けるから、API に直接つないでいるプログラムは何も変えなくていい、と書いてある。

逆に言うと、間にプロキシやゲートウェイを挟んでいて、そこが x-api-key を読んで認可やレート制限をしているなら、2.0 に上げた瞬間にキーが見えなくなる。このサイトの Bot API も request.headers['X-API-Key'] でキーを引く作り(backend/app/controllers/api/v1/bot/base_controller.rb 29 行目)で、こういう自前の中継を書いたことがある人ほど踏みやすい。

移行ガイドには、httpx2 の auth 関数でヘッダを X-Api-Key に戻す方法が載っている。それに沿って書いたのがこれ。

import httpx2, anthropic

def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    auth = request.headers.pop("Authorization", "")
    if auth.startswith("Bearer sk-ant-"):
        request.headers["X-Api-Key"] = auth.removeprefix("Bearer ")
    return request

c = anthropic.Anthropic(api_key="sk-ant-dummy", base_url="http://127.0.0.1:8765", max_retries=0,
                        http_client=anthropic.DefaultHttpxClient(auth=send_x_api_key))

モックが受けたヘッダを見ると、2.0.0 でも x-api-key で届き、Authorization は消えている。

{"ua": "Anthropic/Python 2.0.0", "x-api-key": "sk-ant-dummy", "authorization": null}

Bearer sk-ant- で始まるものだけ移しているのは、auth_token= で渡したトークンまで X-Api-Key に化けさせないため。

型で壊れるのは「role を変数で持つ書き方」と「MessageParam(...) の呼び出し」

MessageParam は 1.17.0 だと 1 つの TypedDict で、2.0.0 では UserMessageParam / AssistantMessageParam / SystemMessageParam の Union になった。

# 2.0.0 types/message_param.py
MessageParam: TypeAlias = Union[UserMessageParam, AssistantMessageParam, SystemMessageParam]

最初は role="system" を messages に入れられるようになったのが本体の変更だと思っていた。ところが 1.17.0 の message_param.py を開くと、こうなっている。

# 1.17.0 types/message_param.py
    role: Required[Literal["user", "assistant", "system"]]

system role は 1.17.0 の時点ですでに型に入っていた。実際に messages=[{"role": "system", ...}, {"role": "user", ...}] を両版から送ると、どちらもそのままモックに届く。2.0 の変更は「system を足した」ではなく「role ごとに型を分けた」方だ。

分けたことで何が起きるか。素朴に書きがちな関数を 3 つ用意して pyright にかけた。

Role = Literal["user", "assistant"]

def make(role: Role, text: str) -> MessageParam:
    return {"role": role, "content": text}

def make_ctor(text: str) -> MessageParam:
    return MessageParam(role="user", content=text)

def tool_ids(m: MessageParam) -> List[str]:
    c = m["content"]
    if isinstance(c, str):
        return []
    return [b["id"] for b in c if isinstance(b, dict) and b["type"] == "tool_use"]
$ v1.17.0/bin/pyright typed2.py
0 errors, 0 warnings, 0 informations
$ v1.17.0/bin/python typed2.py
{'role': 'user', 'content': 'a'} {'role': 'user', 'content': 'b'} []

$ v2.0.0/bin/pyright typed2.py
  typed2.py:7:12 - error: Type "dict[str, str]" is not assignable to return type "MessageParam"
      "dict[str, str]" is not assignable to "UserMessageParam"
      "dict[str, str]" is not assignable to "AssistantMessageParam"
      "dict[str, str]" is not assignable to "SystemMessageParam" (reportReturnType)
  typed2.py:10:12 - error: Object of type "UnionType" is not callable (reportCallIssue)
2 errors, 0 warnings, 0 informations
$ v2.0.0/bin/python typed2.py
    raise TypeError(f"Cannot instantiate {self!r}")
TypeError: Cannot instantiate typing.Union

make は 1.17.0 では通っていた。role が "user" | "assistant" の変数だと、2.0.0 ではどの型にも当てはまらない、という扱いになる。pyright は Literal の Union を TypedDict の Union に分配してくれない。ただし実行は普通に通るので、型チェックを CI に入れていない人には見えない。

厄介なのは make_ctor の方。MessageParam(role=..., content=...) は 1.17.0 だと TypedDict の呼び出しで、ただの dict が返っていた。2.0.0 では Union を呼ぶことになり、実行時に TypeError で落ちる。型チェッカを通していなくても、上げた瞬間に本番で落ちるのはこっちだ。

tool_ids のように content を読むだけの関数は、両版とも 0 エラーだった。history.append({"role": role, "content": text}) で role: str を受けていたコードは、1.17.0 でも 2.0.0 でもエラー 1 件で、件数は変わらない(メッセージの文面だけ変わる)。

移行ガイドの Python 節にも、MessageParam を呼ぶと TypeError になること、make 型の関数は if role == "user": で role ごとに dict を作り分ける書き換え例が載っている。ここはガイドどおりで、実測とも一致した。

認証情報を 2 つ渡すと、引数なら ValueError、環境変数ならログ 1 行

api_key= と auth_token= を両方コンストラクタに渡すケースと、ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN を両方 env に置くケースを試した。

== 1.17.0 both-args
OK ok
== 1.17.0 both-env
OK ok
== 2.0.0 both-args
EXC ValueError Pass at most one of `api_key=`, `auth_token=`, `credentials=`, `config=`, or `profile=`. Received `api_key=`, `auth_token=`.
== 2.0.0 both-env
Anthropic: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both set. Using ANTHROPIC_API_KEY.
OK ok

モックが受けたヘッダを並べると、1.17.0 は 2 つとも送っていた。

Anthropic/Python 1.17.0 x-api-key= sk-ant-dummy authorization= Bearer tok-dummy
Anthropic/Python 1.17.0 x-api-key= sk-ant-env   authorization= Bearer tok-env
Anthropic/Python 2.0.0  x-api-key= None         authorization= Bearer sk-ant-env

API キーが Authorization に引っ越した以上、トークンと同じヘッダを取り合うので、片方しか持てなくなるのは筋が通っている。気を付けたいのは 2 点ある。

1 つは例外の型。1.17.0 にも「2 つ渡すな」というチェックはあったが、対象は credentials= / config= / profile= の 3 つだけで、投げていたのは TypeError だった。

$ grep -n "Pass at most one" v1.17.0/.../anthropic/_client.py
268:                raise TypeError("Pass at most one of `credentials=`, `config=`, or `profile=`.")

except TypeError で拾っていたコードがあれば、2.0.0 ではすり抜ける。

もう 1 つは env の方。あの 1 行がどこから出ているかを grep した。

anthropic/lib/credentials/_auth.py:21:def _warn_once(key: str, message: str, *args: object) -> None:
anthropic/lib/credentials/_auth.py:22:    """Emit a log warning at most once per `key` per process."""
anthropic/lib/credentials/_auth.py:27:    log.warning(message, *args)
anthropic/lib/credentials/_auth.py:52:        "Anthropic: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both set. Using ANTHROPIC_API_KEY.",

warnings.warn ではなく logging だ。実際 python -W error creds.py env で走らせても例外にはならず、同じ 1 行を出して OK ok で終わった。同じプロセスでクライアントを 3 回作っても、警告は最初の 1 回だけだった。

Anthropic: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both set. Using ANTHROPIC_API_KEY.
client 0
client 1
client 2

ログ設定次第では誰の目にも触れないまま、ANTHROPIC_AUTH_TOKEN は黙って捨てられる。トークンをゲートウェイ用に使っていた構成だと、これは静かに壊れる種類の変更だと思う。

1.17.0 の時点ですでに無かったもの

移行ガイドの breaking changes で一番大きいのは、2026-10-21 では temperature / top_p / top_k を送ると 400 になる、という項目だ。これも 2.0 で効くのかと思って temperature=0.2 を渡したら、両版とも同じ結果だった。

== 1.17.0
temperature: EXC TypeError Messages.create() got an unexpected keyword argument 'temperature'
== 2.0.0
temperature: EXC TypeError Messages.create() got an unexpected keyword argument 'temperature'

inspect.signature(Messages.create) にも 3 つとも無い。Python SDK からは 1.17.0 より前に消えていて、2.0 で新しく壊れるものではなかった。いつの版で消えたかは今回追っていない。client.completions(旧 Text Completions)も両版とも hasattr が False だった。

で、2.0 に上げて変わるのはヘッダだけなのか

答えは「ボディは変わらない。ヘッダは 2 本、意味のある変わり方をする。型と初期化は書き方次第で壊れる」だった。自分のコードに当てはめるなら、次を grep すれば 30 分かからず判定できる。

grep するもの2.0.0 で起きること見え方
MessageParam(実行時 TypeError: Cannot instantiate typing.Union上げた瞬間に落ちる
x-api-key / X-Api-Key(中継・ミドルウェア側)キーが Authorization: Bearer で届く中継側でキーが見えない
auth_token= と api_key= の併用ValueError初期化で落ちる
except TypeError(クライアント生成まわり)ValueError に変わってすり抜ける例外ハンドリングが効かない
ANTHROPIC_AUTH_TOKENANTHROPIC_API_KEY と併存なら無視、ログ 1 行静かに壊れる
role を変数で持つ dictpyright エラー、実行は通るCI の型チェックだけ

試していないことも残っている。API キーを使っていないので、anthropic-version: 2026-10-21 に変わったことでサーバ側の挙動がどう変わるか(assistant メッセージ内の document ブロックや、user メッセージの citations が 400 になる、と移行ガイドにある)は見ていない。messages 配列の system role を、古い 2023-06-01 の API が受けるのかどうかも確かめていない。SDK はどちらの版でも黙って送るので、そこはサーバに聞くしかない。

mypy は入れていないので、make 型のエラーが mypy でも同じように出るかは分からない。Union への分配の扱いは型チェッカによって違うことがあるので、pyright で通っても mypy で落ちる、あるいはその逆はありうる。

Tags

参考文献

  1. Release v2.0.0 · anthropics/anthropic-sdk-python(GitHub)
  2. Compare v1.17.0...v2.0.0 · anthropics/anthropic-sdk-python(GitHub)
  3. Migrating to API version 2026-10-21(Claude Docs)

Reaction

Share

X (Twitter)