動画で読む
anthropic-sdk-python の v1.14.0 が 2026-10-14 に出た。Bug Fixes にストリーミングの行が 2 つある。
* **streaming:** pass unknown event types through the message stream helpers
* **streaming:** stop raising "Unexpected event order" for an event before message_start
公式のストリーミング doc にある client.messages.stream() で受けて for event in stream: の中で event.type を分岐しているコードは、上げた瞬間にループに入ってくるものが変わる可能性がある。ただ、リリースノートの 1 行だけでは「どんな SSE が来たときに」変わるのかが分からない。同じリリースの Features に OpenTelemetry tracing の追加もあって、こっちは既定で何か出すのかが気になった。
そこで venv を 2 つ作って 1.13.0 と 1.14.0 を入れ、Python の http.server で /v1/messages を真似る SSE モックを書いて、同じストリームを両方に流した。API キーは使っていない(base_url をモックに向けている)。
$ ./v1.13.0/bin/pip show anthropic | head -3
Name: anthropic
Version: 1.13.0
$ ./v1.14.0/bin/pip show anthropic | head -3
Name: anthropic
Version: 1.14.0
$ python3 --version
Python 3.11.3
event 名が未知の SSE は、1.14 でも helper まで届かない
最初に用意したのは素直なケースで、message_start の直後に event: foo_delta / data: {"type": "foo_delta", ...} を 1 個挟んだストリーム。「未知のイベント型を通す」なら、1.14 の helper では foo_delta が見えるはずだと思っていた。
結果は両バージョンとも同じで、foo_delta はどこにも出てこない。
{"v": "1.13.0", "mode": "helper", "scenario": "unknown_named", "events": ["message_start", "content_block_start", "content_block_delta", "text", ...], "final": "Hello world"}
{"v": "1.14.0", "mode": "helper", "scenario": "unknown_named", "events": ["message_start", "content_block_start", "content_block_delta", "text", ...], "final": "Hello world"}
{"v": "1.14.0", "mode": "raw", "scenario": "unknown_named", "events": ["message_start", "content_block_start", "content_block_delta", ...], "final": "-"}
helper だけでなく、stream=True で受ける raw ストリームにも出ていない。原因は helper より手前、リポジトリの src/anthropic/_streaming.py にあった。SSE の event: 行の名前を、既知の名前の列挙と照合してから yield している。
for sse in iterator:
if sse.event == "completion":
yield process_data(data=sse.json(), cast_to=cast_to, response=response)
if (
sse.event == "message_start"
or sse.event == "message_delta"
...(約 60 個の event 名を列挙)
or sse.event == "workflow_run.phase_ended"
):
data = sse.json()
列挙に無い名前は、ping と error 以外は黙って捨てられる。event: 行を省いて data: だけ送ったケースも同じく消えた。同じファイルの SSE デコーダは self._event = event or None で、event: 行が無いと名前は None のまま。SSE 仕様の既定の message 扱いにはならないので、列挙のどれにも当たらない。つまり 1.14 の修正が効くのは、既知の event 名に、知らない type の data が載ってきたとき に限られる。サーバが新しいイベントを足すとき、event: 行と data.type を同じ新しい名前にするなら、1.14 に上げても見えるようにはならない。
既知の event 名に未知の type が載ると、1.14 の helper だけ挙動が変わる
event: message と event: content_block_delta の 2 通りで、data を {"type": "foo_delta", "index": 0, "payload": "x"} にして流した。こっちは差が出た。
| シナリオ | 受け方 | 1.13.0 | 1.14.0 |
|---|---|---|---|
| 正常系 | helper / raw | 同じ列、final = Hello world | 同じ |
event: foo_delta | helper / raw | foo_delta 出ない | 出ない |
event: 行なし | helper / raw | 出ない | 出ない |
event: message + type: foo_delta | raw | foo_delta が出る | 出る |
| 同上 | helper | 出ない | 出る |
event: content_block_delta + type: foo_delta | raw | 出る | 出る |
| 同上 | helper | 出ない | 出る |
raw ストリームは 1.13 の時点で foo_delta を素通ししていた。1.13 の helper はそれを build_events の中で捨てていて、1.14 で拾うようになった。diff はこれだけ。
else:
- # we only want exhaustive checking for linters, not at runtime
- if TYPE_CHECKING: # type: ignore[unreachable]
- assert_never(event)
+ events_to_fire.append(cast("ParsedMessageStreamEvent[ResponseFormatT]", event))
だから「helper と raw で見えるイベントが揃った」と言うのが正確だと思う。get_final_message() の中身はどのケースでも Hello world で、最終メッセージの組み立てには影響していない。
気になったのは、届いた foo_delta が何のクラスで来るかだった。
1.13.0 raw foo_delta RawMessageStartEvent isinstance(RawMessageStartEvent)= True message= None
1.14.0 raw foo_delta RawMessageStartEvent isinstance(RawMessageStartEvent)= True message= None
1.14.0 foo_delta anthropic.types.raw_message_start_event.RawMessageStartEvent x
type は foo_delta なのに、インスタンスは RawMessageStartEvent だ。union のどれにも合わないので、検証なしの構築で先頭の型に落ちているように見える。message 属性は None で、知らないフィールドの payload はそのまま残っている。
ここは原典に書いていない落とし穴だと思う。isinstance(event, RawMessageStartEvent) で分岐して event.message.id を読むコードは、1.14 の helper に未知の type が来た時点で AttributeError になる。event.type == "message_start" で分岐していれば、未知の type は else に落ちるだけで済む。1.14 に上げる前に直すならここで、isinstance 分岐を type の文字列比較に寄せておく。
message_start より前のイベントは、1.13 だと helper ごと止まっていた
2 つ目の修正は再現がもっと分かりやすかった。message_start の前に content_block_stop を 1 個置いたストリームと、event: message で foo_delta を 1 個置いたストリーム。
{"v": "1.13.0", "mode": "helper", "scenario": "before_start_known", "events": [], "error": "RuntimeError: Unexpected event order, got content_block_stop before \"message_start\""}
{"v": "1.14.0", "mode": "helper", "scenario": "before_start_known", "events": ["content_block_stop", "message_start", "content_block_start", ...], "final": "Hello world"}
{"v": "1.13.0", "mode": "helper", "scenario": "before_start_unknown_msg", "events": [], "error": "RuntimeError: Unexpected event order, got foo_delta before \"message_start\""}
{"v": "1.14.0", "mode": "helper", "scenario": "before_start_unknown_msg", "events": ["foo_delta", "message_start", ...], "final": "Hello world"}
1.13 の helper は 1 イベント目で RuntimeError を投げ、ループには何も入らない。1.14 はそのイベントを素通しして、message_start から普通に組み立てを始める。raw ストリームはどちらのバージョンでも例外を出していない。
1.14 の __stream__ の変更を見ると、素通しの条件は「スナップショットがまだ無く、かつ message_start でない」の 1 行だ。
+ if self.__final_message_snapshot is None and sse_event.type != "message_start":
+ yield cast("ParsedMessageStreamEvent[ResponseFormatT]", sse_event)
+ continue
注意したいのは、既知の型でも message_start 前なら 蓄積されずに流れるだけ という点だ。今回は content_block_stop だったので害は無い。でも仮に content_block_delta が前に来たら、その text は get_final_message() に入らない。1.13 で例外になっていた状況が、1.14 では静かにテキストが欠ける状況に変わりうる。実 API がそういう順序で送ることがあるのかは知らないし、試してもいない。
except RuntimeError で「Unexpected event order」を拾ってリトライしているコードがあるなら、1.14 ではそこに来なくなる。
OpenTelemetry は SDK を入れていなければ何も起きないが、入れていると黙って span と traceparent が出る
1.14 では opentelemetry-api が必須依存に加わっていた。
--- 1.13.0 deps
Requires: anyio, docstring-parser, httpx2, jiter, pydantic, sniffio, typing-extensions
--- 1.14.0 deps
Requires: anyio, docstring-parser, httpx2, jiter, opentelemetry-api, pydantic, sniffio, typing-extensions
グローバルな TracerProvider を何も設定せずに helper を呼ぶと、出力は 1.13 と変わらなかった。モックの受信ログでも traceparent ヘッダは付いていない。1.14 側の venv には後の確認用に opentelemetry-sdk 1.45.1 が入った状態だったが、入っているだけでは何も起きない。
REQ {"path": "/v1/messages", "scenario": "normal", "traceparent": null, "ua": "Anthropic/Python 1.13.0"}
REQ {"path": "/v1/messages", "scenario": "normal", "traceparent": null, "ua": "Anthropic/Python 1.14.0"}
次に opentelemetry-sdk を入れ、TracerProvider に ConsoleSpanExporter を付けてグローバルに設定しただけで、クライアント側は何も変えずに呼んだ。span が 1 本出た(抜粋)。
"name": "anthropic.messages.create",
"kind": "SpanKind.CLIENT",
"attributes": {
"gen_ai.provider.name": "anthropic",
"gen_ai.operation.name": "chat",
"gen_ai.request.model": "claude-mock",
"gen_ai.request.stream": true,
"url.full": "http://127.0.0.1:8799/v1/messages",
"gen_ai.response.time_to_first_chunk": 0.041746,
"gen_ai.response.id": "msg_mock",
"anthropic.message.stop_reason": "end_turn",
"gen_ai.usage.input_tokens": 5,
"gen_ai.usage.output_tokens": 2
},
同じ呼び出しで、モックには traceparent が届いていた。
REQ {"path": "/v1/messages", "scenario": "normal", "traceparent": "00-ff45e60e394616259d489d26683cd865-0a7980ff2fddb85d-03", "ua": "Anthropic/Python 1.14.0"}
ソースの既定値を読むと、enabled も propagation も指定が無ければ True、content_mode は metadata_only になっている。プロンプトと応答の本文は既定では span に入らない。環境変数 ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content を付けると、属性が 2 つ増えた。
> "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"hi\"}]}]",
> "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"text\",\"content\":\"Hello world\"}]}]"
止め方は 2 つあって、Anthropic(open_telemetry=False) と環境変数 ANTHROPIC_OPEN_TELEMETRY=false のどちらでも span は出ず、traceparent も送られなかった。
リリースノートの「add OpenTelemetry tracing」からは、opt-in の機能に読める。実際は opt-out だった。アプリの別の場所(Web フレームワークの計装など)でグローバルな TracerProvider をもう設定しているなら、1.14 に上げた日から Claude の呼び出しが span として collector に流れ、W3C Trace Context の traceparent が API 側にも送られる。モック相手の確認なので、本物の api.anthropic.com がこのヘッダをどう扱うかは分からない。
自分が上げるなら、先に見るのは 3 か所
比べてみて、1.14 は「例外が減ってイベントが増える」方向の変更だった。壊れ方としては穏やかだと思う。それでも上げる前に確認する場所は決まっている。
for event in stream:の分岐がisinstanceかevent.typeか。未知の type はRawMessageStartEventの顔をして来るので、isinstance分岐はtypeの比較に変えるRuntimeErrorの「Unexpected event order」を拾っている箇所。1.14 では来なくなる- プロセスにグローバルな OpenTelemetry の
TracerProviderがあるか。あって、Claude の呼び出しを span にしたくないならopen_telemetry=Falseを渡す
試していないことも残っている。async クライアント(lib/streaming/_messages.py の AsyncMessageStream にも同じ素通しの行が入っているのはコードで確認しただけ)、beta の helper(_beta_messages.py にも同じ 2 行が入っているのは diff で確認しただけ)、同じリリースの「close dropped streams without waiting for the collector」の修正、それと実 API での挙動だ。