View a markdown version of this page

AgentCore ランタイムに AG-UI サーバーをデプロイする - Amazon Bedrock AgentCore

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AgentCore ランタイムに AG-UI サーバーをデプロイする

Amazon Bedrock AgentCore ランタイムを使用すると、AgentCore ランタイムでエージェントユーザーインターフェイス (AG-UI) AgentCore サーバーをデプロイして実行できます。このガイドでは、最初の AG-UI サーバーの作成、テスト、デプロイについて説明します。

このセクションでは、以下を行います。

  • Amazon Bedrock AgentCore が AG-UI をサポートする方法

  • AG-UI サーバーを作成する方法

  • サーバーをローカルでテストする方法

  • サーバーを にデプロイする方法 AWS

  • デプロイされたサーバーを呼び出す方法

AG-UI の詳細については、「AG-UI プロトコル契約」を参照してください。

Amazon Bedrock AgentCore が AG-UI をサポートする方法

Amazon Bedrock AgentCore の AG-UI プロトコルサポートにより、プロキシレイヤーとして機能することで、エージェントのユーザーインターフェイスサーバーとの統合が可能になります。AG-UI 用に設定されている場合、Amazon Bedrock AgentCore はコンテナが HTTP/SSE または WebSocket 接続/wsの/invocationsパスのポート8080でサーバーを実行することを期待します。AG-UI は HTTP プロトコルと同じポートとパスを使用しますが、ランタイムはランタイムに設定されたサーバープロトコルによってそれらを区別します。AgentCore CLI では、 でランタイムの protocolを AGUI agentcore add runtime --protocol AGUIに設定しますagentcore/agentcore.json。

Amazon Bedrock AgentCore は、クライアントと AG-UI コンテナ間のプロキシとして機能します。InvokeAgentRuntime API からのリクエストは、変更なしでコンテナに渡されます。Amazon Bedrock AgentCore は、認証 (SigV4/OAuth 2.0)、セッション分離、スケーリングを処理します。

他のプロトコルとの主な違い:

[ポート]

AG-UI サーバーはポート 8080 で実行されます (HTTP と同じ、MCP の場合は 8000、A2A の場合は 9000)

[Path] (パス)

AG-UI サーバー/invocationsが HTTP/SSE および WebSocket /wsに を使用する (HTTP プロトコルと同じ)

メッセージ形式

ストリーミングには Server-Sent Events (SSE)、双方向通信には WebSocket 経由でイベントストリームを使用します

プロトコルフォーカス

Agent-to-Userインタラクション (ツールの場合は MCP、agent-to-agentの場合は A2A)

認証

SigV4 認証スキームと OAuth 2.0 認証スキームの両方をサポート

詳細については、「https://docs.ag-ui.com/introduction」を参照してください。

AgentCore ランタイムでの AG-UI の使用

このチュートリアルでは、AG-UI サーバーを作成、テスト、デプロイします。

完全な例とフレームワーク固有の実装については、「AG-UI クイックスタートドキュメント」と「AG-UI Dojo」を参照してください。

前提条件

ステップ 1: AG-UI サーバーを作成する

AG-UI は複数のエージェントフレームワークでサポートされています。このチュートリアルでは AWS 、Strands for Python を使用します。

プロジェクトの足場

空のプロジェクトを作成し、Python AG-UI ランタイムを Cognito 認可に登録し、次の例の依存関係を追加します。

agentcore create --name AguiProject --template empty cd AguiProject agentcore add runtime \ --name AguiAgent \ --language python \ --protocol AGUI \ --authorizer-type CUSTOM_JWT \ --authorizer-configuration \ "{\"customJwtAuthorizer\":{\"discoveryUrl\":\"https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration\",\"allowedClients\":[\"$CLIENT_ID\"]}}" \ --request-header-allowlist Authorization cd app/AguiAgent uv init --bare uv add \ "ag-ui-protocol>=0.1.19,<0.2" \ "ag-ui-strands>=0.3,<0.4" \ "aws-opentelemetry-distro~=0.21.0" \ "bedrock-agentcore[strands-agents]>=1.18.1,<2" \ "botocore[crt]~=1.43.0" \ "fastapi>=0.142,<1" \ "strands-agents>=1.15,<2" \ "uvicorn>=0.34.3,<1" cd ../..

