# HTTP
介绍代理应用中 HTTP 协议的实现要求，基于 HTTP 搭建 REST API 接口以适配传统请求响应模式，同时部署 WebSocket 接口实现实时双向流式通信。
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
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"
    }
    ```