错误处理

真正让 tool calling 稳定的，不是“能跑通 happy path”，而是错误时系统会不会乱。

建议统一错误结构

{
  "ok": false,
  "error_code": "UPSTREAM_TIMEOUT",
  "message": "weather api timed out after 5000ms",
  "retryable": true,
  "details": {
    "provider": "weather-api",
    "timeout_ms": 5000
  }
}

错误分层

1. 解析层错误

例如：

• arguments 不是合法 JSON
• provider 响应缺字段
• SDK 类型不符合预期

2. 业务层错误

例如：

• 用户参数非法
• 资源不存在
• 权限不够

3. 基础设施错误

例如：

• 网络超时
• DNS 失败
• 速率限制
• 上游 5xx

要不要把错误原样给模型

不建议把底层异常栈直接塞回模型。

更好的方式是返回：

• 简洁错误码
• 面向模型可理解的信息
• 是否可重试
• 必要时附少量 details

重试原则

不是所有错误都值得重试：

• 参数错误：不该重试
• 权限错误：不该盲重试
• 网络抖动：可有限次重试
• 限流：应遵循 Retry-After