HTTP プロトコル契約

エージェントアプリケーションで HTTP プロトコルを実装するための要件を理解します。HTTP プロトコルを使用して、従来のリクエスト/レスポンスパターン用の直接 REST API エンドポイントと、リアルタイムの双方向ストリーミング接続用の WebSocket エンドポイントを作成します。

コード例については、AgentCore CLI の開始方法」を参照してください。

コンテナの要件

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

パスの要件

/呼び出し - POST

これは、JSON 入力と JSON/SSE 出力を使用する主要なエージェントインタラクションエンドポイントです。

目的

ユーザーまたはアプリケーションからの受信リクエストを受信し、エージェントのビジネスロジックを通じて処理します

ユースケース

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

リクエスト形式の例

Content-Type: application/json

{
  "prompt": "What's the weather today?"
}

レスポンス形式

エージェントは、ユースケースに応じて、次のいずれかの形式で応答できます。

JSON レスポンス (非ストリーミング)

目的

迅速に処理できるリクエストに対する完全なレスポンスを提供します

ユースケース

JSON レスポンスは、以下に最適です。

JSON レスポンス形式の例

Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}

SSE レスポンス (ストリーミング)

サーバー送信イベント (SSE) を使用すると、リアルタイムのストリーミングレスポンスを配信できます。詳細については、「サーバー送信イベントの仕様」を参照してください。

目的

長時間実行されるオペレーションの増分レスポンス配信とユーザーエクスペリエンスの向上を実現

ユースケース

SSE レスポンスは、以下に最適です。

SSE レスポンス形式の例

Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}

/ws - WebSocket (オプション)

これは、リアルタイムの双方向通信のための主要な WebSocket 接続エンドポイントです。

目的

WebSocket のアップグレードリクエストを受け入れ、ストリーミングエージェントとのやり取りのための永続的な接続を維持します

ユースケース

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

接続の確立

WebSocket 接続は、HTTP アップグレードリクエストで始まります。

HTTP アップグレードリクエストの例

GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid

WebSocket アップグレードレスポンスの例

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

メッセージ処理の要件

WebSocket エンドポイントは以下を処理する必要があります。

メッセージ形式

テキストメッセージ

JSON 形式 (推奨)

目的

エージェントとのやり取りのための構造化データ交換

メッセージの例

{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}

レスポンスの例

{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}

プレーンテキスト形式

目的

シンプルなテキストベースの通信

例

Hello, can you help me with this question?

バイナリメッセージ

目的

イメージ、オーディオ、その他のバイナリ形式などの非テキストデータのサポート

ユースケース

バイナリメッセージは、いくつかのシナリオをサポートします。

要件の処理

バイナリメッセージ処理には以下が必要です。

接続ライフサイクル

接続の確立

メッセージ交換

/ping - GET

目的

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

ユースケース

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

レスポンスの形式

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

エージェントがバックグラウンドタスクを処理する必要がある場合は、 /pingステータスで指定できます。ping ステータスが HealthyBusy の場合、ランタイムセッションはアクティブと見なされます。

Ping レスポンス形式の例

{
  "status": "<status_value>"
}

OAuth 認証レスポンス

OAuth 設定のエージェントは、RFC 6749 (OAuth 2.0) 認証標準に従います。認証がない場合、サービスは WWW-Authenticate ヘッダー (RFC 7235 ごと) を含む 401 Unauthorized レスポンスを返します。これにより、クライアントは GetRuntimeProtectedResourceMetadata API を通じて認可サーバーエンドポイントを検出できます。

401 Unauthorized

認可ヘッダーがない場合に返されます。

WWW-Authenticate ヘッダーが含まれます。

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"