View a markdown version of this page

AG-UI プロトコル契約 - Amazon Bedrock AgentCore
プロトコル実装要件コンテナの要件パスの要件認証要件エラー処理OAuth 認証レスポンス

AG-UI プロトコル契約

AG-UI プロトコル契約では、Amazon Bedrock AgentCore ランタイムでagent-to-userインターフェイス通信を実装するための要件を定義します。この契約では、AG-UI エージェントが実装する必要がある技術要件、エンドポイント、および通信パターンを指定します。

コード例については、AgentCore ランタイムに AG-UI サーバーをデプロイする」を参照してください。

プロトコル実装要件

AG-UI エージェントは、以下の特定のプロトコル要件を実装する必要があります。

  • トランスポート : サーバー送信イベント (SSE) または WebSocket - SSE はサーバーからクライアントへの一方向ストリーミングを提供し、WebSocket は双方向リアルタイム通信を有効にします

  • セッション管理: プラットフォームはセッション分離のX-Amzn-Bedrock-AgentCore-Runtime-Session-Idヘッダーを自動的に追加します

コンテナの要件

AG-UI エージェントは、以下の仕様を満たすコンテナ化されたアプリケーションとしてデプロイする必要があります。

  • ホスト: 0.0.0.0

  • ポート : 8080 - AG-UI エージェント通信用の標準ポート (HTTP プロトコルと同じ)

  • プラットフォーム : ARM64 コンテナ - AWS Amazon Bedrock AgentCore ランタイム環境との互換性のために必要です

パスの要件

/呼び出し - POST

目的

ユーザーリクエストを受信し、サーバー送信イベント (SSE) としてレスポンスをストリーミングします

ユースケース

呼び出しエンドポイントには、いくつかの重要な目的があります。

  • チャットレスポンスのストリーミング

  • エージェントのステータスと思考ステップ

  • ツールの呼び出しと結果

リクエストの形式

Amazon Bedrock AgentCore は、検証なしでリクエストペイロードをコンテナに直接渡します。AG-UI-compliantするには、リクエストが RunAgentInput形式に従う必要があります。コンテナの実装によって、必須のフィールドと検証エラーの処理方法が決まります。

AG-UI-compliantのエージェントは JSON RunAgentInput ペイロードを想定しています。例:

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
  "tools": [],
  "context": [],
  "state": {},
  "forwardedProps": {}
}

RunAgentInput スキーマとメッセージ形式の詳細については、「AG-UI タイプ」を参照してください。

レスポンスの形式

AG-UI エージェントは SSE 形式のイベントストリームで応答します。

Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-789","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-789","delta":"Processing your request"}

data: {"type":"TOOL_CALL_START","toolCallId":"tool-001","toolCallName":"search","parentMessageId":"msg-789"}

data: {"type":"TOOL_CALL_RESULT","messageId":"msg-789","toolCallId":"tool-001","content":"Search completed"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-789"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}

/ws - WebSocket

目的

クライアントとエージェント間の双方向のリアルタイム通信を提供します

ユースケース

WebSocket エンドポイントには、いくつかの重要な目的があります。

  • リアルタイムの会話型インターフェイス

  • ユーザー割り込みを使用したインタラクティブなエージェントセッション

  • 永続的な接続によるマルチターン会話

/ping - GET

目的

AG-UI エージェントが動作しており、リクエストを処理する準備ができていることを確認します。

レスポンスの形式

エージェントの状態を示すステータスコードを返します。

  • Content-Type: application/json

  • HTTP ステータスコード: 異常状態の正常で適切なエラーコード200の場合

{
  "status": "Healthy"
}

status は必須であり、 Healthy または のいずれかですHealthyBusy。ステータスが の間HealthyBusy、ランタイムセッションは維持されます。

オプションの time_of_last_updateフィールド (Unix タイムスタンプを秒単位) を含めて、status最後に変更された日時をレポートできます。

警告

すべての ping で現在の時刻time_of_last_updateに設定しないでください。すべての ping で進行するタイムスタンプは、継続的なステータス変更を示します。これにより、アイドル状態のセッションタイムアウトが発砲されるのを防ぐことができます。その後、セッションは まで保持MaxLifetimeされ、セッションクォータが枯渇する可能性があります。フィールドを省略すると、プラットフォームはステータスの変更を単独で追跡します。Bedrock AgentCore SDK を使用すると、ping レスポンスが自動的に処理されます。

認証要件

AG-UI エージェントは、複数の認証メカニズムをサポートしています。

OAuth 2.0 ベアラートークン

AG-UI クライアント認証の場合、リクエストヘッダーにベアラートークンを含めます。

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 認証

Standard AWS SigV4 認証は、プログラムによるアクセスでもサポートされています。

エラー処理

エラーは、発生したタイミングに基づいて 2 つのカテゴリに分類されます。

  • 接続レベルのエラー: リクエストがコンテナに到達する前に発生します (認証、検証、スロットリング）。これらは標準の HTTP ステータスコードを返します。

  • ランタイムエラー: ストリームの開始後にエージェントの実行中に発生します。これらは、HTTP ステータスコードではなく SSE ストリームのRUN_ERRORイベントとして表示されます。

AG-UI エラーコード HTTP ステータス 説明

UNAUTHORIZED

401

認証が必須または無効な認証情報

ACCESS_DENIED

403

リクエストされたオペレーションのアクセス許可が不十分

VALIDATION_ERROR

400

無効なリクエストデータまたはパラメータ

RATE_LIMIT_EXCEEDED

429

クライアントからのリクエストが多すぎる

AGENT_ERROR

200

実行中にエージェントコードが失敗 – CloudWatch ログを確認する

ランタイムエラーの例 (エージェントの失敗):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"AGENT_ERROR","message":"Agent execution failed"}

OAuth 認証レスポンス

OAuth 設定のエージェントは、標準の HTTP ステータスコードで認証エラーを返します。レスポンスには、GetRuntimeProtectedResourceMetadata API を介した OAuth 検出用のWWW-Authenticateヘッダー (RFC 7235 ごと) が含まれます。

OAuth 認証エラーの例:

HTTP/1.1 401 Unauthorized
Content-Type: text/event-stream
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

SigV4-configuredのエージェントはACCESS_DENIEDエラーで HTTP 403 を返し、WWW-Authenticateヘッダーは含まれません。