---
title: "Agent Harness 可观测性：生产级 AI 项目必须补上的一课"
author: "叶小钗"
source: "兔兔AGI"
source_url: "https://mp.weixin.qq.com/s/yU3-ciE-R6pJ1tluHlYF3Q"
created: 2026-05-25
type: raw
tags: [article]
sha256: 984445a33b3b477e6c9c0ee7b738ed534568c69dc357e90c6e2753215f0d7b02
---

# Agent Harness 可观测性：生产级 AI 项目必须补上的一课

## 为什么需要 Agent 可观测性

今年开始，Agent 的基础执行环境从能力上已经 OK，所以逐渐开始有很多产品真正的走向生产，这个时候如何让 Agent 长期稳定的运行，如何正确的执行长链路复杂任务就变得很重要了。

**问题本质**：传统软件执行路径固定，出错了可以重跑复现。但 Agent 不一样，同样的问题，每一次的执行路径都可能不一样，每一次输出的内容都不一样，甚至工具选择都不一样。

**课程来源**：某产品负责人学员的感叹——"他们怎么量化上限、有没有过程方法论？这批程序员就说量化不了、沉淀不了，都是别人的东西跑一下就好了。"

## 模型的能力边界

做 AI 应用一定要了解模型边界，这里涉及两个流派：
- **AI Max**：能用 AI 就用 AI
- **AI Min**：能不用 AI 就不用 AI

可观测性只在 AI Min 模式下可行。追求完美准确率不现实，关键是要知道错在哪、为什么错、怎么改，并且能证明技术框架是闭环可重复的。

**最小化 AI 应用原则**：只在不得不使用 AI 的地方使用 AI，比如语义识别、泛化要求高的场景。拿到结果后再用算法做实现。

## Agent 可观测性八大组件

### 1. 原始数据记录

原始数据包括：
- `model_call` 和 `model_result`：模型输入输出、token、耗时、模型名
- `tool_call` 和 `tool_result`：工具名、参数、结果、错误
- 上下文和状态变化（压缩、任务状态迁移）
- 观测系统生成的事件（anomaly、evaluation）

### 2. 指标设计

- **工具错误率**：提示工具 schema 是否清晰
- **模型调用耗时**
- **Token 消耗**
- **上下文压缩频率**：判断窗口设置或压缩算法是否合理
- **成本评估**

指标能提示哪里出问题了，但不能解释具体原因。

### 3. Trace 调用树结构

Agent 的执行不是一条线，而是一棵树：
- 一次模型调用产生一个或多个工具调用
- 工具结果进入下一轮模型调用
- 某个工具委派会展开子 Agent 的完整执行过程

**关键字段**：
- `model_call_id`：把模型请求、响应、决策和后续动作关联
- `tool_call_id`：把工具调用和工具结果配对
- `delegation_id`：把子 Agent 的事件挂回父 Agent 的委派节点

有了这些字段，Trace 调用树不需要靠时间顺序来猜。

### 4. 决策归因

**为什么这么做**：模型选择这个工具的原因是什么？它下次还会不会选择这个工具？

**实现方式**：在 system prompt 里加入决策记录规范，让模型在 reasoning 中输出固定格式的决策块：
- 当前目标
- 候选动作
- 最终选择
- 选择原因
- 预期结果

后端解析决策块，生成 `decision` 事件挂到对应的模型调用节点上。

### 5. 任务状态显式化

复杂任务需要单独的任务状态系统：
- **任务状态机**：pending → planning → running → waiting_child → succeeded/failed/cancelled
- 每个会话创建 root task
- 调用 `delegate_task` 时创建子 task

这让 Agent 的过程从一串对话事件变成了可查看状态的任务系统。

### 6. 异常检测

**真正危险的是**：连续失败、不能收敛、还在不停执行。

检测规则包括：
- 重复失败
- 接近迭代上限
- 空响应循环
- 压缩频繁
- 未知工具

命中后写入 `anomaly` 事件。

### 7. 评估

三种评估方式：
1. **用户反馈**：点赞/点踩
2. **启发式评估**：会话结束后检查失败信号（无最终回复、高严重度异常、模型调用失败、迭代次数接近上限、工具错误率太高）
3. **LLM-as-judge**：让另一个模型评估 Agent 输出

### 8. 回放与对比

**核心问题**：怎么判断改得有效？

**做法**：拿原来的 user message，带上新的 prompt/工具描述/配置，创建新会话重新跑，然后对比两棵 Trace 调用树：
- 原来失败 4 次，新会话失败 1 次
- 原来触发高风险告警，新会话没有
- 原来评估失败，新会话成功

## 总结

Agent 可观测性八大组件：
1. 日志记录
2. 指标设计
3. 链路追踪（Trace 调用树）
4. 异常告警
5. 决策归因
6. 任务状态
7. 结果评估
8. 回放对比

**核心闭环**：从发现问题 → 定位轨迹 → 修改配置 → 回放对比

→ [[raw/articles/agent-harness-observability-production|原文存档]]