View a markdown version of this page

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

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

HTTP 协议合约

了解在代理应用程序中实现 HTTP 协议的要求。使用 HTTP 协议为传统 request/response 模式创建直接 REST API 端点，为实时双向流式传输连接创建 WebSocket 端点。

注意

HTTP (/invocations) 和 WebSocket (/ws) 端点均可使用端口 8080 部署在同一个容器上，从而允许单一代理实现支持传统 API 交互和实时双向流式传输。

有关示例代码，请参阅 AgentCore CLI 入门。

容器要求

您的代理必须部署为符合以下规格的容器化应用程序：

  • 主机：0.0.0.0

  • 端口：8080- HTTP-based 代理通信的标准端口

  • 平台：ARM64 容器-与 AgentCore 运行时环境兼容所必需的

路径要求

/invocations-POST

这是具有 JSON 输入和 JSON/SSE 输出的主要代理交互端点。

目的

接收来自用户或应用程序的传入请求，并通过代理的业务逻辑处理这些请求

使用案例

该/invocations端点有几个关键用途：

  • 直接的用户互动和对话

  • API 与外部系统的集成

  • 批量处理多个请求

  • Real-time 长时间运行的操作的流式响应

请求格式示例 

Content-Type: application/json

{
  "prompt": "What's the weather today?"
}

响应格式

根据用例，您的代理可以使用以下任一格式进行响应：

JSON 响应（非流式传输）

目的

为可以快速处理的请求提供完整的响应

使用案例

JSON 响应非常适合：

  • 简单的问答场景

  • 确定性计算

  • 快速数据查询

  • 状态确认

JSON 响应格式示例 

Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}

SSE 回应（直播）

Server-sent 事件 (SSE) 允许您提供实时流媒体响应。有关更多信息，请参阅Server-sent 事件规范。

目的

支持为长时间运行的操作提供增量响应并改善用户体验

使用案例

SSE 响应非常适合：

  • Real-time 对话体验

  • 渐进式内容生成

  • Long-running 计算结果为中间结果

  • 实时数据源和更新

SSE 响应格式示例 

Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}

/ws- WebSocket （可选）

这是实时双向通信的主要 WebSocket 连接端点。

目的

接受 WebSocket 升级请求并保持持续连接以进行流媒体代理交互

使用案例

该/ws端点有几个关键用途：

  • Real-time 对话接口

  • 具有即时反馈的交互式代理会话

  • 使用双向通信进行流式数据处理

建立连接

WebSocket 连接从 HTTP 升级请求开始：

HTTP 升级请求示例 

GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid

WebSocket 升级响应示例 

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

消息处理要求

您的 WebSocket 终端必须处理：

  • 接受连接：await websocket.accept()致电建立连接

  • 消息接收：根据您的应用程序要求支持文本或二进制消息类型

  • 消息处理：根据代理的业务逻辑处理传入的消息

  • 发送响应：使用send_text()或发送相应的响应 send_bytes()

  • 连接生命周期：管理连接建立、维护和终止

消息格式

短信
JSON 格式（推荐）

目的

代理交互的结构化数据交换

示例消息 

{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}

响应示例 

{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}
纯文本格式

目的

基于文本的简单通信

示例 

Hello, can you help me with this question?
二进制消息

目的

支持非文本数据，例如图像、音频或其他二进制格式

使用案例

二进制消息支持多种场景：

  • Multi-modal 代理相互作用

  • 文件上传和下载

  • 压缩数据传输

  • 二进制协议数据

处理要求

二进制消息处理需要：

  • 用途receive_bytes()和send_bytes()方法

  • 实现适当的二进制数据处理

  • 考虑邮件大小限制

连接生命周期

建立连接

  1. HTTP 握手：客户端发送 WebSocket 升级请求

  2. 升级响应：代理接受并返回 101 个交换协议

  3. WebSocket 活跃：双向通信开始

  4. 会话绑定：将连接与会话标识符关联起来

