# Agent 节省工时看板，要在 Agent 上线前开始搭

> Trace 能告诉你 Agent 完成了多少任务，但财务只认与上线前实测的人工基线对比出的节省工时。

原文: https://fdetimes.net/zh/guides/agent-hours-saved-dashboard-baseline/

你可以守着一个装满 Trace 的 Langfuse 实例，却仍然答不出客户 CFO 唯一关心的问题：这个 Agent 到底省了多少小时的工作？Trace 记录的是 Agent 做了什么，不记录人工完成同样的事过去要花多长时间。

Fiddler 在关于 Agent ROI 计算器的指南里说得很直接：Agent 上线前，先测量现有流程的基线。它还指出，财务团队不信估算，只信实测出来的差值。

因此，节省工时看板其实是两项测量的结合：一张上线前采集的人工计时表，加上一个上线后由 Trace 驱动的计数器。

本指南会搭建这个计数器，把它与基线关联起来，再把结果放到按客户划分的看板上。代码经过**简化**：Span 导出格式是假设的 JSONL 结构，示例中的所有数字都只作说明之用。

## 需要准备什么？

你需要一个按 OpenTelemetry GenAI 约定完成埋点的 Agent，可以导出到文件或已经存进 Langfuse 的 Trace，以及 Python 3。最重要的前提不在你的电脑上：你得获准坐在执行人工流程的人旁边，给他们计时。

MetaCTO 在一篇讨论上线前后该测什么的文章中建议：建立不了基线的团队仍然可以做试点，但暂时不该谈 ROI。如果客户不让你测，就从第一天起把项目叫作试点。

## 第 1 步：人工实测基线，不要估算

选一种具体的任务类型，比如客服工单分诊。给真正做这件事的人计时，反复多次，取中位数。上线后，继续测量人们审核 Agent 输出仍要花的分钟数，并且每周请客户的经理确认，实际有多少工时被重新分配到了其他工作上。

```python
# baseline.py — 人工测量数据（示意数字）
BASELINE_MIN = {"ticket_triage": 12.0}  # 上线前实测
REVIEW_MIN   = {"ticket_triage": 3.0}   # 上线后实测，不是猜的
# 客户经理确认每周转投到其他工作的工时
REDEPLOYED_H = {("ticket_triage", "week_1"): 45.0}
```

**检查：**每个数字都必须能追溯到一次注明日期的测量或确认，并有具名负责人。如果你答不出“这个 12 是哪来的？”，它就是估算，财务不会信。

## 第 2 步：属性名集中放在一处

正如 Dash0 的解读文章所说，`gen_ai.*` 属性目前仍处于 Development 稳定性阶段：属性名可能改变，Span 结构也可能调整。不要把这些字符串散落在代码各处。

```python
# semconv.py — 所有 gen_ai.* 名称只放在这里
AGENT_SPAN = "invoke_agent"
TOOL_SPAN  = "execute_tool"
IN_TOK     = "gen_ai.usage.input_tokens"
OUT_TOK    = "gen_ai.usage.output_tokens"
TASK_TYPE  = "app.task_type"    # 自定义属性，不属于标准
CUSTOMER   = "app.customer_id"  # 自定义
```

**检查：**运行 `grep -r "gen_ai\." .` 应该只返回一个文件。埋点库的版本也要锁定，免得约定在两次部署之间悄悄变化。

## 第 3 步：一个任务就是一个根 invoke_agent

按 GenAI 约定，每次 Agent 运行是一个 `invoke_agent` Span，子 Agent 则以另一个 `invoke_agent` Span 的形式嵌套在内。如果把每个 `invoke_agent` Span 都算上，一个带三个子 Agent 的任务就变成了四个任务。只有最外层的 Span 才是任务。

```python
import json
from semconv import AGENT_SPAN, TOOL_SPAN, IN_TOK, OUT_TOK

spans = [json.loads(l) for l in open("spans.jsonl")]  # 简化格式
by_id = {s["span_id"]: s for s in spans}

def is_agent(s):
    return s["name"].startswith(AGENT_SPAN)

# 简化写法：每个 Span 都向上走到根，开销为 O(树深度)
def root_agent(s):
    top = s if is_agent(s) else None
    p = by_id.get(s.get("parent_id"))
    while p:
        if is_agent(p):
            top = p
        p = by_id.get(p.get("parent_id"))
    return top
```

这个循环易读，但 Trace 很大、树很深时，应按 `span_id` 缓存根节点，让每条分支只遍历一次。

每次工具调用（包括通过 MCP 的调用）都是一个 `execute_tool` Span。据此可以统计每个任务中的自动化步骤数，把两个 usage 属性相加则得到 Token 成本。

```python
from collections import defaultdict
tasks = defaultdict(lambda: {"tools": 0, "tok": 0})
for s in spans:
    r = root_agent(s)
    if not r:
        continue
    t = tasks[r["span_id"]]
    if s["name"].startswith(TOOL_SPAN):
        t["tools"] += 1
    a = s.get("attributes", {})
    t["tok"] += a.get(IN_TOK, 0) + a.get(OUT_TOK, 0)
```

**检查：**取一天的 Trace，把根任务数与客户自己系统中的工单数对比。差距很大，说明 Span 的父子关联有误，下游所有数字也都跟着错了。

## 第 4 步：被审核吃掉的工时不算节省

Fiddler 的公式很简单：每周节省工时 × 平均综合时薪 × 52 周。附带的条件是，只有真正转投到其他工作的工时才算数。MetaCTO 的提醒思路相同：如果新增的审核工作量把 132 小时全部吃掉了，就不要声称 Agent 省下了 132 小时。

