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 回應。

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標頭。