Agent 上线后最可怕的不是报错，而是”看起来在回答，但没人知道它中间干了什么”：调了几次工具、哪一步开始跑偏、token 成本花在哪——全是黑盒。**可观测性负责”看清每一步”，评估负责”判断好不好”**，两者合起来 Agent 才敢持续迭代。本文从零搭一套 trace 埋点 + 黄金集评估 + 线上监控的最小体系。

前置准备

不引重型平台，先用结构化日志实现 trace，评估用 pytest 承载：

pip install pytest openai
mkdir -p agent_eval/cases
  • trace：一次 run 一条 JSONL，内含嵌套 span（llm / tool / memory）
  • 黄金集：cases/*.json，每条含 task、期望要点、禁止行为

步骤一：给 run 加 trace 埋点

用装饰器把每次 LLM 调用与工具调用记成 span：

import json, time, uuid, contextlib

TRACE = open("trace.jsonl", "a", encoding="utf-8")

@contextlib.contextmanager
def span(run_id, kind, name, **extra):
    sid, t0 = uuid.uuid4().hex[:8], time.time()
    rec = {"run": run_id, "span": sid, "kind": kind, "name": name, **extra}
    yield rec
    rec.update(ms=round((time.time()-t0)*1000), ts=time.time())
    TRACE.write(json.dumps(rec, ensure_ascii=False) + "\n")

Agent 主循环里包一层即可：

with span(run_id, "llm", "plan", prompt=prompt) as s:
    decision = llm.chat(prompt)
    s["tokens"] = decision.usage.total_tokens

with span(run_id, "tool", decision.tool) as s:
    result = run_tool(decision)
    s["ok"] = result.ok

步骤二：构建黄金评估集

从线上真实任务里挑 30～50 条，标注”必须做到”和”绝不允许”：

{
  "task": "查询订单 2024-118 的物流状态并告知用户",
  "must": ["调用订单工具", "回复包含物流单号"],
  "must_not": ["编造物流时间", "泄露其他订单信息"]
}

黄金集要持续生长：线上每出一次 bad case，修完后就补进集里防回归。

步骤三：规则 + LLM-as-judge 双判分

规则判硬指标（工具调用序列、must_not），LLM 判软指标（完整性、语气）：

def judge(case, trace, answer):
    hits = [m for m in case["must"] if m in flatten(trace, answer)]
    violations = [m for m in case["must_not"] if m in answer]
    soft = llm.chat(f"按 rubric 给 1-5 分：{case['task']}\n回答：{answer}")
    return {"hard": not violations and len(hits) == len(case["must"]),
            "violations": violations, "soft": soft}

pytest 里每条 case 一个用例，CI 跑全量：改 prompt、换模型、动工具定义，都必须过这道门禁。

步骤四：线上监控与告警

从 trace 聚合四个核心指标进监控面板：

  • 任务成功率：硬判分口径的线上抽样版（每天抽 5% run 跑 judge）
  • 平均步数与重试率：步数突增 = 规划退化或工具不稳
  • token 成本 / run：按 span.kind 拆分，定位是规划烧钱还是汇总烧钱
  • 工具失败率：按 tool name 分组，区分”Agent 笨”和”工具挂”

告警阈值示例：成功率环比降 5 个百分点、p95 步数翻倍即告警。

常见问题

  • trace 数据量太大：span 只记摘要（prompt 哈希 + 首尾 200 字），原文按 run_id 落冷存储
  • LLM judge 不稳定：rubric 写成 checklist、温度设 0、同条跑 3 次取多数
  • 评估集过拟合：只盯着黄金集调 prompt 会换来”应试 Agent”，每月换血 20% case
  • 隐私合规：trace 含用户数据，入库前脱敏，保留期与隐私政策对齐

小结

Agent 的质量工程 = 看得清 + 判得准 + 防得住：trace 把黑盒拆成可查询的 span，黄金集把”好”定义成可执行的断言，监控把退化拦在用户投诉之前。先埋点再谈优化——没有 trace 的 Agent 调优是占卜，有了 trace 和评估门禁，迭代才是一门工程。