本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AG-UI 协议合约
AG-UI 协议合同定义了在 Amazon Bedrock Runtime 中实现代理与用户界面通信的要求。 AgentCore 该合同规定了您的 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)
## 协议实施要求
您的 AG-UI 代理必须实现以下特定的协议要求：
+ **传输**： Server-Sent 事件 (SSE) 或 WebSocket -SSE 提供从服务器到客户端的单向流式传输，同时 WebSocket 支持双向实时通信
+ **会话管理**：平台自动添加会话隔离`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`标头
## 容器要求
您的 AG-UI 代理必须部署为符合以下规格的容器化应用程序：
+ **主机**：`0.0.0.0`
+ **端口**：`8080`- AG-UI 代理通信的标准端口（与 HTTP 协议相同）
+ **平台**：ARM64 容器-与 Amazon Amazon Bedrock AgentCore 运行时环境兼容所必需的
## 路径要求
### /invocations-POST
#### 用途
接收用户请求并将响应作为 Server-Sent 事件 (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 类型](https://docs.ag-ui.com/sdk/js/core/types)。
#### 响应格式
AG-UI 代理使用 SSE-formatted 事件流进行响应：
```
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 端点有几个关键用途：
+ Real-time 对话接口
+ 用户中断的交互式代理会话
+ Multi-turn 具有持续连接的对话
### /ping-获取
#### 用途
验证您的 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 SDK，则会为您处理 ping 响应。
## 身份验证要求
AG-UI 代理支持多种身份验证机制:
### OAuth 2.0 持有者代币
要进行 AG-UI 客户端身份验证，请在请求标头中包含不记名令牌：
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### SigV4 身份验证
编程访问还支持标准 Amazon SigV4 身份验证。
## 错误处理
AG-UI 将每个错误序列化为 SSE `RUN_ERROR` 事件 (`Content-Type: text/event-stream`)，无论错误发生在流式传输之前还是期间。这些类别的区别仅在于事件附带的 HTTP 状态码：
+ **Connection-level 错误**：在请求到达您的容器之前发生（身份验证、授权、验证、限制、会话冲突）。该`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-configured 代理使用标准 HTTP 状态代码返回身份验证错误。该响应包含一个`WWW-Authenticate`标头（根据 [ RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)），用于通过 API 发现 OAuth。 GetRuntimeProtectedResourceMetadata
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`标头。