Agent User Interaction プロトコル (AG-UI) は、柔軟なイベント駆動型アーキテクチャの上に構築されていて、フロントエンド App と AI エージェント間のシームレスで効率的な通信を可能にします。このドキュメントでは、主要なアーキテクチャのコンポーネントとコンセプトについて解説します。
AG-UI : コンセプト – コア・アーキテクチャ
作成 : Masashi Okumura (@classcat.com)
作成日時 : 04/19/2026
バージョン : v0.0.52
* 本記事は docs.ag-ui.com の以下のページを参考にしています :
* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
AG-UI : コンセプト – コア・アーキテクチャ
AG-UI がフロントエンド・アプリケーションを AI エージェントにどのように接続するのかを理解します。
Agent User Interaction プロトコル (AG-UI) は、柔軟なイベント駆動型アーキテクチャの上に構築されていて、フロントエンド・アプリケーションと AI エージェント間のシームレスで効率的な通信を可能にします。このドキュメントでは、主要なアーキテクチャのコンポーネントとコンセプトについて解説します。
デザイン原理
AG-UI は軽量で、(設計上の押し付けを) 最小限にするように設計されていて、幅広いエージェント実装との統合を容易にしています。プロトコルの柔軟性は、以下の単純な要件に由来します :
- イベント駆動型通信：エージェントは実行中に 16 個の標準化されたイベントタイプのいずれかを発行し、クライアントが処理可能な更新のストリームを生成する必要があります。
- 双方向インタラクション：エージェントはユーザーからの入力を受け付け、人間と AI がシームレスに連携する協調ワークフローを可能にします。
このプロトコルは、組み込みのミドルウェア層を含み、これは 2 つの主要な方法で互換性を最大化します :
- 柔軟なイベント構造：イベントは AG-UI のフォーマットに正確に一致する必要はありません – AG-UI 互換である必要があるだけです。これは、既存のエージェントフレームワークが最小限の労力でネイティブのイベントフォーマットを適応させることを可能にします。
- トランスポート非依存：AG-UI はイベントの配信方法を規定せず、Server-Sent Events（SSE）、Webhook、WebSocket を含む、トランスポートメカニズムをサポートしています。この柔軟性により、開発者はアーキテクチャに最適なトランスポートを選択できます。
この実用的なアプローチにより、AG-UI は既存のエージェント実装やフロントエンド・アプリケーションに大きな変更を加える必要なしに、容易に導入できます。
アーキテクチャ概要
AG-UIは、エージェントとアプリケーション間の通信を標準化するクライアント・サーバー・アーキテクチャに従っています :
- アプリケーション：ユーザー向けアプリケーション (i.e. チャットや AI 有効化アプリケーション)。
- AG-UI クライアント：HttpAgent のような汎用通信クライアント、または既存プロトコルに接続するための専用クライアント。
- エージェント：リクエストを処理し、ストリーミングレスポンスを生成するバックエンド AI エージェント。
- セキュアなプロキシ：追加機能を提供し、セキュアなプロキシとして機能するバックエンドサービス。
コア・コンポーネント
プロトコルレイヤー
AG-UI のプロトコルレイヤーは、エージェント通信のための柔軟な基盤を提供します。
- ユニバーサル互換性 : run(input: RunAgentInput) -> Observable<BaseEvent> を実装することで、任意のプロトコルに接続できます
このプロトコルの主要な抽象化は、アプリケーションがエージェントを実行し、イベントのストリームを受信することを可能にします :
// Core agent execution interface
type RunAgent = () => Observable
class MyAgent extends AbstractAgent {
run(input: RunAgentInput): RunAgent {
const { threadId, runId } = input
return () =>
from([
{ type: EventType.RUN_STARTED, threadId, runId },
{
type: EventType.MESSAGES_SNAPSHOT,
messages: [
{ id: "msg_1", role: "assistant", content: "Hello, world!" }
],
},
{ type: EventType.RUN_FINISHED, threadId, runId },
])
}
}
標準 HTT Pクライアント
AG-UIは、標準 HTTP クライアントである HttpAgent を提供しています、これは RunAgentInput 型のボディを持つ POST リクエストを受け取り、BaseEvent オブジェクトのストリームを送信する、任意のエンドポイントに接続するために使用できます。
HttpAgent は以下のトランスポートをサポートしています :
- HTTP SSE (Server-Sent Events)
- 幅広い互換性のためのテキストベースのストリーミング
- 読みやすくデバッグしやすい
- 幅広い互換性のためのテキストベースのストリーミング
- HTTP バイナリ・プロトコル
- 高性能かつ省スペースなカスタムトランスポート
- 本番環境向けの堅牢なバイナリ・シリアライゼーション
- 高性能かつ省スペースなカスタムトランスポート
メッセージ・タイプ
AG-UIは、エージェント通信の様々な側面のために、幾つかのイベントカテゴリを定義しています :
- ライフサイクル・イベント
- RUN_STARTED, RUN_FINISHED, RUN_ERROR
- STEP_STARTED, STEP_FINISHED
- RUN_STARTED, RUN_FINISHED, RUN_ERROR
- テキストメッセージ・イベント
- TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END
- ツール呼び出しイベント
- TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END
- 状態管理イベント
- STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT
- 特殊イベント
- RAW, CUSTOM
エージェントの実行
エージェントを実行するには、クライアントインスタンスを作成してそれを実行します :
// Create an HTTP agent client
const agent = new HttpAgent({
url: "https://your-agent-endpoint.com/agent",
agentId: "unique-agent-id",
threadId: "conversation-thread"
});
// Start the agent and handle events
agent.runAgent({
tools: [...],
context: [...]
}).subscribe({
next: (event) => {
// Handle different event types
switch(event.type) {
case EventType.TEXT_MESSAGE_CONTENT:
// Update UI with new content
break;
// Handle other event types
}
},
error: (error) => console.error("Agent error:", error),
complete: () => console.log("Agent run complete")
});
状態管理
AG-UIは、以下の特殊イベントを通じて効率的な状態管理を提供します :
- STATE_SNAPSHOT : ある時点における完全な状態表現
- STATE_DELTA: JSON Patch 形式（RFC 6902）を使用した漸進的な状態変化
- MESSAGES_SNAPSHOT: 完全な会話履歴
これらのイベントは、最小限のデータ転送で効率的なクライアント側の状態管理を可能にします。
ツールとハンドオフ
AG-UI は、標準化されたイベントを通じてエージェント-to-エージェントのハンドオフとツール使用をサポートしています :
- ツール定義は runAgent パラメータで渡されます。
- ツール呼び出しは、TOOL_CALL_START → TOOL_CALL_ARGS → TOOL_CALL_END イベントのシーケンスとしてストリーミングされます。
- エージェントは、コンテキストの継続性を維持しながら、他のエージェントにハンドオフできます。
イベント
AG-UI におけるすべての通信は、型付きイベントに基づいています。すべてのイベントは BaseEvent を継承します :
interface BaseEvent {
type: EventType
timestamp?: number
rawEvent?: any
}
イベントは厳密に型付け・検証され、コンポーネント間の信頼性の高い通信を保証します。
以上