View a markdown version of this page

HTTP 协议合约 - Amazon Bedrock 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?
二进制消息

目的

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

使用案例

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

  • Multi-modal 代理互动

  • 文件上传和下载

  • 压缩数据传输

  • 二进制协议数据

处理要求

二进制消息处理需要：

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

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

  • 考虑邮件大小限制

连接生命周期

连接建立

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

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

  3. WebSocket 主动：双向通信开始

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

消息交换

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

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

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

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

/ping-GET

目的

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

使用案例

该/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 响应会由你处理。

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标头。