错误现象全景：常见错误类型汇总、识别方法、优先级划分
Agent 调用外部工具时，错误现象多样且隐蔽。若未建立系统化的分类与识别框架，排障会陷入“看现象猜原因”的循环。本章从实际生产故障中提炼出六大错误类型，给出可量化的识别方法与优先级划分标准，并串联完整排查闭环。
1.1 常见错误类型汇总
| 类型 | 典型现象 | 典型日志/响应示例 |
|---|---|---|
| 网络错误 | 连接超时、DNS 解析失败、TCP 重置 | ConnectionError: [Errno 110] Connection timed out |
| 认证错误 | 401 Unauthorized、403 Forbidden、令牌过期 | HTTP 401: {"error":"invalid_token"} |
| 接口规范错误 | 请求参数缺失、格式不匹配、Method 不允许 | 400 Bad Request: "missing required field: 'action'" |
| 响应解析错误 | JSON 解析失败、非预期字段类型、空响应 | json.decoder.JSONDecodeError: Expecting value: line 1 column 1 |
| 超时与限流 | 请求超时、429 Too Many Requests、速率限制 | HTTP 429: {"retry_after": 120} |
| 资源限制错误 | 文件大小超限、并发数超限、内存不足 | 413 Payload Too Large: {"message":"Max file size 10MB"} |
识别技巧：优先查看 Agent 日志中 HTTP 状态码（4xx/5xx）与异常类型关键字。网络类错误通常在底层 socket 层抛错，认证错误多在 HTTP 头部返回，解析错误固定出现在序列化/反序列化阶段。
1.2 识别方法：从现象到类型的判断规则
- 观察错误发生的时间窗口：连续失败 → 网络/认证/限流；偶发失败 → 解析/接口规范。
- 检查 HTTP 状态码：
4xx→ 客户端问题（参数/认证）；5xx→ 服务端问题（超时/限流/资源）；无响应 → 网络或超时。 - 解析异常类型字符串：
ConnectionError→ 网络；JSONDecodeError→ 解析；ValueError→ 接口规范。 - 查看响应体内容：包含
error、code、message字段时直接映射到预定义错误码表。
# 典型日志片段：响应解析错误
[2025-03-21 10:15:23] ERROR - Tool "weather_api" returned:
{"status": "failed", "err": "invalid city code"}
# 判断规则：err 字段非空 → 接口规范错误（参数错误）1.3 优先级划分
| 优先级 | 定义 | 包含类型 | 处理时限 |
|---|---|---|---|
| P0（致命） | 工具完全不可用，阻塞核心业务流程 | 网络错误（持续）、认证令牌彻底失效 | <1h |
| P1（严重） | 频繁失败（>30% 调用），影响用户体验 | 超时/限流、连续接口规范错误 | <4h |
| P2（一般） | 偶发失败，可降级或重试恢复 | 响应解析错误、单次认证刷新生效 | <24h |
| P3（低优） | 不影响功能，仅影响日志或统计 | 非重要字段解析警告、资源限制边界 | 下次迭代 |
常见误判：将“响应解析错误”降为低优先级，但若解析失败导致 Agent 重复重试，可能触发限流升级为 P1。优先级应结合调用频率与重试策略综合评估。
1.4 排查闭环：从现象到预防的六步骤
以下 SVG 展示了完整的排查流程，每阶段产出物与典型错误类型的对应关系：
排查闭环要点：
- 现象识别阶段需准确映射到六大类型，否则后续采集的日志可能遗漏关键字段。
- 原因定位必须结合采集到的原始请求/响应，而非仅依赖 Agent 内部摘要。
- 修复动作后务必触发复测，且复测应覆盖正常路径与边界条件（如重试次数上限）。
- 预防阶段需将错误码、优先级、处理流程写入可执行文档，并配置对应告警。