HTTP协议基础与RESTful风格：方法、状态码、请求头、响应体

Agent工具调用接口的核心传输载体是HTTP协议。本章从底层原理出发，系统讲解HTTP方法、状态码、请求头与响应体的设计规范，并结合RESTful风格说明如何在Agent接口中正确使用这些元素。

1. HTTP协议请求-响应模型

HTTP协议基于客户端-服务器（C/S）模型，采用无状态、明文传输的请求-响应交互模式。一次完整的HTTP事务包含以下阶段：

1. 客户端（Agent/应用）建立TCP连接（默认端口80/443）。
2. 客户端发送HTTP请求（请求行 + 请求头 + 可选的请求体）。
3. 服务器解析请求，执行逻辑，返回HTTP响应（状态行 + 响应头 + 响应体）。
4. 连接关闭或复用（HTTP/1.1默认Keep-Alive）。

2. HTTP方法（Methods）

RESTful风格要求每种方法对应一种资源操作。Agent工具调用中常用以下方法：

3. HTTP状态码（Status Codes）

状态码是服务端向Agent传递处理结果的数字信号。按大类划分如下：

4. HTTP请求头（Request Headers）

请求头携带元数据，直接影响服务器解析与安全校验。Agent接口必须关注以下头部：

完整请求示例（调用Agent工具）

POST /v1/tools/calculator HTTP/1.1
Host: api.agent.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
User-Agent: AgentClient/1.0

{
  "operation": "add",
  "a": 10,
  "b": 20
}

5. HTTP响应体与响应头

响应头中的 Content-Type 决定Agent如何解析响应体。标准Agent接口通常返回JSON结构：

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
X-RateLimit-Remaining: 99

{
  "code": 0,
  "message": "success",
  "data": {
    "result": 30,
    "execution_time_ms": 2
  }
}

6. RESTful资源设计流程

设计一个Agent工具调用接口时，遵循以下5步流程：

1. 识别资源：确定Agent要操作的实体（如 任务、工具实例、会话）。
2. 规划URL：使用名词复数形式，层级通过 / 表达。例：/api/v1/tasks、/api/v1/tasks/{task_id}。
3. 分配方法：对照上表为每个端点选择正确的HTTP方法。
4. 定义请求/响应Schema：明确必选头、可选头、请求体JSON结构、成功/错误响应结构。
5. 指定状态码映射：列出每个端点所有可能的状态码，并附带处理策略（重试、报错、降级）。

7. 常见错误与调试要点

8. 调试工具与命令行快速验证

推荐使用 curl 快速验证接口行为：

# GET 请求查询工具状态
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "Authorization: Bearer sk-your-token" \
  -H "Accept: application/json" \
  https://api.agent.example.com/v1/tools/calculator/status

# POST 请求调用工具
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -H "Accept: application/json" \
  -d '{"operation":"add","a":10,"b":20}' \
  https://api.agent.example.com/v1/tools/calculator