核心原则

Agent 不可能完全避免报错，关键在于：

让错误可恢复（Recoverable）、可观测（Observable）、可控制（Controllable）。

标准处理流程：

text
报错发生
    ↓
识别错误类型
    ↓
判断是否可重试
    ↓
自动修复或降级
    ↓
记录日志
    ↓
必要时转人工

---

1. 错误分类

1.1 工具错误（Tool Error）

示例：

• API 超时
• 数据库连接失败
• 网络异常
• 第三方服务不可用

处理方式：

• 自动重试
• 指数退避（Exponential Backoff）
• 切换备用服务

---

1.2 参数错误（Parameter Error）

示例：

json
{
  "date": "tomorrow"
}

工具要求：

json
{
  "date": "2026-06-03"
}

处理方式：

• 让 LLM 重新生成参数
• 参数格式校验
• 自动修正

---

1.3 权限错误（Permission Error）

示例：

• Token 失效
• API Key 过期
• 无访问权限

处理方式：

• 停止执行
• 返回明确错误信息
• 通知管理员或人工处理

---

1.4 业务错误（Business Error）

示例：

• 库存不足
• 订单不存在
• 用户余额不足

处理方式：

• 不重试
• 返回业务原因
• 请求用户补充信息

---

1.5 推理错误（Reasoning Error）

示例：

• 调错工具
• 步骤遗漏
• 错误规划

处理方式：

• 重新规划任务
• 回退到上一步
• 重新生成执行计划

---

1.6 循环错误（Loop Error）

示例：

text
搜索
 ↓
搜索
 ↓
搜索
 ↓
搜索

处理方式：

• 限制执行步数
• 限制重试次数
• 检测重复行为

---

2. 工具调用保护层

不要让 Agent 直接调用工具。

推荐增加 Safe Wrapper：

python
def safe_call(tool, args):
    try:
        result = tool(**args)

        return {
            "ok": True,
            "result": result
        }

    except TimeoutError:
        return {
            "ok": False,
            "error_type": "timeout"
        }

    except ValueError as e:
        return {
            "ok": False,
            "error_type": "invalid_args",
            "message": str(e)
        }

    except Exception as e:
        return {
            "ok": False,
            "error_type": "unknown",
            "message": str(e)
        }

优点：

• Agent 获得结构化错误
• 降低异常处理复杂度
• 方便自动恢复

---

3. 可重试与不可重试

可重试错误

• 网络超时
• 服务暂时不可用
• Rate Limit
• JSON 解析失败
• LLM 输出格式错误

示例：

python
for i in range(3):
    try:
        call_tool()
        break
    except TimeoutError:
        sleep(2 ** i)

---

不可重试错误

• 权限不足
• 用户信息缺失
• 参数明显非法
• 业务规则拒绝

例如：

text
用户不存在

继续重试没有意义。

---

4. Agent 自动修复机制

工具返回：

json
{
  "ok": false,
  "error_type": "invalid_args",
  "message": "date must be YYYY-MM-DD"
}

Agent 应执行：

text
读取错误信息
    ↓
修正参数
    ↓
重新调用工具

而不是直接失败。

---

5. 降级（Fallback）策略

搜索系统

text
实时搜索
    ↓失败
知识库搜索
    ↓失败
缓存结果
    ↓失败
人工处理

---

模型降级

text
GPT-5
    ↓失败
GPT-4.1
    ↓失败
规则系统

---

6. 熔断（Circuit Breaker）

防止系统持续调用故障服务。

示例：

text
连续失败 5 次
    ↓
熔断
    ↓
暂停调用 60 秒
    ↓
恢复检测

作用：

• 防止雪崩
• 保护系统资源

---

7. 最大执行限制

推荐配置：

yaml
max_steps: 20
max_tool_calls: 30
max_retries: 3
max_runtime_seconds: 60

达到限制：

text
停止执行
总结当前结果
返回失败原因

---

8. 日志记录

至少记录：

json
{
  "goal": "生成市场分析报告",
  "step": 4,
  "tool": "web_search",
  "input": "...",
  "output": "...",
  "error": "timeout",
  "retry_count": 2
}

日志应包含：

• 用户目标
• 执行步骤
• 工具输入
• 工具输出
• 错误信息
• 重试次数
• 最终结果

---

9. 失败报告机制

错误发生时不要只返回：

text
任务失败

推荐：

text
任务执行失败

失败步骤：
查询订单状态

失败原因：
订单接口超时

已尝试：
重试 3 次

当前影响：
无法确认订单状态

建议：
稍后重试或转人工处理

---

10. 推荐 Agent 架构

text
                User Goal
                    │
                    ▼
              Planner
                    │
                    ▼
             Tool Router
                    │
                    ▼
          Safe Tool Wrapper
                    │
                    ▼
        Retry / Fallback Layer
                    │
                    ▼
             Observation
                    │
                    ▼
             Agent 决策
                    │
                    └────► 下一步执行

---

11. 最佳实践

原则一：错误结构化

不要直接抛异常：

python
raise Exception(...)

推荐：

json
{
  "ok": false,
  "stage": "tool_call",
  "error_type": "timeout",
  "retryable": true,
  "suggested_action": "retry"
}

---

原则二：限制 Agent 自主性

必须设置：

• 最大执行步数
• 最大重试次数
• 最大执行时间

避免无限循环。

---

原则三：优先恢复而非失败

Agent 收到错误后优先考虑：

1. 修正参数
2. 重试
3. 切换工具
4. 降级执行
5. 转人工

而不是直接终止任务。

---

总结

优秀的 Agent 系统并不是：

text
不出错

而是：

text
出错
 ↓
发现
 ↓
理解
 ↓
修复
 ↓
继续执行

核心设计理念：

错误是正常状态（Error is Normal State），Agent 的能力体现在如何从错误中恢复。