Agent开发完全实战指南(九)可观测性与成本
上一篇结尾埋了个雷:评测里冒出两个新指标——花了多少 token、多久出结果。
这不是小事。真实故事:某团队的 Agent 上线后没人盯着,一个逻辑 bug 让它陷入工具调用死循环,一个周末烧掉了小几万块 API 费用,周一才发现。还有更常见的:用户抱怨"你这 Agent 怎么这么慢",你却答不上来到底慢在哪一步——是 LLM 慢、工具慢、还是循环转了太多轮?
单 Agent 已经够难追踪,多 Agent(第 07 篇)更是一团乱麻:主 Agent 派了 5 个子 Agent,每个又调了若干工具和 LLM,出问题时你面对的是一片黑盒。
可观测性的一句话概括:把 Agent 每一步(每次 LLM 调用、每个工具执行、每层子 Agent)都记录成可追溯的 trace,配上 token 和成本埋点——让「它到底干了啥、花了多少钱、卡在哪」从黑盒变成一块随时能看的仪表盘。
一、Agent 为什么比普通服务更难观测
普通 Web 服务,一个请求进来、一个响应出去,加个日志就差不多了。Agent 不一样:一个用户请求背后是一串嵌套的、动态的调用。
flowchart TD
U[用户一个问题] --> A[Agent 循环]
A --> L1[LLM 调用 1
决定调工具]
A --> T1[工具: 查数据库]
A --> L2[LLM 调用 2
看结果再决定]
A --> T2[工具: 调 API]
A --> L3[LLM 调用 3
生成最终答案]
A --> Sub[子 Agent
又是一整套嵌套调用]一个请求可能触发 3 次 LLM 调用、4 个工具、2 个子 Agent。出问题时,你得知道是哪一环、传了什么、花了多久、烧了多少 token。 一坨扁平日志根本理不清这种嵌套关系——你需要的是 trace。
二、三个核心概念:Trace、Span、Metrics
可观测性的行话就三个,一次讲清:
| 概念 | 是什么 | 类比 |
|---|---|---|
| Trace(链路) | 一个完整请求的全过程记录 | 一次快递从下单到签收的完整物流 |
| Span(跨度) | trace 里的一个步骤,可嵌套 | 物流里的每个节点(揽收/运输/派送) |
| Metrics(指标) | 可聚合的数字(token、耗时、成本、成功率) | 快递公司的日均时效、破损率 |
一个 Agent trace 长这样:根 span 是整个请求,下面挂着「LLM 调用」「工具执行」「子 Agent」等子 span,每个 span 记录开始/结束时间、输入输出、token、状态。
关键洞察:Agent 可观测性的核心是「树状 trace」——用父子 span 还原调用的嵌套结构。有了它,多 Agent 的一团乱麻才能被摊开成一棵能点开看的树。
三、要埋哪些点
别乱埋。一个生产 Agent,至少埋这几类:
| 埋点位置 | 记录什么 | 为什么 |
|---|---|---|
| 每次 LLM 调用 | 模型、prompt tokens、completion tokens、耗时 | 成本和延迟大头都在这 |
| 每个工具调用 | 工具名、入参、结果、耗时、成功/失败 | 定位慢工具、错误工具 |
| 每轮循环 | 第几轮、finish_reason | 抓死循环、看收敛速度 |
| 每个子 Agent | 子任务、嵌套 trace | 还原多 Agent 结构 |
| 整个请求 | 总 token、总成本、总耗时、最终状态 | 算总账、看 SLA |
四、动手:给 Agent 加一套 trace + 成本核算
我们做一个离线可跑的最小可观测层:一个 Tracer 收集嵌套 span,每个 LLM span 记录 token,最后按模型价格算出总成本、打印出 trace 树。
4.1 Span 与 Tracer 的数据结构
// Span 一个步骤的记录,可嵌套
type Span struct {
Name string
Kind string // "llm" | "tool" | "agent"
Start time.Time
Duration time.Duration
PromptTok int // LLM 输入 token
CompTok int // LLM 输出 token
Model string // LLM span 才有
Status string // "ok" | "error"
Children []*Span
}
// Tracer 收集一次请求的所有 span,维护父子关系
type Tracer struct {
root *Span
stack []*Span // 当前打开的 span 栈,栈顶是当前父节点
}
4.2 开启 / 结束 span
用一个栈维护嵌套:Begin 压栈并挂到父节点下,End 出栈并记录耗时:
func NewTracer(rootName string) *Tracer {
root := &Span{Name: rootName, Kind: "agent", Start: time.Now(), Status: "ok"}
return &Tracer{root: root, stack: []*Span{root}}
}
// Begin 开一个子 span,成为当前父节点
func (t *Tracer) Begin(name, kind string) *Span {
s := &Span{Name: name, Kind: kind, Start: time.Now(), Status: "ok"}
parent := t.stack[len(t.stack)-1]
parent.Children = append(parent.Children, s)
t.stack = append(t.stack, s)
return s
}
// End 结束当前 span,出栈
func (t *Tracer) End() {
s := t.stack[len(t.stack)-1]
s.Duration = time.Since(s.Start)
if len(t.stack) > 1 {
t.stack = t.stack[:len(t.stack)-1]
}
}
// Finish 收尾根 span
func (t *Tracer) Finish() {
t.root.Duration = time.Since(t.root.Start)
}
4.3 成本核算:按模型价格把 token 换算成钱
token 不算钱就等于没管成本。 不同模型、输入输出单价不同,维护一张价格表逐 span 累加:
// Price 每百万 token 的价格(美元),输入输出分开计价
type Price struct{ InPerM, OutPerM float64 }
// 价格表(示意,以你网关实际价格为准)
var priceTable = map[string]Price{
"gpt-5.4-mini": {InPerM: 0.15, OutPerM: 0.60},
"gpt-5.4": {InPerM: 2.50, OutPerM: 10.00},
"qwen3.6-plus": {InPerM: 0.40, OutPerM: 1.20},
}
// costOf 算单个 LLM span 的成本
func costOf(s *Span) float64 {
p, ok := priceTable[s.Model]
if !ok {
return 0
}
return float64(s.PromptTok)/1e6*p.InPerM + float64(s.CompTok)/1e6*p.OutPerM
}
// walk 递归汇总整棵 trace 的 token 和成本
func walk(s *Span) (totalTok int, totalCost float64) {
totalTok = s.PromptTok + s.CompTok
totalCost = costOf(s)
for _, c := range s.Children {
tok, cost := walk(c)
totalTok += tok
totalCost += cost
}
return
}
关键洞察:成本核算必须按「输入/输出分开计价、按具体模型查表」来算,因为输出 token 通常比输入贵好几倍,不同模型差一个数量级。笼统地「token × 单价」会把账算错。
4.4 打印 trace 树 + 总账
// printTree 缩进打印 trace 树,直观看到嵌套和每步耗时/成本
func printTree(s *Span, depth int) {
indent := strings.Repeat(" ", depth)
line := fmt.Sprintf("%s- [%s] %s (%v)", indent, s.Kind, s.Name, s.Duration.Round(time.Millisecond))
if s.Kind == "llm" {
line += fmt.Sprintf(" tokens=%d+%d $%.5f", s.PromptTok, s.CompTok, costOf(s))
}
fmt.Println(line)
for _, c := range s.Children {
printTree(c, depth+1)
}
}
在 main 里模拟一次带工具、带子 Agent 的请求,跑完打印出树和总账。完整代码见 code/09-observability/,离线可跑。
五、别自己造轮子:生产用现成的
上面是为了讲清原理手搓的。生产环境别自己维护 span 栈,用标准协议和现成平台:
| 方案 | 是什么 | 适用 |
|---|---|---|
| OpenTelemetry (OTel) | 可观测性的行业标准协议,语言无关 | 想接入现有监控体系(Grafana/Jaeger) |
| Langfuse | 专为 LLM 应用做的开源 tracing 平台 | 想要开箱即用的 LLM trace UI + 成本看板 |
| LangSmith | LangChain 家的托管观测 + 评测平台 | 已用 LangChain 生态 |
| Helicone / Phoenix | LLM 网关观测 / 开源可观测 | 按需选型 |
关键洞察:手搓 tracer 是为了理解原理。真上生产,直接用 OpenTelemetry 打标准 span、或接 Langfuse——它们已经解决了嵌套、采样、持久化、可视化、告警这一整套麻烦事。
六、决策指南:可观测性怎么起步
| 你的处境 | 建议 |
|---|---|
| 刚做 demo,还没上线 | 先在每次 LLM 调用打日志记 token,够用 |
| 准备上生产 | 上 trace(OTel 或 Langfuse),至少覆盖 LLM + 工具 |
| 多 Agent 系统 | 必须上树状 trace,否则出问题无从查起 |
| 成本敏感 / 老板要看账 | 加成本埋点 + 按天/按用户聚合看板 |
| 已有监控体系(Prometheus/Grafana) | 用 OpenTelemetry 对接,别另起炉灶 |
| 想省事、快速看 LLM trace | 直接接 Langfuse,开箱即用 |
七、常见坑速查
| 坑 | 后果 | 正确做法 |
|---|---|---|
| 只打扁平日志 | 理不清嵌套调用 | 用树状 trace(父子 span) |
| token 不算成本 | 半夜烧钱无感知 | 按模型价格表逐调用核算 |
| 输入输出 token 混着算 | 成本算错 | 分开计价(输出通常贵几倍) |
| 不设成本/循环告警 | 死循环烧钱到周一才发现 | 设预算阈值和最大轮数告警 |
| 把完整 prompt 全存下来 | 存储爆炸、可能泄密 | 采样 + 脱敏,长文本截断 |
| 生产还手搓 tracer | 重复造轮子、不稳 | 用 OTel / Langfuse |
八、小结与下一篇
- Agent 的调用是嵌套、动态的,普通日志理不清,需要树状 trace。
- 三个概念:Trace(整个请求)、Span(每一步,可嵌套)、Metrics(可聚合指标)。
- 至少埋点:每次 LLM 调用、每个工具、每轮循环、每个子 Agent、整个请求。
- 成本核算要按模型、输入输出分开计价,并设预算/循环告警防止烧钱。
- 手搓是为理解原理,生产直接用 OpenTelemetry / Langfuse。
到这里,我们的 Agent 会循环、有工具、能管上下文、有记忆、能查知识、会协作、能被评测、可观测算账——功能上已经是个成熟选手了。但还差最后、也是最容易被忽视的一环:它安全吗?能扛住恶意用户吗?出故障了会不会把整个系统拖垮?
下一篇预告(完结篇)——《安全与生产化:让 Agent 扛得住真实世界的恶意与故障》:我们会讲透 prompt injection(提示词注入)攻防、工具权限与沙箱、输入输出护栏(guardrails)、故障降级与限流、灰度发布。把前九篇的能力,真正加固成一个敢放到生产环境、敢面对真实用户的系统。
参考资料
| 资料 | 来源 |
|---|---|
| OpenTelemetry(可观测性标准协议) | opentelemetry.io |
| Langfuse(开源 LLM 可观测平台) | langfuse.com |
| OpenTelemetry GenAI 语义约定 | opentelemetry.io/docs/specs/semconv/gen-ai |
| OpenAI 定价(成本核算参考) | openai.com/api/pricing |