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

  • 連接埠：- AG-UI 8080 代理程式通訊的標準連接埠 （與 HTTP 通訊協定相同）

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

路徑需求

/invocations - POST

用途

接收使用者請求並將回應串流為伺服器傳送事件 (SSE)

使用案例

調用端點有幾個主要用途：

  • 串流聊天回應

  • 客服人員狀態和思考步驟

  • 工具呼叫和結果

要求格式

Amazon Bedrock AgentCore 會將請求承載直接傳遞到您的容器，無需驗證。若要符合 AG-UI-compliant，您的請求應遵循 RunAgentInput 格式。您的容器實作會決定需要哪些欄位，以及如何處理驗證錯誤。

AG-UI-compliant代理程式預期會有 RunAgentInput JSON 承載。範例：

{
  "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 開發套件，則會為您處理 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 身分驗證。

錯誤處理

AG-UI 會將每個錯誤序列化為 SSE RUN_ERROR事件 (Content-Type: text/event-stream)，無論錯誤發生在串流之前或期間。類別僅在事件隨附的 HTTP 狀態碼中不同：

  • 連線層級錯誤 ：在請求到達您的容器之前發生 （身分驗證、授權、驗證、限流、工作階段衝突）。RUN_ERROR 事件會傳回錯誤的實際 HTTP 狀態碼 （例如 401、403 或 409)。

  • 執行時間錯誤 ：串流啟動後，在代理程式執行期間發生。只有 AGENT_ERROR 屬於此類別。其RUN_ERROR事件會傳回 HTTP 200，因為串流已開始。

下表會將每個執行時間例外狀況映射至其 AG-UI SSE 錯誤碼、HTTP 狀態碼和訊息。有些例外狀況會共用 SSE 錯誤碼，但會傳回不同的訊息，因此它們會列為個別的資料列。

SSE 錯誤碼 執行時間例外狀況 HTTP 錯誤代碼 錯誤訊息

UNAUTHORIZED

UnauthorizedException

401

需要身分驗證或無效的登入資料

ACCESS_DENIED

AccessDeniedException

403

請求操作的許可不足

VALIDATION_ERROR

ValidationException

400

無效的請求資料或參數

RATE_LIMIT_EXCEEDED

ThrottlingException

429

來自用戶端的請求過多

SESSION_BUSY

ConflictException

409

資源衝突 - 資源已存在

SESSION_BUSY

RetryableConflictException

409

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

SERVICE_QUOTA_EXCEEDED

ServiceQuotaExceededException

429

超過服務配額

AGENT_ERROR

RuntimeClientError

200

代理程式程式碼在執行期間失敗 – 檢查您的 CloudWatch 日誌

INTERNAL_ERROR

任何其他例外狀況

500

處理請求時發生內部錯誤

ConflictException 和 RetryableConflictException都使用 SESSION_BUSY SSE 錯誤碼 (HTTP 409)，但會依其訊息區分。當服務佈建或銷毀該工作階段時，當第二個操作到達工作階段時，服務會傳回 RetryableConflictException(Session operation in progress, please retry)。這是暫時性且可重試 — 以短指數退避重試，因為 AG-UI 用戶端不會自動重試。

範例執行時間錯誤 （代理程式失敗）：

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

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

工作階段忙碌錯誤範例 （可重試衝突）：

HTTP/1.1 409 Conflict
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"SESSION_BUSY","message":"Session operation in progress, please retry"}

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: 12345678-1234-1234-1234-123456789012

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

SigV4-configured代理程式傳回 HTTP 403 時發生錯誤ACCESS_DENIED，且不包含WWW-Authenticate標頭。