HTTP

介绍代理应用中 HTTP 协议的实现要求，基于 HTTP 搭建 REST API 接口以适配传统请求响应模式，同时部署 WebSocket 接口实现实时双向流式通信。

HTTP（/invocations）和WebSocket（/ws）端点可部署在同一个容器中并使用8080端口，单个代理服务可同时兼容传统 API 交互与实时双向流式通信。

镜像要求

需满足以下容器化应用：

Host：0.0.0.0
端口：基于HTTP代理通信的标准端口8080
系统：ARM64 容器

路径要求

/invocations - POST
主要的代理交互端点，提供JSON输入和JSON/SSE输出。
- 目的：接收来自用户或应用的请求，并通过代理业务逻辑进行处理。
- 使用场景
  - 用户互动与对话
  - 与外部系统的API集成
  - 多请求的批量处理
  - 长期运行操作的实时流响应
请求格式示例
```
Content-Type: application/json
{
  "prompt": "What color do you like?"
}
```
响应格式

可以根据使用场景使用以下两种格式进行响应：
- JSON 响应（非流式）
  目的：为请求提供完整的响应，适用于快速处理。
  
  使用场景
  - 简单的问答场景
  - 确定性计算
  - 快速数据查询
  - 状态确认
  JSON 响应格式示例
```
Content-Type: application/json
{
  "response": "I like red"
}
```
- SSE响应（流式传输）
  服务器发送事件（SSE）能够实时传递流式响应。
  
  目的：支持增量响应交付，实现长期运营和提升用户体验。
  
  使用场景
  - 实时对话体验
  - 渐进式内容生成
  - 具有中间结果的长期计算
  - 实时数据流与更新
  SSE响应格式示例
```
Content-Type: text/event-stream
data: {"event": "response 1"}
data: {"event": "response 2"}
data: {"event": "response"}
```

/ws - WebSocket（可选）
实现实时双向通信的主要WebSocket连接端点。

目的：接受WebSocket升级请求，并维护流代理交互的持久连接。

使用场景
- 实时对话接口
- 互动代理会话，提供即时反馈
- 双向通信的流式数据处理
连接建立

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

HTTP升级请求示例
```
GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: 8ZJk2cV7L9aX3pR5sQ7tW2eY1bN4mD6hG8jK0fS9dA2=
X-Hw-Agentarts-Session-Id: session-uuid
```
WebSocket升级响应示例
```
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: 8ZJk2cV7L9aX3pR5sQ7tW2eY1bN4mD6hG8jK0fS9dA2=
```
消息处理要求
- 连接接受：调用 await websocket.accept() 建立连接。
- 消息接收：支持基于应用需求的文本或二进制消息类型。
- 消息处理：根据代理的业务逻辑处理接收到的消息。
- 响应发送：发送适当的响应，使用 send_text() 或 send_bytes()。
- 连接生命周期：管理连接的建立、维护和终止。
消息格式
- JSON格式（推荐）
  请求示例
```
{
  "prompt": "What color do you like?",
}
```
  响应示例
```
{
  "response": "I like red",
}
```
- 纯文本格式
  使用场景
  - 多模态代理交互
  - 文件上传与下载
  - 压缩数据传输
  - 二进制协议数
WebSocket协议过程
- 连接建立
  - HTTP 握手：客户端发送 WebSocket 升级请求
  - 升级响应：代理接受并返回101交换协议
  - WebSocket激活：双向通信开始
  - 会话绑定：将连接与会话标识符关联
- 消息交换
  1. 连续循环：实现消息监听环路
  2. 消息处理：异步处理消息
  3. 响应生成：发送合适的回复
  4. 错误处理：管理异常和连接问题

/ping - GET
目的：验证代理是否已运行并准备好处理请求。

使用场景：服务监控以检测和修复问题。

响应格式

返回状态代码，显示代理健康状况：
- 类型：application/json
- HTTP 状态码：
  1. Agent 启动后，ping 接口不可用
    - 表现：端口无法连接，或者连接后无法返回应答。
    - 状态：Initing
    - 含义：Agent 正在启动，尚未准备好处理请求。
  2. Agent 启动中，ping 接口已经可用，返回 Initing 状态
    - HTTP 返回状态码：200
    - 应答返回的状态：{"status": "Initing"}
    - 含义：Agent 正在初始化，暂时未完成，还没有就绪。
  3. Agent 就绪，初始化完成，ping 返回 Healthy 状态
    - HTTP 返回状态码：200
    - 应答返回的状态：{"status": "Healthy"}
    - 含义：Agent 健康，当前没有异步后台任务。
    - 空闲超时：如果一个 Agent 连续处于 Healthy (Idle) 状态超过空闲超时时间（例如 15 分钟），则应该发起删除 sandbox 的流程。
  4. Agent 启动了后台异步任务，ping 返回 HealthyBusy 状态
    - HTTP 返回状态码：200
    - 应答返回的状态：{"status": "HealthyBusy"}
    - 含义：Agent 健康，有后台异步任务正在运行。这对于支持 Agent 运行工作时间远超过空闲超时的长任务至关重要。
  5. Agent 不健康
    - 表现：ping 接口无法连接，或者无应答，或者返回 HTTP 200 之外的状态码。
    - 状态：不健康
    - 含义：Agent 不健康，多次健康检查失败则会发起删除 sandbox 的流程。
  示例 Ping 响应格式
```
{
  "status: Healthy",
}
```