第3章 工具调用协议设计：HTTP / JSON-RPC / WebSocket、请求-响应模式、异常协议

协议是 Agent 与工具之间通信的语法契约。本章聚焦三种主流协议——HTTP REST、JSON-RPC、WebSocket——在设计工具调用时的核心差异、适用场景、请求-响应模式以及异常协议规范。

3.1 协议选型：性能、语义与适用场景

选择哪种协议取决于工具的使用模式：同步查询、异步任务、流式推送还是高频双向通信。下表从关键维度做了横向对比。

3.2 HTTP 协议：端点设计与请求-响应模式

3.2.1 端点（Endpoint）设计原则

• 使用名词复数表示资源：/tools、/tools/{id}/invoke
• 动作通过 HTTP 方法表达：GET 查询、POST 调用、DELETE 撤销
• 查询参数用于过滤，请求体用于传递调用输入

POST /api/v1/tools/weather/invoke
Content-Type: application/json

{
  "city": "北京",
  "date": "2025-06-10",
  "unit": "celsius"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": {
    "temperature": 28,
    "condition": "晴",
    "humidity": 45
  },
  "request_id": "req-7a3f2c"
}

3.2.2 请求-响应生命周期

1. Agent 构造请求体（含工具名、参数、元数据）
2. 通过 HTTP POST 发送到工具端点
3. 工具服务端校验参数 → 执行业务逻辑 → 构造响应
4. Agent 接收响应并提取 data 或 error
5. 若超时或状态码非 2xx，触发重试或降级策略

3.3 JSON-RPC 协议：结构化调用契约

JSON-RPC 是轻量级远程过程调用协议，天然适合 Agent 工具调用。每个请求包含固定的 jsonrpc、method、params、id 字段，响应严格对称。

3.3.1 请求与响应结构

// 请求
{
  "jsonrpc": "2.0",
  "method": "getWeather",
  "params": {
    "city": "北京",
    "date": "2025-06-10"
  },
  "id": 1
}

// 成功响应
{
  "jsonrpc": "2.0",
  "result": {
    "temperature": 28,
    "condition": "晴"
  },
  "id": 1
}

// 错误响应
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "服务暂时不可用",
    "data": {
      "retry_after": 5
    }
  },
  "id": 1
}

3.3.2 方法命名规范

3.4 WebSocket 协议：流式与双向调用

当 Agent 需要连续调用多个工具或监听工具推送事件时，WebSocket 的长连接特性可以显著降低延迟。

3.4.1 连接建立与消息帧

// 客户端 → 服务端：调用请求
{
  "type": "invoke",
  "tool": "weather_stream",
  "params": { "city": "北京", "interval": 60 },
  "request_id": "ws-req-001"
}

// 服务端 → 客户端：流式数据块
{
  "type": "data",
  "request_id": "ws-req-001",
  "payload": { "temperature": 28, "timestamp": "2025-06-10T10:00:00Z" }
}

// 服务端 → 客户端：完成通知
{
  "type": "complete",
  "request_id": "ws-req-001",
  "status": "success"
}

// 服务端 → 客户端：错误通知
{
  "type": "error",
  "request_id": "ws-req-001",
  "code": -32001,
  "message": "数据源断开",
  "retryable": true
}

3.4.2 心跳保持与重连策略

• 客户端每 30 秒发送 {"type":"ping"}，服务端回复 {"type":"pong"}
• 若连续 3 次未收到 pong，触发重连
• 重连时使用指数退避：1s、2s、4s、8s …… 最大 60s

3.5 异常协议：统一错误码与异常传播

无论使用哪种传输协议，工具调用的异常信息必须结构化、可枚举、可处理。一套统一的异常协议能让 Agent 快速决策是重试、降级还是终止。

3.5.1 标准错误码体系

{
  "error": {
    "code": 2001,
    "message": "余额不足，当前可用额度 0.5 元",
    "data": {
      "required_amount": 10.0,
      "current_balance": 0.5,
      "suggestion": "请充值后重试"
    },
    "retryable": false,
    "retry_after": null
  }
}

3.5.2 异常传播链路

当工具调用链中某个环节失败时，异常信息应沿着调用链向上传播，并携带原始错误上下文，避免在中间层被吞没。

3.6 协议适配器架构

为支持多协议统一管理，建议在工具网关层引入 协议适配器，将不同协议的请求统一转换为内部标准 Invocation 对象。

3.7 调试与部署检查清单

3.8 常见错误与规避

• 协议混用但适配器缺失：某工具同时暴露 HTTP 和 WebSocket 端点，但内部未统一调用模型，导致逻辑分支爆炸。解决方法是在网关层做协议适配。
• JSON-RPC id 冲突：多个请求使用相同 id，导致响应匹配错乱。保证每次调用生成唯一 id（UUID 或递增整数）。
• WebSocket 未处理心跳：连接被网络设备静默断开，Agent 仍认为连接可用。必须实现 ping/pong + 超时重连。
• 异常被中间件吞没：工具链中某环节捕获异常后返回 null，上游误判为成功。始终传递 error 对象，不允许空响应代表成功。

3.9 性能与稳定性优化