やってみた 2026年11月17日

AG-UI に15通りのイベント列を流したら、順番違いは即エラーなのに、途中で切れたストリームだけは静かに resolve した

XECIN TypeScriptAIエージェントストリーミングPython

GitHubのトレンドを眺めていたら、10位に ag-ui-protocol/ag-ui が入っていました。説明は「AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.」。AI エージェントと画面のあいだを、型の決まったイベントの流れでつなぐためのプロトコルと、その SDK 群です。スターは19,758、ライセンスは MIT、npm の @ag-ui/client は 11月5日に公開された 1.0.4 が最新でした。

私はバックエンドの仕事が長く、SSE やロングポーリングのように「流れてくるもの」を扱う現場をいくつか見てきました。そういう仕組みで後から効いてくるのは、たいてい正常系ではなく、相手が約束を破ったときの振る舞いなんですよね。プロキシのタイムアウトで流れが途中で切れ、画面のくるくるが止まらなくなった、というケースもありました。

なので今回は、README の最小構成を動かしたあと、わざと壊れたイベント列をクライアントに食べさせてみることにしました。

試した環境

  • 使い捨ての Docker コンテナ(node:22-bookworm。上限は CPU 2・メモリ 4GB・PID 512、ポートは外に出していません)。ホストには何も入れていません
  • Node 22.23.1 / npm 10.9.8、Python 3.11.2(Debian 12.14 の標準。python3-venv だけ apt で足しました)
  • TypeScript 側: @ag-ui/client 1.0.4、tsx 4.23.15
  • Python 側: ag-ui-protocol 1.0.0、fastapi 0.163.1、uvicorn 0.54.0、pydantic 2.14.3
  • ソースの確認: GitHub の main(79530a25、2026-11-16 のコミット)

コンテナを立ててから捨てるまでは4分43秒でした。

まずは README の最小構成から

README の冒頭には npx create-ag-ui-app@latest で雛形を作る道があります。ただ、生成されるテンプレートは OpenAI を呼ぶので OPENAI_API_KEY が要る、と README 自身に書かれています。キーを使わずにプロトコルそのものを見たかったので、そちらは選ばず、折りたたまれた「Or speak the protocol directly」のほう、Python の最小サーバーと TypeScript のクライアントを README のコードのまま使いました。

# Python 側(venv の中で。時間は date で前後を測った値)
$ pip install ag-ui-protocol fastapi uvicorn        # 3,133ms
$ pip list
ag-ui-protocol    1.0.0
fastapi           0.163.1
pydantic          2.14.3
uvicorn           0.54.0

