# AG-UI 通訊協定合約
<a name="runtime-agui-protocol-contract"></a>

AG-UI 通訊協定合約定義在 Amazon Bedrock AgentCore 執行期中實作agent-to-user界面通訊的需求。本合約會指定 AG-UI 代理程式必須實作的技術需求、端點和通訊模式。

如需程式碼範例，請參閱在 [ AgentCore 執行期中部署 AG-UI 伺服器](runtime-agui.md)。

**Topics**
+ [通訊協定實作要求](#agui-protocol-implementation-requirements)
+ [容器需求](#agui-container-requirements)
+ [路徑需求](#agui-path-requirements)
+ [身分驗證要求](#agui-authentication-requirements)
+ [錯誤處理](#agui-error-handling)
+ [OAuth 身分驗證回應](#agui-oauth-authentication-responses)

## 通訊協定實作要求
<a name="agui-protocol-implementation-requirements"></a>

您的 AG-UI 代理程式必須實作這些特定的通訊協定需求：
+  **傳輸** ：伺服器傳送事件 (SSE) 或 WebSocket - SSE 提供從伺服器到用戶端的單向串流，而 WebSocket 則啟用雙向即時通訊
+  **工作階段管理**：平台會自動新增工作階段隔離的`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`標頭

## 容器需求
<a name="agui-container-requirements"></a>

您的 AG-UI 代理程式必須部署為符合下列規格的容器化應用程式：
+  **主機** ： `0.0.0.0`
+  **連接埠**：- AG-UI `8080` 代理程式通訊的標準連接埠 （與 HTTP 通訊協定相同）
+  **平台** ：ARM64 容器 - 與 Amazon Bedrock AgentCore AWS 執行期環境相容時需要

## 路徑需求
<a name="agui-path-requirements"></a>

### /invocations - POST
<a name="agui-invocations-endpoint"></a>

#### 用途
<a name="agui-invocations-purpose"></a>

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

#### 使用案例
<a name="agui-invocations-use-cases"></a>

調用端點有幾個主要用途：
+ 串流聊天回應
+ 客服人員狀態和思考步驟
+ 工具呼叫和結果

#### 要求格式
<a name="agui-invocations-request-format"></a>

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 類型](https://docs.ag-ui.com/sdk/js/core/types)。

#### 回應格式
<a name="agui-invocations-response-format"></a>

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
<a name="agui-ws-endpoint"></a>

#### 用途
<a name="agui-ws-purpose"></a>

提供用戶端和客服人員之間的雙向即時通訊

#### 使用案例
<a name="agui-ws-use-cases"></a>

WebSocket 端點有幾個主要用途：
+ 即時對話界面
+ 使用者中斷的互動式代理程式工作階段
+ 具有持久性連線的多轉對話

### /ping - GET
<a name="agui-ping-endpoint"></a>

#### 用途
<a name="agui-ping-purpose"></a>

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

#### 回應格式
<a name="agui-ping-response-format"></a>

傳回狀態碼，指出代理程式的運作狀態：
+  **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 回應。

## 身分驗證要求
<a name="agui-authentication-requirements"></a>

AG-UI 代理程式支援多個身分驗證機制：

### OAuth 2.0 承載權杖
<a name="agui-oauth-bearer-tokens"></a>

對於 AG-UI 用戶端身分驗證，請在請求標頭中包含承載字符：

```
Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>
```

### SigV4 身分驗證
<a name="agui-sigv4-authentication"></a>

程式設計存取也支援 Standard AWS SigV4 身分驗證。

## 錯誤處理
<a name="agui-error-handling"></a>

錯誤根據發生的時間分為兩個類別：
+  **連線層級錯誤** ：在請求到達您的容器 （身分驗證、驗證、限流） 之前發生。這些會傳回標準 HTTP 狀態碼。
+  **執行時間錯誤** ：串流啟動後，在代理程式執行期間發生。這些會在 SSE 串流中顯示為`RUN_ERROR`事件，而非 HTTP 狀態碼。


| AG-UI 錯誤代碼 | HTTP 狀態 | 說明 | 
| --- | --- | --- | 
|  `UNAUTHORIZED`  | 401 | 需要身分驗證或無效的登入資料 | 
|  `ACCESS_DENIED`  | 403 | 請求操作的許可不足 | 
|  `VALIDATION_ERROR`  | 400 | 無效的請求資料或參數 | 
|  `RATE_LIMIT_EXCEEDED`  | 429 | 來自用戶端的請求過多 | 
|  `AGENT_ERROR`  | 200 | 代理程式程式碼在執行期間失敗 – 檢查您的 CloudWatch 日誌 | 

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

```
HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

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

## OAuth 身分驗證回應
<a name="agui-oauth-authentication-responses"></a>

OAuth 設定的代理程式會傳回具有標準 HTTP 狀態碼的身分驗證錯誤。回應包含透過 GetRuntimeProtectedResourceMetadata API 進行 OAuth 探索的`WWW-Authenticate`標頭 （根據 [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235))。

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: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

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

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