Amazon Bedrock AgentCore で AG-UI プロトコルを活用し、AI エージェントに生成型 UI を構築する方法

AI エージェントはチャット以上のことができます。適切なプロトコルがあれば、エージェントは会話の途中でインタラクティブなチャートをインライン表示したり、共有キャンバスをリアルタイムで更新したり、実行中に一時停止して次の手順に進む前に承認を求めることもできます。これらの相互作用（生成 UI、共有状態、人間によるループ処理）には、エージェントバックエンドがフロントエンドに動的イベントを通信するための標準的な方法が必要です。

AG-UI (Agent-User Interaction Protocol) は、この標準を定義するオープンプロトコルです。これは複数のエージェントフレームワーク（Strands Agents, LangGraph, CrewAI）およびフロントエンドライブラリ（React, Angular, Vue）と連携します。AG-UI を使用すれば、エージェントコードとフロントエンドコードは分離された状態を保ちます。バックエンドには最適なフレームワークを、フロントエンドには最適なライブラリを選択し、AG-UI がそれらを接続します。

Amazon Bedrock AgentCore は、生成 AI 向けの Amazon Bedrock サービスファミリーの一部です。AgentCore は、あらゆるフレームワークとモデルを使用して、AI エージェントを安全に大規模で構築・展開・運用するためのエージェントプラットフォームです。

本記事では、AG-UI が Amazon Bedrock AgentCore 上でインタラクティブなエージェントフロントエンドを構築するために、Fullstack AgentCore Solution Template (FAST) にどのように統合されるかを解説します。その後、CopilotKit がこれに生成型 UI（ジェネレーティブ UI）、共有状態、人間を介したループ処理（ヒューマン・イン・ザ・ループ）の機能を追加し、すべてが Amazon Bedrock AgentCore 上でデプロイされる様子を示します。

ソリューションの概要

Amazon Bedrock AgentCore Runtime は、AI エージェントやツールのデプロイおよび実行のための安全でサーバーレスかつ目的に特化したホスティング環境を提供します。AgentCore Runtime は複数のエージェントプロトコルをサポートしています。Model Context Protocol (MCP) はエージェントをツールに接続し、Agent2Agent (A2A) はエージェント同士を接続し、AG-UI はエージェントをユーザーに接続します。AG-UI プロトコルフラグ付きのエージェントコンテナをデプロイすると、AgentCore は透過的なプロキシとして機能します。認証（Amazon Cognito を介した Signature Version 4 [SigV4] または OAuth 2.0）、セッションの分離、スケーリング、観測可能性を処理します。あなたのコンテナは、AG-UI リクエスト用の POST /invocations と、ポート 8080 でのヘルスチェック用の GET /ping を公開します。AgentCore はリクエストを変更せずに通過させます。詳細については、Deploy AGUI servers in AgentCore Runtime をご覧ください。

FAST は、すぐにデプロイ可能なスタータープロジェクトです。これは、React フロントエンドと Amazon Cognito による認証を備え、AWS Cloud Development Kit (AWS CDK) で定義された AgentCore Runtime、Gateway、Identity、Memory、Code Interpreter を接続するものです。Strands Agents、LangGraph、Claude Agent SDK 用のエージェントパターンも同梱されています。FAST v0.4.1 では、単一のフロントエンドパーサーを共有する 2 つの AG-UI パターン (agui-strands-agent および agui-langgraph-agent) が追加されました。FAST のアーキテクチャとデプロイに関する完全なウォークスルーについては、Amazon Bedrock AgentCore 向けのフルスタックスターターテンプレートでエージェント型アプリケーション開発を加速する をご覧ください。

このソリューションには 2 つのレイヤーがあります。FAST 内の AG-UI は、2 つの新しいエージェントパターンと、両方を処理する単一のフロントエンドパーサーを提供し、フロントエンドがどのエージェントフレームワークが実行されているかを知らなくても済むようにします。CopilotKit + FAST は、FAST の組み込みチャット UI を CopilotKit に置き換えたスタンドアロンのサンプルです。これにより、ジェネレーティブ UI（インラインのチャートやコンポーネント）、双方向共有状態（To-Do キャンバス）、人間をループに組み込んだインタラクション（エージェントを一時停止して入力を待つ会議スケジューラー）が追加されます。両方のレイヤーは、Cognito 認証、MCP ツール接続用の AgentCore Gateway、永続的な会話のための AgentCore Memory を備えた AgentCore Runtime でデプロイされます。

