View a markdown version of this page

AG-UI 协议合约 - 亚马逊基岩 AgentCore
协议实施要求容器要求路径要求身份验证要求错误处理OAuth 身份验证响应

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AG-UI 协议合约

AG-UI 协议合同定义了在 Amazon Bedrock Runtime 中实现代理与用户界面通信的要求。 AgentCore 该合同规定了您的 AG-UI 代理必须实施的技术要求、端点和通信模式。

有关示例代码，请参见在 AgentCore 运行时部署 AG-UI 服务器。

协议实施要求

您的 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 容器-与 AWS 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 类型。

响应格式

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 <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 身份验证

编程访问还支持标准 AWS 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），用于通过 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标头。