CLI は AG-UI ランタイム契約AGENTS.mdで README.mdと を作成しますが、アプリケーションコードは生成しません。別のモデルプロバイダーを使用するには、アプリケーションコードAgentでストランドを設定します。その他のフレームワークについては、「AG-UI フレームワークの統合」を参照してください。

最初の AG-UI サーバーを作成する

次の実装app/AguiAgent/main.pyで を作成します。この例では、AG-UI AWS で Strands を使用します。サーバーはポート をリッスンし8080、AG-UI トラフィック/invocationsを公開し、ヘルスチェック/pingを公開します。AgentCore Runtime では、AG-UI コンテナにこの契約が必要です。

# app/AguiAgent/main.py import os import uvicorn from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse, JSONResponse from ag_ui_strands import StrandsAgent from ag_ui.core import RunAgentInput from ag_ui.encoder import EventEncoder from strands import Agent # Create a simple Strands agent strands_agent = Agent( system_prompt="You are a helpful assistant.", ) # Wrap with AG-UI protocol support agui_agent = StrandsAgent( agent=strands_agent, name="my_agent", description="A helpful assistant", ) # FastAPI server app = FastAPI(telemetry={"auto_configure": False}) @app.post("/invocations") async def invocations(input_data: dict, request: Request): """Main AG-UI endpoint that returns event streams.""" accept_header = request.headers.get("accept") encoder = EventEncoder(accept=accept_header) async def event_generator(): run_input = RunAgentInput(**input_data) async for event in agui_agent.run(run_input): yield encoder.encode(event) return StreamingResponse( event_generator(), media_type=encoder.get_content_type() ) @app.get("/ping") async def ping(): return JSONResponse({"status": "Healthy"}) if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

フレームワーク固有の完全な例については、以下を参照してください。

上記の FastAPI バージョンtelemetry={"auto_configure": False}で を維持します。OpenTelemetry ディストリビューションはエクスポーター設定を所有しています。この設定により、FastAPI が環境駆動型のエクスポーターも設定できなくなります。

コードについて

イベントストリーム

AG-UI はサーバー送信イベント (SSE) を使用して、型付きイベントをクライアントにストリーミングします。

/invocations エンドポイント

HTTP/SSE 通信のプライマリエンドポイント (HTTP プロトコルと同じ)

ポート 8080

AG-UI サーバーは、デフォルトで AgentCore ランタイムでポート 8080 で実行されます。

ステップ 2: AG-UI サーバーをローカルでテストする

ローカル開発環境で AG-UI サーバーを実行してテストします。

AG-UI サーバーを起動する

プロジェクトディレクトリから AG-UI サーバーをローカルで実行します。

agentcore dev

サーバーがポート で実行されていることを示す出力が表示されます8080。

エンドポイントのテスト

適切にフォーマットされた AG-UI リクエストを使用して SSE エンドポイントをテストします。

curl -N -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{ "threadId": "test-123", "runId": "run-456", "state": {}, "messages": [{"role": "user", "content": "Hello, agent!", "id": "msg-1"}], "tools": [], "context": [], "forwardedProps": {} }'

、、 イベントなど、SSE 形式で返される RUN_STARTED AG-UI TEXT_MESSAGE_CONTENT RUN_FINISHEDイベントストリームが表示されます。

ステップ 3: AG-UI サーバーを Bedrock AgentCore ランタイムにデプロイする

AgentCore CLI AWS を使用して AG-UI サーバーを にデプロイします。ステップ 1 でランタイムを追加したときに Cognito 認可を設定しているため、デプロイ前にそれ以上のセットアップは必要ありません。

にデプロイする AWS

エージェントを構築してデプロイします。

agentcore build agentcore deploy

デプロイ後、ランタイム ARN を取得します。

agentcore status --json

ランタイムリソースの arnフィールドには、その ARN が含まれます。

