AI

anthropic SDK 1.14 で stream() に届くイベントが増える条件

anthropic-sdk-python 1.13.0 と 1.14.0 に同じ SSE モックを流した。未知の type が helper に届くのは既知の event 名に載ったときだけで、実体は RawMessageStartEvent。順序外イベントと OpenTelemetry の既定の出方も比べた。

SoSoraEndo2026年10月15日 09:1124 min1,920 字

動画で読む

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.01.14.0
正常系helper / raw同じ列、final = Hello world同じ
event: foo_deltahelper / rawfoo_delta 出ない出ない
event: 行なしhelper / raw出ない出ない
event: message + type: foo_deltarawfoo_delta が出る出る
同上helper出ない出る
event: content_block_delta + type: foo_deltaraw出る出る
同上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 は「例外が減ってイベントが増える」方向の変更だった。壊れ方としては穏やかだと思う。それでも上げる前に確認する場所は決まっている。

  1. for event in stream: の分岐が isinstance か event.type か。未知の type は RawMessageStartEvent の顔をして来るので、isinstance 分岐は type の比較に変える
  2. RuntimeError の「Unexpected event order」を拾っている箇所。1.14 では来なくなる
  3. プロセスにグローバルな 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 での挙動だ。

Tags

参考文献

  1. anthropic-sdk-python Release v1.14.0
  2. anthropic-sdk-python(GitHub リポジトリ)
  3. Streaming Messages(Claude API Docs)
  4. Trace Context(W3C Recommendation)

Reaction

Share

X (Twitter)