メインコンテンツへスキップ
見出し画像

【新基準がぞくぞく】AG-UI プロトコル 1.0 の全貌:MCP・A2A と並ぶ「エージェントとUIをつなぐ」第3のオープン標準

    ようやく1.0になったぞーということで。
    わたしは以前から、自作カンバンツールでお世話になってたやつですっ

    modern-web-guidance-srcとか
    agent-plugins-specとか
    新しい基準がいっぱいになってきましたね。


    AIエージェント開発の世界では、ツール連携の 「MCP(Anthropic)」 と、エージェント間連携の 「A2A(Google)」 が急速に標準化されてきました。

    では、「バックエンドで動く自律エージェント」と「ユーザーが操作するフロントエンドUI」のあいだ はどうでしょうか?ってお話が今回の主軸。

    ここを埋めるオープンプロトコルとして、GitHubで 19,200スター超(2026年11月17日時点)を集め、ついに 仕様 1.0(Stable) に到達したのが 「AG-UI」 。(Agent–User Interaction Protocolとも書くみたい)

    CopilotKit が考案し、すでに Google・Microsoft・Amazon・Oracle や主要30以上のエージェントフレームワークが対応を進めている AG-UI 1.0 の仕組みと全貌を、仕様レベルから実装・セキュリティまでを徹底的に整理してみましたーっ。


    1. なぜエージェントに「AG-UI」が必要なのか?

    従来のWebアプリは REST や GraphQL による「リクエスト → データを返す → 画面を描画して終了」というモデルで動いていました。

    でーも、AIエージェントの振る舞いはこの型に収まりません。

    • 長時間かつストリーミング:マルチターンを跨いで中間結果を逐次流す必要がある

    • 非決定的:いつツールを呼び、いつUIを書き換えるかが事前に決まらない

    • 構造化+非構造化の混在:チャット文字(非構造)と、状態更新・フォーム表示(構造)が同時に発生する

    • 動的な合成(サブエージェント):処理の途中で別エージェントを呼び出す

    • 人間の介入(Human-in-the-loop):処理を一時停止し、人間の承認や修正を待ってから再開する

    これまで開発者は、LangGraph や CrewAI などのフレームワークごとに独自の WebSocket / SSE 配線(接着剤コード)を書き続けてきました。AG-UI はこの独自配線を 「1つの双方向・型付きイベントストリーム」 に標準化。

    MITライセンスです、助かるっ


    2. MCP / A2A / A2UI との棲み分け

    エージェントシステム全体の中で、各オープンプロトコルの役割は以下のように綺麗に整理できます。

    レイヤ | プロトコル / 仕様 | 起源 | 役割

    Agent ↔ User | AG-UI | CopilotKit | エージェントをユーザー向けUIへ接続するリアルタイム・双方向プロトコル
    Agent ↔ Tools | MCP | Anthropic | 外部ツール・DB・ワークフローへの安全な接続
    Agent ↔ Agent | A2A | Google | 分散したエージェント同士の調整・タスク分担
    Generative UI | A2UI / MCP Apps | Google 他 | 「エージェントが見せたいUI部品」の記述仕様。AG-UIはそのペイロードを運ぶランタイム

    ※ 名前が似ている「A2UI」と「AG-UI」ですが、A2UIは表示するウィジェットの仕様、AG-UIはフロントとバックエンドを繋ぐ通信プロトコルで、両者は協調して動作する感じです

    各社が協力して、今のこの感じに落ち着いた感じ。


    3. AG-UI の仕組み:1つの入力から「順序付きイベント列」へ

    AG-UI のやり取りは極めてシンプル。

    1. アプリ → エージェント:1通の `RunAgentInput` を送信して「run(実行)」を開始する

    2. エージェント → アプリ:8ファミリ・31種類の型付きイベントを 生成された順番どおり にストリーミングする

    設計思想の核心

    • サイドチャネルなし:ユーザーに見える状態変化やメッセージは、すべてこの1本のイベントストリームの中に流れます。そのためログをそのまま記録・再生・テストでき、トランスポート(SSE や Protobuf)を差し替えても同じUIを再構築できます。

    • Tolerant reader, strict writer(読み手は寛容、書き手は厳格):書き手はスキーマ通りのイベントを厳格に出力し、読み手は未知のフィールド・イベントを警告付きで安全に無視(除去)して処理を継続します。ただし既知のイベントで型や値が不正な場合は致命的エラーとして扱います。

    • 順序の厳格性:プロトコル上の順序は 「到着順」 であり、`timestamp` で並べ替えてはなりません。

    アプリから送る唯一のメッセージ `RunAgentInput`

    会話のたびにアプリがエージェントへ渡すJSON構造。

    • 必須項目:`threadId`(会話全体で不変)、`runId`(1回の実行ごとに一意、再利用不可)、`messages`(マルチモーダル `ContentPart` 対応の完全な履歴。ソースは `data` / `url` / プロバイダ発行ハンドル `file` の3種)

    • 任意項目:`tools`(アプリ側で実行するフロントエンドツール定義)、`context`(タイムゾーン等の注入情報)、`state`(run開始時の共有状態)、`forwardedProps`(アプリ固有の透過データ)、`resume`(前回の割り込みへの人間の回答)、`protocolVersion`、`parentRunId`


    4. 全31イベント・8ファミリ カタログと「3つのパターン」

    すべてのイベントは共通の `BaseEvent` エンベロープ(`type` 必須)を持ち、以下の 8ファミリ・全31種 で構成されます。

    1. Runs and steps(5種 / lifecycle)
      `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`, `STEP_STARTED`, `STEP_FINISHED`

    2. Text messages(4種 / streaming)
      `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`, `TEXT_MESSAGE_CHUNK`

    3. Tool calls(5種 / streaming)
      `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_CHUNK`, `TOOL_CALL_RESULT`

    4. Reasoning(7種 / streaming)
      `REASONING_START`, `REASONING_END`, `REASONING_MESSAGE_START`, `REASONING_MESSAGE_CONTENT`, `REASONING_MESSAGE_END`, `REASONING_MESSAGE_CHUNK`, `REASONING_ENCRYPTED_VALUE`(0.xの `THINKING_*` を置換)

    5. State(3種 / snapshot–delta)
      `STATE_SNAPSHOT`, `STATE_DELTA`(RFC 6902 JSON Patch), `MESSAGES_SNAPSHOT`

    6. Activity(2種 / snapshot–delta)
      `ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA`(構造化された進捗表示)

    7. Subagents(3種 / lifecycle)
      `SUBAGENT_STARTED`, `SUBAGENT_FINISHED`, `SUBAGENT_ERROR`

    8. Passthrough(2種 / standalone)
      `RAW`, `CUSTOM`(独自拡張用)

    イベントを組み立てる3つの基本パターン

    • ① ストリーミング(Text / Tool / Reasoning)
      `START` → `CONTENT × N` → `END` の順で流します(省略形の `*_CHUNK` 単一形式も可。最初のチャンクが `messageId` や `toolCallId` などの開始情報を保持する必要があります)。

    • ② スナップショット – デルタ(State / Activity)
      最初に `SNAPSHOT` で状態全体を送り、以降の更新は `STATE_DELTA` で RFC 6902 の JSON Patch 操作配列 を送って差分同期。不整合が起きた場合は再度スナップショットを要求できます。

    • ③ 割り込み – 再開(Human-in-the-loop)
      `RUN_FINISHED` の `outcome` フィールドに終了理由(`success` / `interrupt` / `cancelled`)を指定します。承認待ちなどで止める場合は `outcome: "interrupt"` として `interrupts[]` に待ち情報を載せて一度 run を閉じ、次の `RunAgentInput` の `resume[]` にユーザーの回答を入れて再開します。

    • ※ フロントエンドツール実行のために停止する場合は `interrupt` ではなく `success` で終了し、`pendingToolCallIds` に未回答IDを載せます


    5. トランスポート(ワイヤー)と「切断の扱い」

    AG-UI の意味論は通信方式に依存せず、プロトコルを乗せる下位層を「バインディング」として定義しています。

    • HTTP + SSE(標準・必須):POSTで `RunAgentInput` を送り、`text/event-stream` のJSONフレームで受信。HTTPを話す実装は必ず対応(MUST)。

    • HTTP + Protobuf(任意):コンテントネゴシエーションで4バイト長プレフィックスのバイナリフレームに切り替え。高効率で本番向き。

    • カスタム(可能):WebSocket、メッセージバス、インプロセス等も可。

    重要な制約として「終端イベントなしでストリームが切断された場合、クライアントは勝手に `RUN_FINISHED` をでっち上げて成功扱いにしてはならない」 と仕様で厳格に定められています。再実行する場合は新しい `runId` を使って別の run としてやり直す必要があります。


    6. 「AG-UI 1.0」で何が変わったのか?

    Spec 1.0 では JSON Schema と BCP 14 規約文によって仕様が凍結され、TypeScript / Python / .NET の公式SDKがスキーマから生成されるようになりましたー。

    0.x と 1.0 は双方向互換です
    旧形式は互換性境界で自動翻訳されます。

    1.0 の主な進化ポイント

    1. 仕様の明文化:順序、未知と不正の境界、帰属ルールがコードの暗黙知からドキュメント化された規約へ。

    2. `RUN_FINISHED.outcome` の導入:`success` / `interrupt` / `cancelled` の明確化と interrupt–resume パターン。

    3. Subagents 対応:`subagentRunId` によるイベント帰属と `SUBAGENT_*` ライフサイクル。

    4. `THINKING_` → `REASONING_` への刷新:モデルの中身を覗かずに往復させる暗号化成果物 `REASONING_ENCRYPTED_VALUE` に対応。

    5. Activity イベント:構造化された進捗状況(`ACTIVITY_SNAPSHOT` / `DELTA`)。

    6. `TOOL_CALL_RESULT` のマルチモーダル対応:文字列だけでなく `ContentPart` 列や `file` ソースも返却可能に。

    7. 共通トークン利用量レポート:`RUN_FINISHED` / `RUN_ERROR` にプロバイダ共通のトークン使用量(cached / reasoning 内数、キャッシュ read/write 分離)を搭載。

    8. `AgentCapabilities` のスキーマ統合:キー名が `subagents` に統一(旧 `subAgents` は非対応)。

    9. インバンドのバージョン交渉:`protocolVersion` の宣言。


    7. SDK・エコシステム・始め方・セキュリティ

    公式SDK と エコシステム

    • 公式 SDK:

      • TypeScript:`npm install @ag-ui/client`

      • Python:`pip install ag-ui-protocol`

      • .NET:`dotnet add package AGUI.Client`

    • 対応フレームワーク(30以上):LangChain (LangGraph), CrewAI, Microsoft Agent Framework, Google ADK / Antigravity, AWS Strands / Bedrock AgentCore, Mastra, Pydantic AI, LlamaIndex, Agno, AG2, Claude Agent SDK, OpenAI Agents SDK, Oracle Agent Spec 等。

    • クライアント:CopilotKit(React / Angular / Vue / React Native)、Slack & Teams、Terminal、OpenBot。コミュニティSDKとして Go / Rust / Kotlin / Swift / Java / Dart / C++ / Ruby なども展開されています。

    クイックスタート(CLI & 最小実装)

    # テンプレートからアプリを即座に生成(CopilotKit + Next.js / terminal)
    npx create-ag-ui-app@latest
    export OPENAI_API_KEY="sk-…"
    npm run dev

    プロトコルを話す最小の TypeScript エージェントは、数行で書けます。

    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: "m1", role: "assistant", content: "Hello, world!" }]
          },
          { type: EventType.RUN_FINISHED, threadId, runId },
        ])
      }
    }

    実装時に守るべきセキュリティ3原則

    1. ユーザーの同意と制御:副作用のあるツール実行の前には必ずアプリ側で明示的な同意を取得すること。

    2. モデル出力は「信頼できない入力」:ツール引数や状態更新は信頼境界を越えてやってきます。必ず検証しストリーム内容をサニタイズせずに実行可能なマークアップとして描画してはなりません。

    3. データは双方向に流れる:状態やメッセージは毎回の run で往復。機密情報(シークレット)を `state` に入れないこと、また `reasoning` や暗号化成果物も会話本体と同等の機密レベルで扱うことが求められます。


    まとめ

    MCP でツールを繋ぎ、A2A でエージェント同士を繋ぎ、AG-UI でユーザー画面と繋ぐ。これが現状の最適解って言われてるみたいですね

    AG-UI 1.0 の登場により、フロントエンドとAIエージェントの接続はようやく「フレームワークごとの独自実装」から解放され、記録・再生・テストが可能で、トランスポートも言語も問わない標準スタック を手に入れました。

    これからエージェントを組み込んだWeb・モバイルアプリや業務ツールを開発するなら、真っ先に検討すべき基盤プロトコル。


    参考・一次情報リンク


    #AI #AIエージェント #AGUI #MCP #A2A #フロントエンド #生成AI #開発 #プロトコル

    あなたへのおすすめ