ステップ 4: デプロイされた AG-UI サーバーを呼び出す

デプロイされた Amazon Bedrock AgentCore AG-UI サーバーを呼び出し、イベントストリームとやり取りします。

環境変数をセットアップする

次の環境変数を設定します。

  1. ベアラートークンを環境変数としてエクスポートします。ベアラートークンのセットアップについては、「認証用に Cognito ユーザープールを設定する」を参照してください。

    export BEARER_TOKEN="<BEARER_TOKEN>"
  2. エージェント ARN をエクスポートします。

    export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/AguiProject_default_AguiAgent-xyz123"

AG-UI サーバーを呼び出す

プログラムで AG-UI サーバーを呼び出すには、クライアントに一致する言語を選択します。

例
Python
  1. 必要なパッケージをインストールします。

    pip install httpx httpx-sse

    次に、次のクライアントコードを使用します。

    import asyncio import json import os from urllib.parse import quote from uuid import uuid4 import httpx from httpx_sse import aconnect_sse async def invoke_agui_agent(message: str): agent_arn = os.environ.get('AGENT_ARN') bearer_token = os.environ.get('BEARER_TOKEN') escaped_arn = quote(agent_arn, safe='') url = f"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/{escaped_arn}/invocations?qualifier=DEFAULT" headers = { "Authorization": f"Bearer {bearer_token}", "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": str(uuid4()), } payload = { "threadId": str(uuid4()), "runId": str(uuid4()), "messages": [{"id": str(uuid4()), "role": "user", "content": message}], "state": {}, "tools": [], "context": [], "forwardedProps": {}, } async with httpx.AsyncClient(timeout=300) as client: async with aconnect_sse(client, "POST", url, headers=headers, json=payload) as sse: async for event in sse.aiter_sse(): data = json.loads(event.data) event_type = data.get("type") if event_type == "TEXT_MESSAGE_CONTENT": print(data.get("delta", ""), end="", flush=True) elif event_type == "RUN_ERROR": print(f"Error: {data.get('code')} - {data.get('message')}") asyncio.run(invoke_agui_agent("Hello!"))
TypeScript
  1. 必要なパッケージをインストールします。

    npm install @ag-ui/client

    次に、次のクライアントコードを使用します。

    import { HttpAgent, AgentSubscriber } from "@ag-ui/client"; import { randomUUID } from "crypto"; async function invokeAguiAgent(message: string): Promise<void> { const agentArn = process.env.AGENT_ARN!; const bearerToken = process.env.BEARER_TOKEN!; const escapedArn = encodeURIComponent(agentArn); const agent = new HttpAgent({ url: `https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/${escapedArn}/invocations?qualifier=DEFAULT`, headers: { Authorization: `Bearer ${bearerToken}`, "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": randomUUID(), }, }); agent.messages = [{ id: randomUUID(), role: "user", content: message }]; const subscriber: AgentSubscriber = { onTextMessageContentEvent: ({ event }) => { process.stdout.write(event.delta); }, onRunErrorEvent: ({ event }) => { console.error(`Error: ${event.code ?? "RUN_ERROR"} - ${event.message}`); }, }; await agent.runAgent({}, subscriber); } void invokeAguiAgent("Hello!");

完全な UI アプリケーションの構築については、CopilotKit」または「AG-UI TypeScript client SDK」を参照してください。

付録

認証用に Cognito ユーザープールを設定する

Cognito のセットアップ手順の詳細については、「認証用に Cognito ユーザープールを設定する」を参照してください。AG-UI サーバーのセットアッププロセスは同じです。

トラブルシューティング

AG-UI-specific一般的な問題

以下は、発生する可能性のある一般的な問題です。

ポートの競合

AG-UI サーバーは AgentCore ランタイム環境のポート 8080 で実行する必要があります

認可方法の不一致

リクエストで、エージェントが設定されたのと同じ認証方法 (OAuth または SigV4) を使用していることを確認します。

イベント形式のエラー

イベントが AG-UI プロトコル仕様に従っていることを確認します。「AG-UI イベントのドキュメント」を参照してください。