View a markdown version of this page

HTTP 通訊協定合約 - Amazon Bedrock AgentCore
容器需求路徑需求錯誤處理OAuth 身分驗證回應

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

HTTP 通訊協定合約

了解在您的代理程式應用程式中實作 HTTP 通訊協定的要求。使用 HTTP 通訊協定為傳統請求/回應模式建立直接 REST API 端點，並為即時雙向串流連線建立 WebSocket 端點。

注意

HTTP /invocations ( ) 和 WebSocket ( /ws ) 端點都可以使用連接埠 8080 部署在相同的容器上，讓單一代理程式實作同時支援傳統 API 互動和即時雙向串流。

如需範例程式碼，請參閱 AgentCore CLI 入門。

容器需求

您的代理程式必須部署為符合下列規格的容器化應用程式：

  • 主機 ： 0.0.0.0

  • 連接埠：8080- HTTP 型代理程式通訊的標準連接埠

  • 平台 ：ARM64 容器 - 與 AgentCore 執行期環境相容時需要

路徑需求

/invocations - 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) 可讓您提供即時串流回應。如需詳細資訊，請參閱伺服器傳送事件規格。

用途

為長時間執行的操作啟用增量回應交付，並改善使用者體驗

使用案例

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 升級請求

  2. 升級回應：客服人員接受並傳回 101 切換通訊協定

  3. WebSocket Active：雙向通訊開始

  4. 工作階段繫結：將連線與工作階段識別符建立關聯

訊息交換

  1. 持續迴圈 ：實作訊息接聽迴圈

  2. 訊息處理 ：以非同步方式處理傳入的訊息

  3. 回應產生：傳送適當的回應

  4. 錯誤處理 ：管理例外狀況和連線問題

/ping - GET

用途

驗證您的代理程式是否正常運作並準備好處理請求

使用案例

/ping 端點有幾個主要用途：

  • 偵測和修復問題的服務監控

  • 透過 AWS受管基礎設施的自動化復原

回應格式

傳回狀態碼，指出代理程式的運作狀態：

  • Content-Type： application/json

  • HTTP 狀態碼：200適用於運作狀態不良、適當的錯誤碼

如果您的客服人員需要處理背景任務，您可以使用 /ping 狀態來表示。如果 ping 狀態為 HealthyBusy ，則執行階段工作階段會被視為作用中。

Ping 回應格式範例 

{
  "status": "<status_value>"
}
狀態 （必要）

Healthy - 系統已準備好接受新工作

HealthyBusy - 系統可運作，但目前正忙於非同步任務。當狀態為 時HealthyBusy，執行階段工作階段會被視為作用中並保持運作狀態。

time_of_last_update （選用）

status 取消上次變更時的時間戳記 （以秒為單位）。僅在實際狀態變更時設定。

警告

請勿在每個 ping 上time_of_last_update將 設定為目前時間。在每個 ping 上推進的時間戳記會發出持續狀態變更，防止閒置工作階段逾時永遠觸發 — 然後工作階段會保留到 ，MaxLifetime並可以耗盡工作階段配額。如果您省略 欄位，平台會自行追蹤狀態變更。如果您使用 Bedrock AgentCore 開發套件，則會為您處理 ping 回應。

錯誤處理

與 A2A、MCP 和 AG-UI 通訊協定不同，HTTP 通訊協定不會在通訊協定特定的信封中包裝錯誤。服務會以原生 HTTP 回應的形式直接傳回錯誤：HTTP 狀態碼會反映例外狀況，而x-amzn-ErrorType回應標頭會攜帶例外狀況名稱。下表列出您可以收到的例外狀況。

HTTP 錯誤代碼 執行時間例外狀況 (x-amzn-ErrorType) 說明

400

ValidationException

無效的請求資料或參數

401

UnauthorizedException

需要身分驗證或無效的登入資料 (OAuth 設定的代理程式）

402

ServiceQuotaExceededException

請求將超過服務配額

403

AccessDeniedException

請求操作的許可不足

404

ResourceNotFoundException

請求的資源不存在

409

ConflictException

資源衝突 - 資源已存在

409

RetryableConflictException

工作階段操作進行中，請重試

424

RuntimeClientError

代理程式的容器傳回 4xx 或 5xx 錯誤 - 檢查您的 CloudWatch 日誌

429

ThrottlingException

請求太多 - 超過請求速率限制

500

InternalServerException

處理請求時發生非預期的錯誤

ConflictException 和 RetryableConflictException都會傳回 HTTP 409。x-amzn-ErrorType 標頭和訊息會區分它們。當第二個操作以服務佈建或銷毀的工作階段為目標時，服務會傳回 RetryableConflictException(Session operation in progress, please retry)。此條件為暫時性且可重試。以短指數退避重試。啟用預設重試時 AWS SDKs 會自動重試此例外狀況。如果您直接呼叫 API 而沒有 AWS SDK，則必須自行重試。

注意

ServiceQuotaExceededException 在此原生 HTTP 表面上傳回 HTTP 402。在 A2A 通訊協定上，它會傳回 HTTP 429，與限流相同的 HTTP 狀態。在 MCP 通訊協定上，它會共用調節 JSON-RPC 錯誤代碼 (-32003)，但傳回 HTTP 200。在 AG-UI 上，它使用不同的 SERVICE_QUOTA_EXCEEDED SSE 程式碼並傳回 HTTP 429。

OAuth 身分驗證回應

OAuth 設定的代理程式遵循 RFC 6749 (OAuth 2.0) 身分驗證標準。缺少身分驗證時，服務會傳回具有 WWW-Authenticate 標頭的 401 未授權回應 （根據 RFC 7235)，讓用戶端能夠透過 GetRuntimeProtectedResourceMetadata API 探索授權伺服器端點。

401 (未經授權)

缺少授權標頭時傳回。

包含 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代理程式傳回 HTTP 403 時發生錯誤ACCESS_DENIED，且不包含WWW-Authenticate標頭。