AG-UI プロトコル スキル

概要

AG-UI (Agent-User Interaction) は、エージェントと UI の通信のための CopilotKit のオープンなイベントベースプロトコルです。すべてのエージェント・フロントエンド間のインタラクションは、SSE (Server-Sent Events) またはバイナリ protobuf トランスポート経由でストリーミングされる型付きイベントを通じて行われます。エージェントは AbstractAgent.run() を実装して RxJS Observable<BaseEvent> を返し、クライアント SDK がイベント適用、状態管理、メッセージ履歴を処理します。

使用するケース

• AG-UI と通信する必要があるカスタムエージェントバックエンドを構築している場合
• 新しいフレームワーク統合用に AbstractAgent.run() を実装する場合
• イベントがフロントエンドに到達しない、または不正な形式で到達している理由をデバッグする場合
• イベントの順序付け (ライフサイクル、テキスト、ツール呼び出し、状態) を理解する場合
• 状態同期 (スナップショット vs JSON Patch デルタ) で作業する場合
• 人間がループに介入する中断/再開フローを実装する場合
• SSE ストリーミングまたはエンコーディングの問題をトラブルシューティングする場合

使用しないケース

• CopilotKit React フック およびフロントエンドコンポーネント については copilotkit-develop を使用
• CopilotKit ランタイムのセットアップと設定については copilotkit-setup を使用
• フレームワーク固有の統合ガイド (LangGraph、Mastra、CrewAI) については copilotkit-integrations を使用

クイックリファレンス

イベントファミリー

ファミリー	イベント	目的
Lifecycle	RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_STARTED, STEP_FINISHED	実行の境界と進捗
Text	TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END	ストリーミングテキストメッセージ
Tool Calls	TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT	エージェントのツール呼び出し
State	STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT	状態同期
Reasoning	REASONING_START, REASONING_MESSAGE_START/CONTENT/END, REASONING_END, REASONING_ENCRYPTED_VALUE	思考過程の可視化
Activity	ACTIVITY_SNAPSHOT, ACTIVITY_DELTA	構造化された進捗更新
Custom	RAW, CUSTOM	拡張ポイント

便利なチャンクイベント

TEXT_MESSAGE_CHUNK と TOOL_CALL_CHUNK はクライアントの transformChunks パイプラインを通じて Start/Content/End の三つ組に自動展開されます。バックエンド実装をより簡潔にするために使用します。

SSE ワイヤフォーマット

各イベントは JSON オブジェクトとして SSE データ行として送信されます:

data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}\n\n
data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}\n\n
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello"}\n\n
data: {"type":"TEXT_MESSAGE_END","messageId":"m1"}\n\n
data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"}\n\n

パッケージ

パッケージ	npm	目的
@ag-ui/core	イベント、型、スキーマ	プロトコル定義
@ag-ui/client	AbstractAgent、HttpAgent、ミドルウェア、イベント適用	クライアント SDK
@ag-ui/encoder	EventEncoder (SSE + protobuf)	サーバー側エンコーディング

ワークフロー: AG-UI バックエンドの構築

1. エンドポイントを定義 -- RunAgentInput ボディの POST を受け入れ、text/event-stream で応答
2. 入力を解析 -- リクエストボディから threadId、runId、messages、tools、state、context を抽出
3. イベントを順序通りに発出 -- RUN_STARTED をまず発出し、次にコンテンツイベント、その後 RUN_FINISHED または RUN_ERROR
4. SSE としてエンコード -- @ag-ui/encoder の EventEncoder.encode() を使用するか、手動で data: JSON\n\n と記述
5. ツール結果を処理 -- クライアントが TOOL_CALL_RESULT を返送します。エージェントが処理して継続

完全に機能する例については references/building-agents.md を参照してください。

キープロトコルルール

• すべての実行は RUN_STARTED で開始し、RUN_FINISHED または RUN_ERROR で終了する必須です
• TEXT_MESSAGE_CONTENT.delta は空でない必須です
• ツール呼び出しイベントは toolCallId でリンクされます
• STATE_DELTA は RFC 6902 JSON Patch 操作を使用します
• 複数の順序付きの実行がサポートされています -- 各実行は次の実行が開始する前に完了する必須です
• メッセージは実行全体で累積されます。状態は STATE_SNAPSHOT でリセットされない限り継続されます

リファレンス

• references/protocol-spec.md -- スキーマと例を含むイベント型リファレンス全体
• references/building-agents.md -- AG-UI バックエンド構築のステップバイステップガイド
• references/event-flow-diagrams.md -- 一般的なフロー用の ASCII シーケンス図
• references/client-sdk.md -- @ag-ui/client API リファレンス