アーキテクチャの概要。フロントエンドは AG-UI イベントを通じて AgentCore Runtime と通信します。AgentCore は認証、スケーリング、セッションの分離を処理します。エージェントランタイムはフレームワーク固有のイベントを AG-UI プロトコルに変換します。

ウォークスルー

このウォークスルーには 2 つの部分があります。まず、AG-UI パターンが FAST でどのように機能するか、および単一のフロントエンドパーサーが Strands および LangGraph の両方のバックエンドをどのように処理するかを示します。次に、CopilotKit サンプルをデプロイして、AgentCore 上の生成型 UI、共有状態、人間をループに組み込んだプロセスを実演します。

ソースコード:

• AG-UI パターンを含む FAST リポジトリ。

• CopilotKit と FAST のサンプル。

前提条件

このウォークスルーでは、以下の前提条件を満たしている必要があります：

• AWS CloudFormation、Amazon Elastic Container Registry (Amazon ECR)、Amazon Bedrock AgentCore、Amazon Cognito、および AWS Amplify に対する権限を持つ AWS アカウント。

• インストールして設定された AWS Command Line Interface (AWS CLI) v2。

• インストールされた AWS CDK。

• Node.js 18 以降および Python 3.11 以降。

• コンテナビルド用の Docker の実行環境。

• エージェントが使用するモデルに対して、Amazon Bedrock コンソールでモデルアクセスが有効になっていること。

AG-UI in FAST: One parser, two frameworks

agui-strands-agent パターンは、ag-ui-strands ライブラリ内の StrandsAgent を用いて Strands Agent をラップします。このラッパーは、Strands のストリーミングイベントを自動的に AG-UI サーバー送信イベントに変換します。

各リクエストごとに、Gateway MCP ツールを備えた新規エージェントが作成されます。AgentCore Memory は、session-manager プロバイダーを通じてスレッドごとにアタッチされるため、会話履歴は AgentCore Runtime のスケーリングを超えて維持されます。メモリ機能はオプトイン方式であり、MEMORY_ID が設定されていない場合、プロバイダーは None を返します:

# patterns/agui-strands-agent/agent.py

from ag_ui_strands import StrandsAgent, StrandsAgentConfig

from bedrock_agentcore.runtime import BedrockAgentCoreApp, RequestContext

from strands import Agent

app = BedrockAgentCoreApp()

モデルとコードインタープリターは、モジュール読み込み時に一度だけ構築する

MODEL = BedrockModel(model_id="us.anthropic.claude-sonnet-4-5-20250929-v1:0")

CODE_INTERPRETER = StrandsCodeInterpreterTools(REGION).execute_python_securely

@app.entrypoint

async def invocations(payload: dict, context: RequestContext):

input_data = RunAgentInput.model_validate(payload)

actor_id = extract_user_id_from_context(context)

# Fresh agent per request --- picks up the caller's identity and tools

agent = Agent(

model=MODEL,

system_prompt=SYSTEM_PROMPT,

tools=[create_gateway_mcp_client(actor_id), CODE_INTERPRETER],

session_manager=get_memory_session_manager(actor_id, session_id),

)

agui_agent = StrandsAgent(

agent=agent,

name="agui_strands_agent",

config=StrandsAgentConfig(

session_manager_provider=make_memory_provider(actor_id),

replay_history_into_strands=False,

),

)

async for event in agui_agent.run(input_data):

yield event.model_dump(mode="json", by_alias=True, exclude_none=True)

BedrockAgentCoreApp は、AgentCore Runtime のヘッダー（WorkloadAccessToken, Authorization, Session-Id）を読み取り、コンテキスト変数を設定します。これにより、ゲートウェイ認証とメモリ機能は HTTP パターンと同じように動作します。

agui-langgraph-agent パターンでは、copilotkit ライブラリから LangGraphAGUIAgent を使用します。このパターンは、各リクエストごとにコンパイルされたグラフを新規に構築するため、各呼び出しで呼び出し元にスコープされた MCP ツールが利用可能になります。AgentCore Memory もここではオプトイン方式です：ヘルパー関数は MEMORY_ID が設定されていない場合に None を返すため、メモリのプロビジョニングなしでもこのパターンを実行できます。

patterns/agui-langgraph-agent/agent.py

from copilotkit import CopilotKitMiddleware, LangGraphAGUIAgent

async def build_graph(actor_id: str):

"""Gateway ツールを使用して、新鮮なコンパイル済み LangGraph を構築する。"""

mcp_client = await create_gateway_mcp_client(actor_id)

tools = await mcp_client.get_tools()

tools.append(CODE_INTERPRETER)

