動画で読む
@anthropic-ai/sdk(Anthropic の TypeScript SDK)は 2026-10-21 に 1.0.0 と 1.1.0、10-23 に 1.2.0 と 1.3.0 が出た。3 日で 4 リリース。1.3.0 のリリースノートには、Chores(雑務)の欄にこういう行が混ざっている。
- client: stop sending query params hardcoded in endpoint paths
- internal: read the beta route qualifier instead of the beta=true query
雑務扱いだけど、beta 系のエンドポイントが送る URL が変わるなら話は別だ。Anthropic API の手前に自前のゲートウェイを置いて、?beta=true の有無でログを分けたりルーティングしたりしている構成だと、上げた日から集計がずれる。
そこで 1.1.0 / 1.2.0 / 1.3.0 を同じスクリプトでローカルのモックサーバに向けて、届いたリクエストを並べた。API キーは要らない。手元の Node は v20.20.2 で、このサイトのフロントが前提にしている 24 ではない。SDK の送信内容には効かないと思うけど、そこは確かめていない。
先に書いておくと、URL の件は予想どおりだった。予想していなかったのは 1.2.0 の tool runner の方で、こっちのほうがプロキシ側への影響は大きい。
比べ方: 届いたものを 1 行 JSON で吐くだけのモック
Node の http で 127.0.0.1:4010 にサーバを立て、method / path / query / anthropic-* と x-stainless-* のヘッダ / body の要約を 1 リクエスト 1 行で出すようにした。/v1/messages には普通の message を返す。tools 付きで、まだ tool_result が無いリクエストにだけ tool_use を返す。
SDK は版ごとに別ディレクトリへ入れた。
$ (cd v1.1.0 && npm i @anthropic-ai/sdk@1.1.0) # 1.2.0 / 1.3.0 も同じ
1.1.0 2789 files 22164 KB
1.2.0 2843 files 22796 KB
1.3.0 2924 files 23328 KB
クライアントは baseURL: 'http://127.0.0.1:4010'、maxRetries: 0。どの版から来たか分かるように defaultHeaders で x-run-tag を足している。
1.3.0 では beta 系の呼び出しから ?beta=true が消える
8 通りの呼び出しで、モックが受けた path + query と anthropic-beta ヘッダを並べた。1.1.0 と 1.2.0 は 8 行とも同じだったので 1 列にまとめる。
| 呼び出し | 1.1.0 / 1.2.0 | 1.3.0 |
|---|---|---|
messages.create | /v1/messages | /v1/messages |
beta.messages.create(betas: context-management-2025-06-27) | /v1/messages?beta=true + beta ヘッダ | /v1/messages + beta ヘッダ |
beta.messages.countTokens | /v1/messages/count_tokens?beta=true + token-counting-2024-11-01 | /v1/messages/count_tokens + 同じヘッダ |
beta.models.list | /v1/models?beta=true | /v1/models |
models.list | /v1/models | /v1/models |
beta.messages.create(betas なし、query: { trace: 'abc' }) | ?beta=true&trace=abc | ?trace=abc |
defaultQuery: { beta: 'true' } で beta.messages.create | ?beta=true | ?beta=true |
defaultQuery: { beta: 'true' } で messages.create | ?beta=true | ?beta=true |
ヘッダまで含めて 1.3.0 の生ログを見ると、区別のつかない組が出てくる。
{"path":"/v1/messages","query":"","headers":{"anthropic-version":"2026-10-21"}}
{"path":"/v1/messages","query":"","headers":{"anthropic-version":"2026-10-21","anthropic-beta":"context-management-2025-06-27"}}
{"path":"/v1/messages/count_tokens","query":"","headers":{"anthropic-version":"2026-10-21","anthropic-beta":"token-counting-2024-11-01"}}
{"path":"/v1/models","query":"","headers":{"anthropic-version":"2026-10-21"}}
{"path":"/v1/models","query":"","headers":{"anthropic-version":"2026-10-21"}}
{"path":"/v1/messages","query":"?trace=abc","headers":{"anthropic-version":"2026-10-21"}}
4 行目が beta.models.list、5 行目が models.list で、バージョン系のヘッダを除けば完全に同じだった。1 行目(messages.create)と 6 行目(betas を渡さない beta.messages.create)も、自分で足した trace を除けば同じになる。つまり 1.3.0 からは、betas を指定していない beta 呼び出しはネットワーク上で普通の呼び出しと見分けがつかない。プロキシで anthropic-beta ヘッダを見て振り分けるやり方に変えても、この 2 組は拾えない。
原因は path から query を外して __qualifiers に移したこと
dist を grep すると、変わり方がはっきりしている。
$ grep -rl --include='*.js' 'beta=true' ... | wc -l ; grep -rho ... ; grep -rho '__qualifiers' ...
1.1.0 files=70 occurrences=245 __qualifiers=0
1.2.0 files=72 occurrences=247 __qualifiers=0
1.3.0 files=0 occurrences=0 __qualifiers=262
'beta=true' を含む .js が 72 ファイルから 0 になり、入れ替わりに __qualifiers が 262 か所現れた。resources/beta/messages/messages.js の差分はこうだった。
< const request = this._client.post('/v1/messages?beta=true', {
> const request = this._client.post('/v1/messages', {
> __qualifiers: { beta: 'true' },
< const request = this._client.post('/v1/messages/count_tokens?beta=true', {
> const request = this._client.post('/v1/messages/count_tokens', {
> __qualifiers: { beta: 'true' },
1.1.0 までは、path に埋めた ?beta=true が buildURL の Object.fromEntries(url.searchParams) で拾われて、そのまま URL に残っていた。1.3.0 は path を素の /v1/messages にして、「これは beta 呼び出しだ」という印を __qualifiers というリクエストオプションに持たせている。__qualifiers を読んでいるのは SDK の中だけで、grep した範囲では lib/middleware.js の betaRefusalFallbackMiddleware が ctx.options.__qualifiers?.['beta'] !== 'true' で判定していた。1.1.0 の同じミドルウェアは path を ? で split して query を見ていたので、SDK 内部の判定を URL から切り離したのが目的なんだと思う。
API 側が ?beta=true を必要としていないことは、この変更が通っている以上たぶん確かだ。ただ、本物の API に 1.3.0 で投げて挙動が変わらないかは、キーを使っていないので確かめていない。
プロキシ側で ?beta=true に頼っているなら、直し方は 3 つある
試した範囲で、1.3.0 でも ?beta=true を送らせる方法は 2 つあった。
- 呼び出しごとに
{ query: { beta: 'true' } }を渡す。beta.messages.createもbeta.models.listも?beta=true付きで届いた defaultQuery: { beta: 'true' }を持つクライアントを作る。ただし表の最終行のとおり、そのクライアントではmessages.createにも付く。beta 専用のクライアントを分けるなら使える
もう 1 つはプロキシ側を変える方で、?beta=true で分けていた集計を「anthropic-beta ヘッダの有無」に寄せる。上で見たとおり betas なしの beta 呼び出しは拾えなくなるけど、beta 機能を本当に使っている呼び出しはヘッダが付くので、課金や機能別の集計ならこっちで足りる気がする。
私が選ぶなら 3 つ目にする。SDK の内部実装に合わせて query を足し直すのは、次にまた変わったときに同じことになるからだ。とはいえ「beta 名前空間から呼んだかどうか」そのものを数えたいなら、per-call の query しか手が無い。
1.2.0 から tool runner は 2 ターン目に差分しか送らない
ここからが予定外だった。リリースノートの 1.2.0 には「tool runner のループ本体で setMessagesParams() / pushMessages() を呼んだときの挙動を元に戻した」という修正がある。これを確かめるつもりで 4 つのシナリオを回した。
- A: 何もしない
- B: 1 ターン目の後に
runner.pushMessages({ role: 'user', content: 'pushed-in-loop' }) - C: 1 ターン目の後に
setMessagesParamsで messages を 1 件足す - D: runner を作った直後に、渡した元の
messages配列へ push する
モックに届いた messages を並べるとこうなった(tool_use / tool_result はブロックの type)。
{"tag":"1.1.0/A","q":"?beta=true","messages":["user:weather?"]}
{"tag":"1.1.0/A","q":"?beta=true","messages":["user:weather?","assistant:tool_use","user:tool_result"]}
{"tag":"1.1.0/B","q":"?beta=true","messages":["user:weather?"]}
{"tag":"1.1.0/B","q":"?beta=true","messages":["user:weather?","user:pushed-in-loop"]}
{"tag":"1.1.0/B","q":"?beta=true","messages":["user:weather?","user:pushed-in-loop","assistant:tool_use","user:tool_result"]}
{"tag":"1.2.0/A","q":"?beta=true","messages":["user:weather?"]}
{"tag":"1.2.0/A","q":"?beta=true","messages":["user:tool_result"]}
{"tag":"1.2.0/B","q":"?beta=true","messages":["user:weather?"]}
{"tag":"1.2.0/B","q":"?beta=true","messages":["user:weather?","user:pushed-in-loop"]}
{"tag":"1.2.0/B","q":"?beta=true","messages":["user:tool_result"]}
1.2.0 の A は、2 リクエスト目に tool_result 1 件しか送っていない。最初は履歴を落とすバグかと思った。body のキーを出し直すと、そうではなかった。
{"tag":"1.2.0/A","beta":"message-threads-2026-08-12","helper":"BetaToolRunner, message-thread","bodyKeys":["model=\"claude-mock\"","max_tokens=16","thread={\"type\":\"create\"}","stream=false"],"messages":["user:weather?"]}
{"tag":"1.2.0/A","beta":"message-threads-2026-08-12","helper":"BetaToolRunner, message-thread","bodyKeys":["model=\"claude-mock\"","max_tokens=16","thread={\"type\":\"continue\",\"previous_message_id\":\"msg_18\"}","stream=false"],"messages":["user:tool_result"]}
1.2.0 の tool runner は、同じ版で入った message threads(会話の履歴をサーバ側に持たせる beta 機能。ヘッダは message-threads-2026-08-12)を 既定で 使う。1 ターン目で thread: { type: "create" }、2 ターン目からは previous_message_id を付けて新しいメッセージだけを送る。1.1.0 には lib/internal/threads ディレクトリ自体が無い。型定義のコメントにもそう書いてある。
* The loop runs over a message thread by default, sending only new messages each turn. `false` sends the full
* history every turn.
*/
thread?: false;
リリースノートの Features には「add support for message threads」としか無く、tool runner の既定が変わったことは読み取れなかった。
プロキシで会話ログを丸ごと保存している人には、これは URL の件より効く。1.2.0 以降、tool runner 経由の 2 ターン目以降はリクエスト単体を見ても文脈が無い。previous_message_id で前のレスポンスと突き合わせないと会話が復元できなくなる。モックは thread を無視して普通に返しただけなのに SDK は何事もなく 2 ターンで終わったので、エラーで気づくこともない。
toolRunner({ ..., thread: false }) を渡すと 1.1.0 と同じ全履歴送信に戻った。1.2.0 でも 1.3.0 でも同じだった。
{"tag":"1.3.0/thread-false","q":"","beta":null,"bodyKeys":["model=\"claude-mock\"","max_tokens=16","stream=false"],"messages":["user:weather?"]}
{"tag":"1.3.0/thread-false","q":"","beta":null,"bodyKeys":["model=\"claude-mock\"","max_tokens=16","stream=false"],"messages":["user:weather?","assistant:tool_use","user:tool_result"]}
本物の API で thread が作れないときは、unsupportedRequestBehavior: 'continue_unthreaded' で全履歴送信に落ちるコードが ThreadState.js にある。ただし落ちるのはサーバがエラーを返したときで、モックのように thread を黙って無視する中継(自前のプロキシや、別のバックエンドに転送するゲートウェイ)だと、その分岐には入らない。中継先が previous_message_id を知らないまま差分だけ受け取ることになる。ここは実物の中継で確かめたわけではなく、コードとモックの結果からの推測だ。
pushMessages の「元に戻した」修正は、1.1.0 との差としては見えなかった
肝心の修正の方は、B と C で 1.1.0 と 1.2.0 の振る舞いが揃っていた。どちらもループ本体で messages を変えると、1 ターン目の tool_use への返事を送らずに、変えた messages でもう一度リクエストする(B の 2 行目)。その後に tool を実行して返す。D(元の配列を後から書き換える)は 3 版とも書き換えが送信に反映されず、渡した時点のコピーが使われた。
「元に戻した」なので、たぶん 1.2.0 の開発中に thread 化で一度壊れて、リリース前に直った話なんだと思う。1.1.0 から上げる人には差として出てこない。1.0.0 は入れていないので、1.0.0 との比較はしていない。
ついでに 1.3.0 の「long-request のエラーメッセージをドキュメントにリンク」も見た。max_tokens: 64000 を非ストリーミングで投げると、どちらの版も送信前に AnthropicError を投げる。変わったのはリンク先だけだった。
1.2.0 messages AnthropicError: Streaming is required for operations that may take longer than 10 minutes. See https://github.com/anthropics/anthropic-sdk-typescript#long-requests for more details
1.3.0 messages AnthropicError: Streaming is required for operations that may take longer than 10 minutes. See https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#long-requests for more details
上げる前に見るのは query とヘッダと body の thread
このモックの結果から、1.1.0 以前から上げる人が手元で確かめることは 3 つに絞れる。
- プロキシやログ集計が
?beta=trueを見ているか。見ているなら 1.3.0 で全部空になる。ヘッダで分けるか、per-call のqueryで足し直す - betas を渡さない
beta.*呼び出しを区別したいか。1.3.0 ではネットワーク上の手がかりが無いので、区別したいなら query を足すしかない - tool runner を使っていて、中継で会話を保存・検査しているか。1.2.0 からは
thread: falseを付けないと 2 ターン目以降が差分になる
Python 版の SDK を 1.6 から 1.8 に上げたときは、同じようにモックで比べて「届くボディは同じ」で終わった。TypeScript 版の 1.1 → 1.3 は、メジャーを跨がないマイナー 2 つ分で URL も body も変わる。私が一番引っかかったのは、そのどちらも Features ではなく Chores と、別機能の 1 行の中に入っていたことだった。