# TypeScript 側(新しいフォルダで)
$ npm init -y && npm pkg set type=module
$ npm install @ag-ui/client tsx                     # 2,781ms
client@1.0.0 /work/client
+-- @ag-ui/client@1.0.4
`-- tsx@4.23.15

# uvicorn server:app --port 8000 を起動しておいて
$ npx tsx client.ts                                 # 503ms
run started (AG-UI 1.0)
Hello from AG-UI!
run finished
rc=0

依存はどちらも3秒前後で入り、README に書かれたとおり Hello from AG-UI! が流れてきました。ここまでで詰まるところは何もありません。node_modules は 40MB で、@ag-ui の下には client・core・encoder・proto の4つが入っていました。

最初のアプローチ: Python のサーバーから protobuf を返そうとした

README には、AG-UI の仕様が HTTP + SSE に加えてバイナリの HTTP + Protobuf も定めている、と書かれています。SSE はテキストなので、どれくらい軽くなるのかを先に測っておきたくなりました。README の Python サーバーは EventEncoder(accept=request.headers.get("accept")) という形で Accept を受け取っているので、protobuf の media type を渡せば切り替わるのだろう、と考えたわけです。

結果は、Content-Type もバイト数も SSE とまったく同じでした。

# 同じイベント列を EventEncoder(accept="application/vnd.ag-ui.event+proto") と SSE で符号化した合計
{"n":3,"sse":486,"sse_type":"text/event-stream","proto":486,"proto_type":"text/event-stream"}
{"n":200,"sse":14868,"sse_type":"text/event-stream","proto":14868,"proto_type":"text/event-stream"}

# 入っていた ag_ui/encoder/encoder.py(ag-ui-protocol 1.0.0。docstring は省略)
AGUI_MEDIA_TYPE = "application/vnd.ag-ui.event+proto"

class EventEncoder:
    def __init__(self, accept: str = None):
        pass

    def get_content_type(self) -> str:
        return "text/event-stream"

    def encode(self, event: BaseEvent) -> str:
        return self._encode_sse(event)

実装を開いてみると、accept は受け取るだけで使われておらず、get_content_type() は常に text/event-stream を返していました。media type の定数は定義されているのに、このファイルの中では使われていません。少なくとも今回入った 1.0.0 では、Python の SDK から protobuf は出てきませんでした。README のサンプルが Accept を渡しているのは将来の切り替えに備えた書き方なのかもしれませんが、そこまでは確かめていません。

改善後のアプローチ: TypeScript のエンコーダーで測る

TypeScript 側の @ag-ui/encoder には encodeBinary() があり、こちらは protobuf を返します。同じイベント列(RUN_STARTED・TEXT_MESSAGE_START・本文・TEXT_MESSAGE_END・RUN_FINISHED)を両方の形式で符号化して、合計のバイト数を比べました。ついでに、protobuf だけを返す小さな Node のサーバーを立てて、HttpAgent に読ませています。

{"n":3,"events":7,"sse_bytes":462,"proto_bytes":138,"ratio":0.299,"sse_type":"text/event-stream","proto_type":"application/vnd.ag-ui.event+proto"}
{"n":200,"events":204,"sse_bytes":14844,"proto_bytes":4473,"ratio":0.301,"sse_type":"text/event-stream","proto_type":"application/vnd.ag-ui.event+proto"}

# protobuf だけを返すサーバーに HttpAgent をつないだ
{"server_saw_accept":"text/event-stream"}
{"case":"proto_to_httpagent","events":["RUN_STARTED","TEXT_MESSAGE_START","TEXT_MESSAGE_CONTENT","TEXT_MESSAGE_CONTENT","TEXT_MESSAGE_CONTENT","TEXT_MESSAGE_END","RUN_FINISHED"],"error":null,"messages":["user:Hi there!","assistant:Hello from AG-UI!"]}

protobuf は SSE のおよそ3割でした(7イベントで462→138バイト、204イベントで14,844→4,473バイト)。Python で測った SSE より24バイト少ないのは、Python 側の RUN_STARTED にだけ protocolVersion を付けていたためで、,"protocolVersion":"1.0" がちょうど24文字です。

面白かったのは HttpAgent の側です。サーバーが受け取った Accept は text/event-stream だけでした。それでも、応答の Content-Type が protobuf なら protobuf として読み、7イベントすべてを受け取っています。クライアントが自分から protobuf を頼むことはないけれど、来れば読める、という作りでした。

本題: 壊れたイベント列を食べさせる

ここからが本当に試したかったところです。?case= の値で送るイベント列を切り替える FastAPI のサーバーを書き、HttpAgent を1ケース1プロセスで走らせました。違反する列は Python の型(pydantic のモデル)を通すと作りにくいので、SSE の data: 行を JSON で直接書いています。正しい列2本を含めて15通りです。

ケース送ったものクライアントの結果rc
okREADME と同じ正しい列(JSON を直書き)7イベントを受信。Hello from AG-UI!0
enc_sse同じ列を Python の EventEncoder で符号化ok と同じ0
no_startTEXT_MESSAGE_START なしで CONTENTAGUIError(No active text message found)1
no_run_startedRUN_STARTED なしで始めるAGUIError(最初のイベントが RUN_STARTED ではない)1
after_finishRUN_FINISHED のあとに新しいメッセージRUN_FINISHED までは受理し、そのあと AGUIError1
double_startRUN_STARTED を2回AGUIError(while a run is still active)1
unclosed_msgTEXT_MESSAGE_END なしで RUN_FINISHEDAGUIError(text messages are still active: m1)1
run_errorRUN_ERROR のあとに CONTENTonRunErrorEvent が呼ばれ、そのあと AGUIError(already errored)1
bad_jsondata: {not json} を1行SyntaxError(JSON.parse)1
unknown_type型が FOO のイベントを途中に警告を出して捨て、続行。Hello world0
bad_patch存在しないパスを remove する STATE_DELTA、続けて正しい STATE_DELTA警告を出し、次の delta は適用。state の count は 30
empty_deltadelta が空文字の CONTENTそのまま受理0
chunk_onlyTEXT_MESSAGE_CHUNK だけを2つSTART・CONTENT×2・END に展開。Hello chunks0
stateSTATE_SNAPSHOT のあとに STATE_DELTA(add と replace)state の count が 2 になり、items に a が1つ入る0
no_finishRUN_STARTED・START・CONTENT のあと接続を閉じるエラーなし。会話に Hello が残る0

rc が1になった7通り(順番の違反6通りと、壊れた JSON)は、どれも AGUIError か SyntaxError で runAgent() の Promise が reject されました。onRunFailed もそのたびに呼ばれています。エラー文がかなり親切で、何が足りないのかと、次に何を送るべきかまで書いてありました。

# 1ケース=1プロセス。error 欄だけ抜粋(ms は runAgent の所要時間)
no_start        37ms  AGUIError: Cannot send 'TEXT_MESSAGE_CONTENT' event: No active text message found with ID 'm1'. Start a text message with 'TEXT_MESSAGE_START' first.
no_run_started  37ms  AGUIError: First event must be 'RUN_STARTED'
after_finish    41ms  AGUIError: Cannot send event type 'TEXT_MESSAGE_START': The run has already finished with 'RUN_FINISHED'. Start a new run with 'RUN_STARTED'.
unclosed_msg    45ms  AGUIError: Cannot send 'RUN_FINISHED' while text messages are still active: m1
bad_json        38ms  SyntaxError: Expected property name or '}' in JSON at position 1 (line 1 column 2)

# 自分で catch していても、ライブラリがこれを出力する(at の行は10行続く)
Agent execution failed: AGUIError: Cannot send 'TEXT_MESSAGE_CONTENT' event: No active text message found with ID 'm1'. Start a text message with 'TEXT_MESSAGE_START' first.
    at <anonymous> (/work/client/node_modules/@ag-ui/client/src/verify/verify.ts:427:19)
    at Observable.init (/work/client/node_modules/rxjs/src/internal/observable/throwError.ts:123:68)

# 警告で済んだもの(console.warn を差し替えて拾った。記録は160文字で切っている)
unknown_type    [ag-ui][enforce] Dropping unrecognised event 'FOO': no middleware translated it and the protocol does not describe it.
bad_patch       Failed to apply state patch:\nCurrent state: {\n  "count": 1\n}\nPatch operations: [\n  {\n    "op": "remove",\n    "path": "/nope"\n  }\n]\nError: Cannot perform the ope

上のコードブロックの中段は、改善の余地というより、自分の使い方次第だと思ったところです。エラーを自分でログに出す作りにすると、ライブラリの出力と合わせて同じ失敗が二重に残ります。本番ではログの出し先を一度整理したくなりそうです。

下段の2つは、警告だけで run は最後まで進み、rc は0でした。存在しないパスを消そうとした STATE_DELTA は適用されず、その直後の正しい STATE_DELTA は普通に当たって、state は count が3になっています。未知の型を捨てて進むのは、イベントの種類が増えても古いクライアントが止まらないための作りなのだと思います。ここは好みが分かれるところですが、私は開発中だけでも、この警告を失敗として扱える切り替えが欲しいと感じました。

空の delta は、最初は弾かれるだろうと思っていました。実際は TypeScript のクライアントも Python のモデルも受理しています。仕様(docs/spec/1.0/schema.mdx)を読むと「May be the empty string: providers emit empty deltas as keep-alives」とあり、keep-alive のために空文字を許すのは意図した作りでした。

途中で切れたストリームだけは、静かに終わる

表の最後の行が、今回いちばん気になったところです。RUN_STARTED・TEXT_MESSAGE_START・CONTENT を1つ送ったところでサーバーが接続を閉じると、エラーは出ず、rc は0、会話には途中までの Hello がアシスタントの発言として残りました。正常に終わった場合と何が違うのかを見るために、終わりに呼ばれるフックと runAgent() の戻り値を並べています。

# finish-hooks.ts: 終わりに呼ばれたフックと、runAgent が返した newMessages
{"case":"ok","hooks":["onRunFinishedEvent","onRunFinalized"],"resolved":true,"result":null,"newMessages":["assistant:Hello from AG-UI!"]}
{"case":"no_finish","hooks":["onRunFinalized"],"resolved":true,"result":null,"newMessages":["assistant:Hello "]}

違いは、onRunFinishedEvent が呼ばれないことだけでした。onRunFailed は呼ばれず、Promise は resolve し、newMessages には Hello が入っています。

仕様では、これは「truncated run」として扱いが決まっていました(docs/spec/1.0/basic/transports/index.mdx の Truncation の節)。

A truncated run has no outcome. A consumer MUST NOT synthesize a RUN_FINISHED for it and MUST NOT report it as having succeeded; everything the run delivered before the break remains delivered.

HttpAgent は RUN_FINISHED を合成していないので、そこは仕様どおりです。その先、途切れたことをどう見せるかは「consumer’s business」と仕様が明言しています。なので私は、これをライブラリの不具合というより、使う側が拾うべき穴として受け取りました。await agent.runAgent() が例外なく返ってきたら成功、と書いてしまうと、途中で切れた返答を完成品として画面に残すことになります。冒頭のくるくるの件もそうでしたが、こういうものはたいてい本番で初めて踏みます。

私が組み込むなら、onRunFinishedEvent と onRunErrorEvent のどちらかが呼ばれたかを自分で記録しておき、どちらも無いまま resolve したら「途切れた」として扱います。今回の finish-hooks.ts がしていたのがまさにその記録で、正常終了との差はそこにしか出ませんでした。

試してみての所感

正直なところ、イベントの順番をここまで細かく見てくれるとは思っていませんでした。START のないメッセージや、閉じていない run のまま次を始めるような列は、どれも1行の分かりやすいエラーで止まります。エージェント側を自前で書くなら、このクライアントに流してみるだけで、順番のバグはかなり早く見つかりそうです。

一方で、失敗にならずに通るものが3種類ありました。途中で切れた流れ、未知の型、当たらなかった JSON Patch です。途中で切れた流れの扱いは仕様が使う側に委ねていますし、残りの2つも流れを止めないための作りに見えます(こちらは仕様の該当箇所までは読んでいません)。ただ、どれも画面側で拾わないと気づけないので、私なら最初に途切れの判定を入れ、警告はログで監視します。

protobuf は、TypeScript 同士なら SSE のおよそ3割まで縮みました。Python の SDK(1.0.0)はまだ SSE しか出さないので、Python でエージェントを書く人はしばらく SSE 前提で考えることになりそうです。ここは次の版を様子見しようと思います。