ag2-ag-ui

AG-UI 統合

使用する場面

• AG2 エージェントと連携する Web UI（React／Next.js／HTTP+SSE に対応するもの）を構築している場合。
• 標準プロトコルを使って、ストリーミングテキスト、推論、ツール呼び出しの表示、共有状態の同期、サブタスクのステップ追跡などをフロントエンドに表示したい場合。独自の REST／WebSocket 契約は使いません。
• CopilotKit（推奨される React クライアント）を使用している、または導入を検討している場合。

契約全体を自分で管理する、用途を限定したカスタム API を使う場合は、AG-UI を使わず、代わりに通常のエンドポイントを作成してください。

サポートされている AG-UI 機能

機能	状態
実行ライフサイクル（RUN_STARTED／RUN_FINISHED／RUN_ERROR）	✓
テキストのストリーミングイベント（TEXT_MESSAGE_START／_CONTENT／_END／_CHUNK）	✓
推論イベント（REASONING_START／_END、REASONING_MESSAGE_START／_CONTENT／_END）	✓
バックエンドツールのライフサイクル（TOOL_CALL_START／_ARGS／_RESULT／_END）	✓
フロントエンドツールのディスパッチ（RunAgentInput.tools 内のクライアントツールに対する TOOL_CALL_CHUNK）	✓
共有状態のスナップショット（STATE_SNAPSHOT）	✓
サブタスクのステップ（TaskStarted／TaskCompleted で発行される STEP_STARTED／STEP_FINISHED）	✓
AG-UI イベントとして表示される人間による入力チェックポイント	✗ — 人間による入力用のイベントファミリーはありません。hitl_hook は agent.ask にそのまま渡されます

インストール

pip install "ag2[ag-ui]"

必須です。コードを提供する前に、このインストールを実行してください。コマンドを実行できない場合は、正確な pip install コマンドを明記してください。

60 秒でできるレシピ — FastAPI サーバー

from fastapi import FastAPI, Header
from fastapi.responses import StreamingResponse

from ag2 import Agent
from ag2.ag_ui import AGUIStream, RunAgentInput
from ag2.config import OpenAIConfig

agent = Agent(
    name="support_bot",
    prompt="You help users with billing questions.",
    config=OpenAIConfig(model="gpt-4o-mini"),
)

stream = AGUIStream(agent)
app = FastAPI()

@app.post("/chat")
async def run_agent(message: RunAgentInput, accept: str | None = Header(None)) -> StreamingResponse:
    return StreamingResponse(
        stream.dispatch(message, accept=accept),
        media_type=accept or "text/event-stream",
    )

uvicorn run_ag_ui:app --reload --port 8000

テスト：

curl -N -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"thread_id":"t1","run_id":"r1","messages":[{"id":"m1","role":"user","content":"Hello"}],"state":{},"context":[],"tools":[]}'

より手軽な方法 — build_asgi()

カスタム認証／ミドルウェアが不要な場合は、ASGI エンドポイントを直接マウントできます。

from ag2.ag_ui import AGUIStream
from fastapi import FastAPI

app = FastAPI()
stream = AGUIStream(agent)
app.mount("/chat", stream.build_asgi())

CopilotKit フロントエンド（React／Next.js におすすめ）

始め方は 2 通りあります。

# Option A — CopilotKit bootstrap
npx copilotkit@latest create -f ag2

# Option B — clone the reference starter
# https://github.com/ag2ai/ag2-copilotkit-starter

スターターのレイアウト：

ag2-copilotkit-starter/
├── agent-py/     # Python backend (AG2 + AG-UI)
└── ui-react/     # React + CopilotKit frontend

バックエンドは、デフォルトでポート 8008 の /chat を提供します。ui-react/app/api/copilotkit/route.ts の Next.js ルートが UI とバックエンドをつなぎます。

import { HttpAgent } from "@ag-ui/client";
import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import { NextRequest } from "next/server";

const agent = new HttpAgent({ url: "http://localhost:8008/chat" });
const runtime = new CopilotRuntime({ agents: { weather_agent: agent } });

export async function POST(req: NextRequest) {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
}

アプリをラップします。

import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CopilotKit agent="weather_agent" runtimeUrl="/api/copilotkit">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

チャット（<CopilotChat />）を表示し、クライアントコンポーネントで useCopilotAction({...}) を使うと、バックエンドのツール呼び出しに連動する生成 UI を表示できます。

本番環境向けチェックリスト

• CORS — AG-UI バックエンドでフロントエンドのオリジン（POST、OPTIONS、認証ヘッダー）を許可します。
• 認証 — /api/copilotkit（Next.js ルート）とバックエンドの /chat の両方を保護します。クライアント側のシークレットだけに頼らないでください。
• SSE バッファリング — バックエンドのレスポンスが Content-Type: text/event-stream であること、およびプロキシ層（Nginx、CloudFront など）が SSE をバッファリングしないことを確認します。
• タイムアウト／再試行 — 長時間実行されるツールのワークフローには控えめな値を設定し、冪等なリクエストのみ再試行します。
• ツール入力は信頼できません — 特権ツールを呼び出す前に、サーバー側で検証と認可を行います。リクエスト ID とともにツールの実行をログに記録します。
• ツール名の一致 — フロントエンドの useCopilotAction の name は、バックエンドの @tool 名と完全に一致させる必要があります。

さらに詳しく

• website/docs/user-guide/ag-ui/index.mdx — AGUIStream、サポートされているイベント、基本的なサーバー。
• website/docs/user-guide/ag-ui/copilotkit-quickstart.mdx — React + CopilotKit の詳しい手順（ファイルレイアウト、ルート、レイアウト、チャットコンポーネント、天気カードの例）。
• AG-UI プロトコル：https://docs.ag-ui.com/introduction
• リファレンス用スターター：https://github.com/ag2ai/ag2-copilotkit-starter
• プロトコルレベルのテストには、AG2 Dojo プロファイルを使用してください：https://dojo.ag-ui.com/ag2/feature/agentic_chat

よくある落とし穴

• ag-ui extras の不足 — pip install "ag2[ag-ui]" が必要です。これがないと、from ag2.ag_ui import AGUIStream が失敗します。
• CORS によるブロック — 開発環境でフロントエンドからバックエンドにアクセスできません。開発用オリジンに対して、FastAPI アプリに CORSMiddleware を追加してください。
• ストリーミング出力がない — プロキシまたは Content-Type の問題です。まず生の curl -N でテストし、問題を切り分けてください。
• ツール UI が表示されない — React 側のツール名（useCopilotAction({ name: "..." })）が、バックエンドの @tool 名と完全に一致していません。
• SSE 非対応のプロキシの背後にエンドポイントを置く — 多くのプロキシは、デフォルトでイベントストリームのレスポンスをバッファリングします。このルートではバッファリングを無効にしてください。
• AGUIStream を従来の ConversableAgent で使おうとする — ここでは ag2.Agent について説明しています。従来の AG2 エージェントは別の方法で公開できます。その方法については、AG2 のドキュメントを確認してください。