别把这条规则留在幻灯片上，要写进脚本，让计入的数字永远不会超过客户确认的工时。

```python
from baseline import BASELINE_MIN, REVIEW_MIN, REDEPLOYED_H

def weekly_hours(n_tasks, task_type, week):
    gross = n_tasks * BASELINE_MIN[task_type] / 60
    net = n_tasks * (BASELINE_MIN[task_type] - REVIEW_MIN[task_type]) / 60
    confirmed = REDEPLOYED_H.get((task_type, week), 0.0)  # 未确认 = 0
    return {"gross": gross, "after_review": net, "counted": min(net, confirmed)}

def annual_value(counted_h, rate):
    return counted_h * rate * 52
```

用示意数字看一周的情况。Agent 处理了 400 张工单，即 400 × 12 / 60 = 80 小时毛工时。每张工单扣除 3 分钟审核，剩下 400 × 9 / 60 = 60 小时。

客户经理只确认有 45 小时被重新分配到其他工作，所以 `counted` 是 45，而不是 60。假设时薪为 40 个货币单位，`annual_value(45, 40)` 得出 45 × 40 × 52 = 93,600。没有确认的那些周，脚本返回的计入工时为 0。

**要点:** 被审核吃掉的工时，不算节省的工时。

**检查：**看板上三个数字都要展示：毛工时、扣除审核后的工时、转投到其他工作的工时。看的人需要知道你扣掉了什么。

## 第 5 步：把成本放在节省旁边

Token 已经在第 3 步汇总好了。乘以客户模型合同中的单价，得到每个任务的成本，并紧挨着人力价值展示。只有收益一栏的看板，在第一次会议上就会被质疑。

再把每个任务的平均工具调用次数加到看板上，作为预警信号。如果任务量持平而这个数字上升，就打开几条 Trace，看看 Agent 是否在循环，因为每个多余的步骤都会增加 Token。

## 第 6 步：搭建按客户划分的看板

如果 Trace 已经在 Langfuse 里，它的自定义看板可以对 Trace、Observation、用户、会话和评分做聚合。它的 Metrics API 支持按名称、模型或用户 ID 分组，并提供多种时间粒度。把用户 ID 设为客户或团队代码，选择按周粒度，就能得到每个客户每周的任务数。

下面的查询只是一个**草图**，展示你发出的问题是什么形态：统计 Trace 数，按用户 ID 分组，按周分桶。字段名经过简化，运行前请对照 Langfuse 文档核实。

```python
# Metrics API 查询草图 — 字段名经过简化，并非准确语法
query = {
    "view": "traces",
    "metrics": [{"measure": "count", "aggregation": "count"}],
    "dimensions": [{"field": "userId"}],          # 每个客户一行
    "timeDimension": {"granularity": "week"},     # 每周一列
    "filters": [{"column": "name", "value": "ticket_triage"}],
}
# 对返回的每一行 (customer, week, n_tasks)：
#   weekly_hours(n_tasks, "ticket_triage", week)
```

乘以基线这一步仍在你的脚本里完成，因为基线是人工实测数据，不在 Trace 中。Langfuse 给出按客户、按周的任务数；`weekly_hours` 把它们换算成计入工时。

**检查：**把某一周所有客户的任务数相加，与第 3 步脚本在同一周统计出的根任务数对比，两者必须一致。

## 数字会在哪里崩掉？

最常见的错误是统计所有 `invoke_agent` Span 而不筛选根任务，任务数随子 Agent 的数量膨胀。其次是用客户凭印象说的“大概”数字，而不是计时测量值。第三个很少有人注意：埋点库升级后属性被改名，Token 计数器悄无声息地掉到零，却没人发现。

这三种错误动摇的都是财务最信任的东西，即实测差值。看板上一旦有一个数字被发现有误，旁边那些正确的数字也会失去可信度。

## 这项技能在客户现场是什么样子？

对前线部署工程师（FDE）来说，基线测量属于项目的第一周，而不是最后一周。在写下第一行 Prompt 之前，就把它作为一个具名事项写进部署计划，并在客户方指定负责人。到了季度复盘，你带去的是实测数字，而不是承诺。

从职业角度看，当岗位描述提到可观测性或向客户证明价值时，面试中就该谈这项技能。简历上不要写“搭建了一个看板”。

要写清楚：上线前测量了基线，从 Trace 中筛选根任务，报告扣除审核时间后的节省工时。一个能在示例 Trace 上运行、附带基线文件的小仓库，比任何描述都更有说服力。

每个 Agent 都会产生 Trace。而客户敢写进明年预算的那个数字，必须在 Agent 运行之前，用秒表测出来。

**本周动手试试:**

- 选一个客户仍在人工处理的流程，计时 20 次，记录每个任务的中位分钟数
- 把代码中所有 gen_ai.* 属性名移到同一个映射文件里
- 在一天的真实 Trace 上运行按根 invoke_agent 统计任务的脚本，并与客户自己的任务数对比

## 信源

- [How To Build an AI Agent ROI Calculator That Finance Actually Trusts](https://www.fiddler.ai/blog/ai-agent-roi-calculator)

- [AI Agent ROI: What to Measure Before and After Launch](https://www.metacto.com/blogs/ai-agent-roi-what-to-measure-before-and-after-launch)

- [OpenTelemetry GenAI semantic conventions explained (Dash0)](https://www.dash0.com/knowledge/opentelemetry-genai-semantic-conventions-explained)

- [Custom Dashboards - Langfuse Docs](https://langfuse.com/docs/metrics/features/custom-dashboards)

- [Custom Metrics API - Langfuse Changelog](https://langfuse.com/changelog/2025-05-12-custom-metrics-api)
