View a markdown version of this page

AG-UI 协议合同 - Amazon Bedrock 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 亚马逊 Bedrock AgentCore 运行时环境兼容

路径要求

/invocations-POST

用途

接收用户请求并将响应作为 Server-Sent 事件 (SSE) 进行流式传输

使用案例

调用端点有几个关键用途：

  • 直播聊天回复

  • 代理状态和思考步骤

  • 工具调用和结果

请求格式

Amazon Bedrock 无需验证即可将请求有效载荷直接 AgentCore 传递到您的容器。为此 AG-UI-compliant，您的请求应遵循RunAgentInput格式。您的容器实现决定了哪些字段是必填字段以及如何处理验证错误。

AG-UI-compliant 代理需要一个 J RunAgentInput SON 有效负载。示例：

{
  "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-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 SDK，ping 响应会由你处理。

身份验证要求

AG-UI 代理支持多种身份验证机制：

OAuth 2.0 持有者代币

要进行 AG-UI 客户端身份验证，请在请求标头中包含 Bearer 令牌：

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

Sigv4 身份验证

编程访问还支持标准 AWS Sigv4 身份验证。

错误处理

根据错误的发生时间，将错误分为两类：

  • Connection-level 错误：在请求到达您的容器之前发生（身份验证、验证、限制）。它们返回标准的 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 身份验证响应

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

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

SigV4-configured 代理返回 HTTP 403 并ACCESS_DENIED显示错误，并且不包含WWW-Authenticate标头。