本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# HTTP 协议合约
了解在代理应用程序中实现 HTTP 协议的要求。使用 HTTP 协议为传统 request/response 模式创建直接 REST API 端点，为实时双向流式传输连接创建 WebSocket 端点。
**注意**
HTTP (`/invocations`) 和 WebSocket (`/ws`) 端点均可使用端口 8080 部署在同一个容器上，从而允许单一代理实现支持传统 API 交互和实时双向流式传输。
有关示例代码，请参阅 AgentCore CLI [ 入门](runtime-get-started-cli.md)。
**Topics**
+ [容器要求](#container-requirements-http)
+ [路径要求](#path-requirements-http)
+ [错误处理](#http-error-handling)
+ [OAuth 身份验证响应](#http-oauth-authentication-responses)
## 容器要求
您的代理必须部署为符合以下规格的容器化应用程序：
+ **主机**：`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 事件](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events)规范。
**目的**
支持为长时间运行的操作提供增量响应并改善用户体验
**使用案例**
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 升级请求
1. **升级响应**：代理接受并返回 101 个交换协议
1. **WebSocket 活跃**：双向通信开始
1. **会话绑定**：将连接与会话标识符关联起来
##### 消息交换
1. **连续循环**：实现消息监听循环
1. **消息处理**：异步处理传入的消息
1. **生成响应**：发送相应的回复
1. **错误处理**：管理异常和连接问题
### /ping-获取
**目的**
验证您的代理是否正常运行并已准备好处理请求
**使用案例**
该`/ping`端点有几个关键用途：
+ 服务监控以检测和修复问题
+ 通过 Amazon的托管基础架构自动恢复
**响应格式**
返回表示代理人健康状况的状态码：
+ **Content-Type** : `application/json`
+ **HTTP 状态码**：`200`对于运行正常，对不健康状态使用相应的错误代码
如果您的代理需要处理后台任务，则可以用`/ping`状态指示。如果 ping 状态为`HealthyBusy`，则运行时会话被视为活动会话。
**Ping 响应格式示例 **
```
{
"status": ""
}
```
**状态**（必填）
`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`)。这种情况是暂时的，可以重试。使用短暂的指数退避重试。启用默认重试后， Amazon SDK 会自动重试此异常。如果您在没有 Amazon 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) 身份验证标准。](https://datatracker.ietf.org/doc/html/rfc6749)缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 [ RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)），使客户端能够通过 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`标头。