# HTTP プロトコル契約
エージェントアプリケーションで HTTP プロトコルを実装するための要件を理解します。HTTP プロトコルを使用して、従来のリクエスト/レスポンスパターン用の直接 REST API エンドポイントと、リアルタイムの双方向ストリーミング接続用の WebSocket エンドポイントを作成します。
**注記**
HTTP ( ) `/invocations` エンドポイントと WebSocket ( ) `/ws` エンドポイントの両方をポート 8080 を使用して同じコンテナにデプロイできるため、単一のエージェントの実装で従来の API インタラクションとリアルタイムの双方向ストリーミングの両方をサポートできます。
コード例については、[AgentCore CLI の開始方法](runtime-get-started-cli.md)」を参照してください。
**Topics**
+ [コンテナの要件](#container-requirements-http)
+ [パスの要件](#path-requirements-http)
+ [OAuth 認証レスポンス](#http-oauth-authentication-responses)
## コンテナの要件
エージェントは、以下の仕様を満たすコンテナ化されたアプリケーションとしてデプロイする必要があります。
+ **ホスト:** `0.0.0.0`
+ **ポート** : `8080` - HTTP ベースのエージェント通信用の標準ポート
+ **プラットフォーム** : ARM64 コンテナ - AgentCore ランタイム環境との互換性のために必要です
## パスの要件
### /呼び出し - POST
これは、JSON 入力と JSON/SSE 出力を使用する主要なエージェントインタラクションエンドポイントです。
**目的**
ユーザーまたはアプリケーションからの受信リクエストを受信し、エージェントのビジネスロジックを通じて処理します
**ユースケース**
`/invocations` エンドポイントには、いくつかの重要な目的があります。
+ ユーザーとの直接的なやり取りと会話
+ 外部システムとの API 統合
+ 複数のリクエストのバッチ処理
+ 長時間実行されるオペレーションのリアルタイムストリーミングレスポンス
**リクエスト形式の例**
```
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) を使用すると、リアルタイムのストリーミングレスポンスを配信できます。詳細については、[「サーバー送信イベントの](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events)仕様」を参照してください。
**目的**
長時間実行されるオペレーションの増分レスポンス配信とユーザーエクスペリエンスの向上を実現
**ユースケース**
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 エンドポイントは以下を処理する必要があります。
+ **接続の承諾**: を呼び出し`await websocket.accept()`て接続を確立します
+ **メッセージ受信**: アプリケーション要件に基づいてテキストまたはバイナリメッセージタイプをサポートします。
+ **メッセージ処理**: エージェントのビジネスロジックに従って受信メッセージを処理します。
+ **レスポンスの送信**: `send_text()`または を使用して適切なレスポンスを送信する `send_bytes()`
+ **接続ライフサイクル**: 接続の確立、メンテナンス、終了を管理する
#### メッセージ形式
##### テキストメッセージ
##### 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?
```
##### バイナリメッセージ
**目的**
イメージ、オーディオ、その他のバイナリ形式などの非テキストデータのサポート
**ユースケース**
バイナリメッセージは、いくつかのシナリオをサポートします。
+ マルチモーダルエージェントインタラクション
+ ファイルのアップロードとダウンロード
+ 圧縮データ転送
+ バイナリプロトコルデータ
**要件の処理**
バイナリメッセージ処理には以下が必要です。
+ `receive_bytes()` および `send_bytes()`メソッドを使用する
+ 適切なバイナリデータ処理を実装する
+ メッセージサイズの制限を考慮する
#### 接続ライフサイクル
##### 接続の確立
1. **HTTP ハンドシェイク**: クライアントが WebSocket アップグレードリクエストを送信する
1. **アップグレードレスポンス**: エージェントが 101 の切り替えプロトコルを受け入れて返す
1. **WebSocket アクティブ**: 双方向通信開始
1. **セッションバインディング**: 接続をセッション識別子に関連付ける
##### メッセージ交換
1. **連続ループ**: メッセージリッスンループを実装する
1. **メッセージ処理** : 受信メッセージを非同期的に処理する
1. **レスポンスの生成**: 適切なレスポンスを送信する
1. **エラー処理**: 例外と接続の問題を管理する
### /ping - GET
**目的**
エージェントが動作していて、リクエストを処理する準備ができていることを確認します。
**ユースケース**
`/ping` エンドポイントには、いくつかの重要な目的があります。
+ 問題を検出して修正するためのサービスモニタリング
+ AWSのマネージドインフラストラクチャによる自動復旧
**レスポンスの形式**
エージェントの状態を示すステータスコードを返します。
+ **Content-Type:** `application/json`
+ **HTTP ステータスコード**: 異常状態の正常で適切なエラーコード`200`の場合
エージェントがバックグラウンドタスクを処理する必要がある場合は、 `/ping`ステータスで指定できます。ping ステータスが `HealthyBusy` の場合、ランタイムセッションはアクティブと見なされます。
**Ping レスポンス形式の例**
```
{
"status": ""
}
```
**ステータス** (必須)
`Healthy` - システムは新しい作業を受け入れる準備ができています
`HealthyBusy` - システムは動作していますが、現在非同期タスクでビジー状態です。ステータスが の間`HealthyBusy`、ランタイムセッションはアクティブと見なされ、存続したままになります。
**time\_of\_last\_update** (オプション)
`status` 最後の が変更された時刻の Unix タイムスタンプ (秒単位）。実際のステータス変更でのみ設定します。
すべての ping で現在の時刻`time_of_last_update`に設定しないでください。すべての ping で進行するタイムスタンプは、継続的なステータス変更を示します。これにより、アイドル状態のセッションタイムアウトが発砲されるのを防ぐことができます。その後、セッションは まで保持`MaxLifetime`され、セッションクォータが枯渇する可能性があります。フィールドを省略すると、プラットフォームはステータスの変更を単独で追跡します。Bedrock AgentCore SDK を使用すると、ping レスポンスが自動的に処理されます。
## OAuth 認証レスポンス
OAuth 設定のエージェントは、[RFC 6749 (OAuth 2.0) ](https://datatracker.ietf.org/doc/html/rfc6749)認証標準に従います。認証がない場合、サービスは WWW-Authenticate ヘッダー ([RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ごと) を含む 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}"
```
**注記**
SigV4-configuredのエージェントは`ACCESS_DENIED`エラーで HTTP 403 を返し、`WWW-Authenticate`ヘッダーは含まれません。