# HTTP 协议合约
<a name="runtime-http-protocol-contract"></a>

了解在代理应用程序中实现 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)
+ [OAuth 身份验证响应](#http-oauth-authentication-responses)

## 容器要求
<a name="container-requirements-http"></a>

您的代理必须部署为符合以下规格的容器化应用程序：
+  **主机**：`0.0.0.0`
+  **端口**：`8080`-用于 HTTP-based 代理通信的标准端口
+  **平台**：ARM64 容器-需要与 AgentCore 运行时环境兼容

## 路径要求
<a name="path-requirements-http"></a>

### /invocations-POST
<a name="invocations-endpoint"></a>

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

 **目的** 

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

 **使用案例** 

该`/invocations`端点有几个关键用途：
+ 直接的用户互动和对话
+ API 与外部系统的集成
+ 批量处理多个请求
+ Real-time 为长时间运行的操作流式传输响应

 **请求格式示例** 

```
Content-Type: application/json

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

 **响应格式** 

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

#### JSON 响应（非流式传输）
<a name="json-response"></a>

 **目的** 

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

 **使用案例** 

JSON 响应非常适合于：
+ 简单的问答场景
+ 确定性计算
+ 快速查找数据
+ 状态确认

 **JSON 响应格式示例** 

```
Content-Type: application/json

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

#### SSE 响应（直播）
<a name="sse-response"></a>

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 （可选）
<a name="ws-endpoint"></a>

这是实时双向通信的主要 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()` 
+  **连接生命周期**：管理连接的建立、维护和终止

#### 消息格式
<a name="websocket-message-formats"></a>

##### 短信
<a name="websocket-text-messages"></a>

##### JSON 格式（推荐）
<a name="websocket-json-format"></a>

 **目的** 

用于代理互动的结构化数据交换

 **消息示例** 

```
{
  "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"
}
```

##### 纯文本格式
<a name="websocket-plain-text-format"></a>

 **目的** 

基于文本的简单通信

 **示例** 

```
Hello, can you help me with this question?
```

##### 二进制消息
<a name="websocket-binary-messages"></a>

 **目的** 

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

 **使用案例** 

二进制消息支持多种场景：
+ Multi-modal 代理互动
+ 文件上传和下载
+ 压缩数据传输
+ 二进制协议数据

 **处理要求** 

二进制消息处理需要：
+ 用途`receive_bytes()`和`send_bytes()`方法
+ 实现适当的二进制数据处理
+ 考虑邮件大小限制

#### 连接生命周期
<a name="websocket-connection-lifecycle"></a>

##### 连接建立
<a name="websocket-connection-establishment"></a>

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

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

1.  **WebSocket 主动**：双向通信开始

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

##### 消息交换
<a name="websocket-message-exchange"></a>

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

1.  **消息处理**：异步处理传入的消息

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

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

### /ping-GET
<a name="ping-endpoint"></a>

 **目的** 

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

 **使用案例** 

该`/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 身份验证响应
<a name="http-oauth-authentication-responses"></a>

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 未经授权
<a name="http-401-unauthorized"></a>

缺少授权标头时返回。

包括 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`标头。