return create_agent(

model=MODEL,

tools=tools,

checkpointer=get_memory_saver(), # MEMORY_ID が設定されていない場合は None

middleware=[CopilotKitMiddleware()],

system_prompt=SYSTEM_PROMPT,

)

@app.entrypoint

async def invocations(payload: dict, context: RequestContext):

input_data = RunAgentInput.model_validate(payload)

actor_id = extract_user_id_from_context(context)

graph = await build_graph(actor_id)

agui_agent = LangGraphAGUIAgent(

name="agui_langgraph_agent",

graph=graph,

config={"configurable": {"actor_id": actor_id}},

)

async for event in agui_agent.run(input_data):

yield event.model_dump(mode="json", by_alias=True, exclude_none=True)

両方のパターンは同じ AG-UI イベントを生成します。このプロトコルは、Server-Sent Events (SSE: サーバー送信イベント) 上の型付きイベントストリームを定義しています。例えば、単一のツール呼び出しでは以下のシーケンスが発生します：

data: {"type": "RUN_STARTED", "threadId": "t1", "runId": "r1"}

data: {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"}

data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "Let me check "}

data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "that for you."}

data: {"type": "TEXT_MESSAGE_END", "messageId": "m1"}

data: {"type": "TOOL_CALL_START", "toolCallId": "tc1", "toolCallName": "get_weather"}

data: {"type": "TOOL_CALL_ARGS", "toolCallId": "tc1", "delta": "{\"location\": \"Seattle\"}"}

data: {"type": "TOOL_CALL_END", "toolCallId": "tc1"}

data: {"type": "TOOL_CALL_RESULT", "toolCallId": "tc1", "content": "{\"temp\": 55}"}

data: {"type": "RUN_FINISHED", "threadId": "t1", "runId": "r1"}

フロントエンドのパーサーは、各イベントをフロントエンドアクションにマッピングします：

// frontend/src/lib/agentcore-client/parsers/agui.ts

export const parseAguiChunk: ChunkParser = (line, callback) => {

if (!line.startsWith("data: ")) return;

const json = JSON.parse(line.substring(6).trim());

switch (json.type) {

case "TEXT_MESSAGE_CONTENT":

callback({ type: "text", content: json.delta ?? "" });

break;

case "TOOL_CALL_START":

callback({ type: "tool_use_start", toolUseId: json.toolCallId, name: json.toolCallName });

break;

case "TOOL_CALL_RESULT":

callback({ type: "tool_result", toolUseId: json.toolCallId, result: json.content ?? "" });

break;

case "RUN_FINISHED":

callback({ type: "result", stopReason: "end_turn" });

}

};

HTTP パターンと比較すると、Strands、LangGraph、Claude-agent-sdk のそれぞれは異なるストリーミング形式を処理するために個別のパーサーが必要となります。AG-UI を用いれば、バックエンドフレームワークは抽象化されるため、設定で agui-strands-agent から agui-langgraph-agent に切り替えてもフロントエンドに変更を加える必要はありません。

デプロイするには、infra-cdk/config.yaml でパターンを設定し、CDK を実行します：

backend:

pattern: agui-strands-agent # または agui-langgraph-agent

deployment_type: docker

infra-cdk に移動し、以下のコマンドを実行します。

cdk deploy --require-approval never

python3 ../scripts/deploy-frontend.py

CopilotKit + FAST：生成型 UI、共有状態、および人間を介したループ

ベースとなる FAST フロントエンドは機能的なチャットインターフェースを提供しますが、AG-UI はより豊かなインタラクションをサポートします。具体的には、エージェントがカスタム UI コンポーネントを描画したり、フロントエンドと状態を同期させたり、実行中にユーザー入力を待機したりする機能です。CopilotKit はこれらのパターンに特化して構築された React ライブラリです。CopilotKit チームは、AgentCore 上でこれらの機能をデモンストレーションするために、FAST を基盤とした サンプルアプリケーション を作成しました。このアプリケーションには LangGraph および Strands エージェントパターンが含まれており、デプロイ時にどちらかを選択できます。

生成型 UI は、フロントエンドの制御を重視する側からエージェントの自由度を重視する側まで幅広いスペクトラムにわたります。今回のサンプルは制御が効く側に位置しており、事前に構築された React コンポーネントをフロントエンドが所有し、エージェントはどのコンポーネントを描画するかを選択し、AG-UI イベントを通じてデータを供給します。このスペクトラムのさらに奥では、エージェントが記述的な UI 記述を返してフロントエンドが描画したり、フロントエンドが埋め込む完全な UI サーフェスを返したりすることもあります。AG-UI はこれらすべてをサポートしています。なぜなら、それは UI そのものではなく、イベントと状態ストリームを標準化しているからです。エージェントに任せる自由度が高くなるほど、開発者が負う責任も増えます。オープンエンドのサーフェスにはサンドボックス化や入力検証が必要となるためです。

