Posts

Agent 评测与可观测性术语地图：从 Eval、Trace 到 Replay

Agent 评测领域最容易造成误解的，不是某个指标怎么算，而是同一个词在不同框架里常常指向不同层级。

有人把一次模型调用叫 Run，有人把整个工作流叫 Run；有人说 Replay，实际只是重新发送 prompt；有人把 Trace 当日志，也有人把它当成一棵有父子关系、可以定位耗时与错误的执行树。术语没有先对齐，评测报告里的“成功率 95%”“支持恢复”“全链路可追踪”就很难验证。

这篇文章不按字母顺序背词典，而是沿着一条完整链路解释这些概念：Agent 怎样运行，怎样留下证据，怎样用数据集和评估器打分，又怎样把失败样本变成回归测试。

先看全局：一次运行如何变成一次评测

Dataset 中的一条 Case
        │ 输入 + 可选 Ground Truth
        ▼
Workflow 启动一个 Run
        │
        ├── Span：模型调用
        ├── Span：Tool Call
        ├── Span：Guardrail 检查
        ├── Checkpoint：保存 State
        └── HITL：暂停并等待人工决定
        │
        ▼
Trace：串起本次执行的完整证据
        │
        ├── Evaluator 打分
        ├── Offline Eval 批量比较
        ├── Online Eval 生产监控
        └── Replay / Regression Eval 复现与防回退

这里可以先记住三句话：

read more
Posts

不仅是日志：构建企业级 Agent 的全链路可观测性

不仅是日志：构建企业级 Agent 的全链路可观测性

在企业级应用中，Agent 不再是一个黑盒模型，而是一个需要被持续审视的决策系统。如果 Agent 的决策链路不可见，其执行失控的风险将成倍增加。

1. 可观测性的分层设计

我们必须将 Agent 的运行视为三个不同维度的流：

  • 执行层 (Action Layer)：系统指标（CPU/内存/网络/IO）。这是最底层的基础保障，通过 htop/eBPF 等工具获取。
  • 交互层 (Interaction Layer)：MCP 工具调用记录。记录所有 Tool 的输入、输出参数及执行耗时。
  • 认知层 (Cognitive Layer)：模型推理过程。记录 Prompt 上下文、思考过程（Thought）及最终决策逻辑。

2. 三阶段观测策略

企业级 Agent 应在不同生命周期注入观测点：

第一阶段：感知 (Perception)

  • 观测重点：输入清洗后的上下文数据质量。
  • 策略：记录原始 Prompt 到优化后的 Prompt 的转换差值，评估输入信息的信噪比。

第二阶段：决策 (Decision)

  • 观测重点：模型意图与规划路径。
  • 策略：使用“追踪标记” (Tracing Markers) 记录模型在复杂任务分解过程中的逻辑分支。建议将决策链序列化为 JSON 存储，支持后续复盘。

第三阶段：执行 (Execution)

  • 观测重点：工具调用成功率与异常处理。
  • 策略：标准化 MCP 接口。通过 MCP 封装所有外部工具调用，注入拦截器记录 request_id，实现从决策到内核级系统调用的全链路追踪。

3. 企业级参考架构：基于 MCP 的观测流

在复杂环境中，不要直接在 Agent 中硬编码观测逻辑，推荐采用**“旁路观测”**模式：

  1. 接口标准化 (MCP Wrapper)：利用 MCP 协议作为 Agent 与外部世界的标准接口，所有 Tool 调用统一接入该层，自动注入 Correlation-ID。
  2. 异步数据流：观测数据不应同步发送（避免阻塞 Agent 决策）。使用 Unix Domain Socket 将 JSON 格式的指标流实时推送到 Sidecar 进程，由 Sidecar 负责数据的聚合与上报（至 Prometheus/Jaeger）。
  3. 决策快照：在发生错误（如 Tool 返回 Error）时，自动触发“现场快照”，记录当前的 Prompt、工具参数、中间变量、以及系统栈信息，供研发离线回溯。
// 企业级观测接口示例 (标准化 JSON)
{
  "request_id": "req_550e8400-e29b",
  "component": "tool_executor",
  "action": "execute_tool",
  "tool_name": "docker_compose_up",
  "status": "failure",
  "metadata": {
    "latency_ms": 1245,
    "system_load": "0.85",
    "trace_parent": "trace_a9928"
  },
  "error_msg": "Timeout after 1000ms"
}

4. 故障演练：故障降级策略

一旦观测系统检测到异常：

read more