很多 AI Agent 项目从 demo 走向生产时，最先暴露的不是模型能力，而是排障能力。

用户只看到“回答慢、结果错、费用高”。工程团队如果只能看到一行 `tool call failed`，问题基本没法定位。

生产级 Agent 的第一步不是再换一个更强模型，而是先把 trace 和 tool span 打出来。

## 1. 为什么普通日志不够

传统后端服务里，请求路径通常比较固定：

```text
HTTP request -> service -> database -> response
```

Agent 系统的路径更像这样：

```text
user intent
  -> prompt assembly
  -> model routing
  -> tool selection
  -> tool input validation
  -> external system call
  -> model reasoning
  -> final response or human handoff
```

如果每一步只写一行自然语言日志，后续很难回答三个关键问题：

1. 慢在哪一层？
2. 贵在哪一次模型或工具调用？
3. 错是模型判断错、上下文错，还是工具返回错？

所以 Agent 可观测性的核心不是“日志更多”，而是把一次任务拆成可以追踪的 span。

## 2. 一个最小 trace 结构

可以先不追求复杂平台，先保证每次任务有统一的 `trace_id`：

```json
{
  "trace_id": "tr_20260614_001",
  "user_intent": "查询客户最近一次工单并生成摘要",
  "route": "support_agent_v2",
  "model": "claude-sonnet",
  "risk_level": "medium",
  "started_at": "2026-06-14T09:30:00+08:00"
}
```

每次工具调用再记录一个 tool span：

```json
{
  "trace_id": "tr_20260614_001",
  "span_id": "tool_03",
  "tool_name": "ticket.search",
  "reason": "需要找到客户最近一次工单",
  "input_schema_version": "v1",
  "input_summary": {
    "customer_id": "masked",
    "limit": 1
  },
  "permission_result": "allowed",
  "latency_ms": 842,
  "status": "success",
  "retry_count": 0
}
```

注意这里不一定要把所有原始数据明文写入日志。生产环境更常见的做法是记录摘要、哈希、脱敏字段和对象引用，避免把敏感数据复制到日志系统里。

## 3. tool span 至少要包含什么

我建议从 8 个字段开始：

| 字段 | 作用 |
| --- | --- |
| `trace_id` | 串起一次完整任务 |
| `tool_name` | 知道调用了哪个外部能力 |
| `reason` | 记录模型为什么选择这个工具 |
| `input_summary` | 保留入参摘要，避免明文泄露 |
| `permission_result` | 证明权限判断经过了系统 |
| `latency_ms` | 定位慢调用 |
| `status/error_code` | 区分工具失败和模型失败 |
| `retry_count` | 判断是否存在无效重试 |

这些字段先打出来，很多问题会立刻变清楚。

比如用户反馈“Agent 很慢”，你可以看到是模型推理慢、检索慢，还是某个外部 API 重试了 3 次。

用户反馈“结果错”，你可以看到是检索上下文错、工具入参错，还是模型在工具返回后总结错。

用户反馈“费用高”，你可以看到是不是高风险模型被低价值任务滥用了。

## 4. 权限边界必须进入 trace

Agent 比普通聊天机器人更危险的地方，是它可能调用真实系统。

只要涉及写入、发送、审批、支付、删除、变更配置，就不应该只依赖 prompt 约束。

权限判断应该是系统级逻辑，并且进入 trace：

```json
{
  "tool_name": "invoice.send",
  "risk_level": "high",
  "permission_result": "blocked",
  "block_reason": "requires_human_approval",
  "approval_policy": "finance_handoff_v2"
}
```

这样出问题后，你能证明系统是否执行过边界判断，而不是事后猜测“模型当时是不是理解错了”。

## 5. 失败处理也要被记录

很多 Agent demo 只处理成功路径。生产系统最该先设计失败路径。

一次失败至少要回答：

- 是否允许重试？
- 重试用了同样参数还是修正参数？
- 是否触发降级模型或备用工具？
- 是否转人工？
- 是否回滚了已经执行的动作？

这些信息如果没有记录，事故复盘就会变成口头回忆。

## 6. 和 OpenTelemetry 怎么结合

如果团队已经在用 OpenTelemetry，可以把 Agent 的一次任务当成 trace，把模型调用、检索、工具调用、权限判断、人工接管都建成 span。

关键是不要只记录 HTTP 层 span。Agent 系统还需要业务语义：

- `agent.route`
- `agent.model`
- `agent.tool.name`
- `agent.tool.reason`
- `agent.risk_level`
- `agent.permission.result`
- `agent.handoff.required`

这些字段会让排障从“看服务状态”升级到“看 Agent 决策链”。

## 7. 最小落地顺序

如果现在系统已经在跑，但排障困难，可以按这个顺序补：

1. 所有请求加 `trace_id`
2. 模型调用记录 token、延迟、模型名
3. 工具调用记录 tool span
4. 高风险工具加入权限判断和人工复核
5. 失败路径记录重试、降级、回滚
6. 每周抽样复盘 5 条失败 trace

不要一开始就追求完整平台。先让每一次关键失败都有证据。

## 结论

Agent 慢、贵、错，通常不是一个单点问题。

它可能是模型路由、上下文、工具入参、外部系统、权限策略、失败处理共同作用的结果。

先把 trace 和 tool span 打出来，团队才有资格讨论优化。否则换模型、调 prompt、加缓存，都只是猜。