CopilotKit のサンプルアーキテクチャ。CopilotKit Runtime Lambda は、ブラウザと AgentCore Runtime の間のサーバーサイドの橋渡し役として機能し、AG-UI イベントの解析、生成型 UI ルーティング、認証フォワーディングを処理します。

生成型 UI: エージェントが React コンポーネントを描画する

CopilotKit を使用すると、エージェントはテキストだけでなく、チャット内にカスタム React コンポーネントをインラインで描画できます。フロントエンドでは、AG-UI ツール呼び出しイベントを通じてエージェントが呼び出せるコンポーネントを登録します:

// エージェントが描画できるピートチャートを登録する

useComponent({

name: "pieChart",

description: "データをピートチャートとして表示します。",

parameters: PieChartPropsSchema,

render: PieChart,

});

エージェントが pieChart ツールを呼び出すと、CopilotKit は TOOL_CALL_START および TOOL_CALL_ARGS イベントをインターセプトし、PieChart コンポーネントを会話内に直接描画します。まずエージェントは query_data ツールを呼び出してサンプルのコンマ区切り値 (CSV) ファイルからデータを取得し、その結果をチャートコンポーネントに渡します。

シェアードステート：エージェントと同期する TODO キャンバス

このサンプルには、エージェントと UI の間で双方向に同期される TODO キャンバスが含まれています。ユーザーが「タスクを 3 つ追加して：API の設計、テストの記述、ステージング環境へのデプロイ」と指示すると、エージェントは manage_todos を呼び出し、AG-UI の STATE_SNAPSHOT イベントを通じてキャンバスがリアルタイムで更新されます。また、TODO は UI 上で直接編集することも可能です。Strands パターンによって現在の TODO がシステムプロンプトに注入されるため、エージェントは次のターンで更新されたステートを確認できます：

def state_context_builder(state: dict) -> str:

todos = state.get("todos", [])

if todos:

return f"\nCurrent todos:\n{json.dumps(todos, indent=2)}"

return ""

人間をループに組み込む：エージェントが一時停止して待機する

このサンプルは、実行の途中で一時停止し、タイムピッカーをレンダリングする会議スケジューラーを示しています。ユーザーが時間を選択すると、エージェントはその選択に基づいて処理を続行します：

useHumanInTheLoop({

name: "scheduleTime",

description: "Schedule a meeting with the user.",

parameters: z.object({

reasonForScheduling: z.string(),

meetingDuration: z.number(),

}),

render: ({ respond, status, args }) => (

),

});

これは AG-UI のツール呼び出しフローを通じて機能します。エージェントは scheduleTime に対して TOOL_CALL_START を発行し、CopilotKit がバックエンドツールの実行の代わりにピッカーをレンダリングします。その後、ユーザーからの応答が TOOL_CALL_RESULT として戻ってきます。

CopilotKit サンプルのデプロイ

FAST Samples リポジトリをクローンしてデプロイします：

git clone https://github.com/aws-samples/sample-FAST-applications.git

cd sample-FAST-applications/samples/copilotkit-generative-ui

cp config.yaml.example config.yaml

config.yaml を編集 --- stack_name_base と admin_user_email を設定

./deploy-langgraph.sh # または ./deploy-strands.sh

デプロイスクリプトは、Amazon Cognito ユーザープール、Amazon ECR リポジトリ、AgentCore Runtime（ランタイム）、AgentCore Gateway（ゲートウェイ）、AgentCore Memory（メモリ）、CopilotKit Runtime Lambda と Amazon API Gateway、そして AWS Amplify ホスティングを含むフルスタックをプロビジョニングします。完了したら、最後に表示される Amplify の URL を開いてログインしてください。CopilotKit チャットインターフェースに移動し、デプロイが正常に機能していることを確認するためのいくつかの簡単なチェックを行います：

• サンプルデータから円グラフを作成するようエージェントに依頼します。チャートは会話内にインラインでレンダリングされます。

• TODO キャンバスに 3 つのタスクを追加するよう依頼します。キャンバスがリアルタイムで更新されます。

• 会議のスケジュールを設定するよう依頼します。エージェントは一時的に停止し、時刻選択ウィジェットを表示します。

クリーンアップ

このウォークスルーでは、2 つの別々の s