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/client1.0.4、tsx4.23.15 - Python 側:
ag-ui-protocol1.0.0、fastapi0.163.1、uvicorn0.54.0、pydantic2.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 |
|---|---|---|---|
| ok | README と同じ正しい列(JSON を直書き) | 7イベントを受信。Hello from AG-UI! | 0 |
| enc_sse | 同じ列を Python の EventEncoder で符号化 | ok と同じ | 0 |
| no_start | TEXT_MESSAGE_START なしで CONTENT | AGUIError(No active text message found) | 1 |
| no_run_started | RUN_STARTED なしで始める | AGUIError(最初のイベントが RUN_STARTED ではない) | 1 |
| after_finish | RUN_FINISHED のあとに新しいメッセージ | RUN_FINISHED までは受理し、そのあと AGUIError | 1 |
| double_start | RUN_STARTED を2回 | AGUIError(while a run is still active) | 1 |
| unclosed_msg | TEXT_MESSAGE_END なしで RUN_FINISHED | AGUIError(text messages are still active: m1) | 1 |
| run_error | RUN_ERROR のあとに CONTENT | onRunErrorEvent が呼ばれ、そのあと AGUIError(already errored) | 1 |
| bad_json | data: {not json} を1行 | SyntaxError(JSON.parse) | 1 |
| unknown_type | 型が FOO のイベントを途中に | 警告を出して捨て、続行。Hello world | 0 |
| bad_patch | 存在しないパスを remove する STATE_DELTA、続けて正しい STATE_DELTA | 警告を出し、次の delta は適用。state の count は 3 | 0 |
| empty_delta | delta が空文字の CONTENT | そのまま受理 | 0 |
| chunk_only | TEXT_MESSAGE_CHUNK だけを2つ | START・CONTENT×2・END に展開。Hello chunks | 0 |
| state | STATE_SNAPSHOT のあとに STATE_DELTA(add と replace) | state の count が 2 になり、items に a が1つ入る | 0 |
| no_finish | RUN_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_FINISHEDfor 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 前提で考えることになりそうです。ここは次の版を様子見しようと思います。