消息交换

  1. 连续循环：实现消息监听循环

  2. 消息处理：异步处理传入的消息

  3. 生成响应：发送相应的回复

  4. 错误处理：管理异常和连接问题

/ping-获取

目的

验证您的代理是否正常运行并已准备好处理请求

使用案例

该/ping端点有几个关键用途：

  • 服务监控以检测和修复问题

  • 通过 AWS的托管基础架构自动恢复

响应格式

返回表示代理人健康状况的状态码：

  • Content-Type : application/json

  • HTTP 状态码：200对于运行正常，对不健康状态使用相应的错误代码

如果您的代理需要处理后台任务，则可以用/ping状态指示。如果 ping 状态为HealthyBusy，则运行时会话被视为活动会话。

Ping 响应格式示例 

{
  "status": "<status_value>"
}
状态（必填）

Healthy-系统已准备好接受新工作

HealthyBusy-系统正在运行，但目前正忙于异步任务。当状态为时HealthyBusy，运行时会话被视为活动会话并保持活动状态。

上次更新时间（可选）

status上次更改时的 Unix 时间戳（以秒为单位）。仅在实际状态更改时进行设置。

警告

不要在每次 ping 时都设置time_of_last_update为当前时间。每次 ping 都会向前移动的时间戳表示状态持续变化，这可以防止空闲会话超时触发——然后会话会一直持续到会话配额用尽为止MaxLifetime。如果您省略该字段，平台会自行跟踪状态变化。如果您使用 Bedrock AgentCore SDK，则会为您处理 ping 响应。

错误处理

与 A2A、MCP 和 AG-UI 协议不同，HTTP 协议不会将错误封装在协议特定的信封中。该服务直接以原生 HTTP 响应的形式返回错误：HTTP 状态码反映异常，x-amzn-ErrorType响应标头带有异常名称。下表列出了您可以收到的例外情况。

HTTP 错误代码 运行时异常 (x-amzn-ErrorType) 说明

400

ValidationException

请求数据或参数无效

401

UnauthorizedException

需要进行身份验证或凭据无效（OAuth-configured 代理）

402

ServiceQuotaExceededException

请求将超过服务配额

403

AccessDeniedException

请求的操作权限不足

404

ResourceNotFoundException

请求的资源不存在

409

ConflictException

资源冲突-资源已经存在

409

RetryableConflictException

会话操作正在进行中，请重试

424

RuntimeClientError

您的代理的容器返回了 4xx 或 5xx 错误-请检查您的日志 CloudWatch

429

ThrottlingException

请求过多-已超过请求速率限制

500

InternalServerException

处理请求时出现意外错误

ConflictException并且RetryableConflictException都返回 HTTP 409。标x-amzn-ErrorType题和消息将它们区分开来。当第二项操作以服务正在配置或拆除的会话为目标时，该服务返回 RetryableConflictException (Session operation in progress, please retry)。这种情况是暂时的，可以重试。使用短暂的指数退避重试。启用默认重试后， AWS SDK 会自动重试此异常。如果您在没有 AWS SDK 的情况下直接调用 API，则必须自己重试。

注意

ServiceQuotaExceededException在此原生 HTTP 表面上返回 HTTP 402。在 A2A 协议上，它返回 HTTP 429，与限制相同 HTTP 状态。在 MCP 协议上，它共享限制 JSON-RPC 错误代码 (-32003)，但返回 HTTP 200。 AG-UI 它使用不同的 SERVICE_QUOTA_EXCEEDED SSE 代码并返回 HTTP 429。

OAuth 身份验证响应

OAuth-configured 代理遵循 RFC 6749 (OAuth 2.0) 身份验证标准。缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 RFC 7235），使客户端能够通过 API 发现授权服务器端点。 GetRuntimeProtectedResourceMetadata

401 未经授权

缺少授权标头时返回。

包括 WWW-Authenticate 标题：

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
注意

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