翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
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 クイックスタートドキュメント
トピック
前提条件
-
Python 3.12 以降がインストールされている
-
AgentCore CLI がインストールされ、設定されています。手順については、AgentCore CLI の開始方法」を参照してください。
-
適切なアクセス許可とローカル認証情報が設定されている AWS アカウント
-
AG-UI プロトコルとイベントベースのagent-to-user通信の概念を理解する
-
「認証用に Cognito ユーザープールを設定する」の説明に従って設定された Cognito ユーザープール。プロジェクトを作成する前に
REGION、そのセットアップCLIENT_IDからPOOL_ID、、 をエクスポートします。
ステップ 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 サーバーを呼び出し、イベントストリームとやり取りします。
環境変数をセットアップする
次の環境変数を設定します。
-
ベアラートークンを環境変数としてエクスポートします。ベアラートークンのセットアップについては、「認証用に Cognito ユーザープールを設定する」を参照してください。
export BEARER_TOKEN="<BEARER_TOKEN>" -
エージェント ARN をエクスポートします。
export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/AguiProject_default_AguiAgent-xyz123"
AG-UI サーバーを呼び出す
プログラムで AG-UI サーバーを呼び出すには、クライアントに一致する言語を選択します。
例
完全な UI アプリケーションの構築については、CopilotKit
付録
認証用に Cognito ユーザープールを設定する
Cognito のセットアップ手順の詳細については、「認証用に Cognito ユーザープールを設定する」を参照してください。AG-UI サーバーのセットアッププロセスは同じです。
トラブルシューティング
AG-UI-specific一般的な問題
以下は、発生する可能性のある一般的な問題です。
- ポートの競合
-
AG-UI サーバーは AgentCore ランタイム環境のポート 8080 で実行する必要があります
- 認可方法の不一致
-
リクエストで、エージェントが設定されたのと同じ認証方法 (OAuth または SigV4) を使用していることを確認します。
- イベント形式のエラー
-
イベントが AG-UI プロトコル仕様に従っていることを確認します。「AG-UI イベントのドキュメント
」を参照してください。