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 会循环、有工具、能管上下文、有记忆、能查知识、会协作、能被评测、可观测算账——功能上已经是个成熟选手了。但还差最后、也是最容易被忽视的一环:它安全吗?能扛住恶意用户吗?出故障了会不会把整个系统拖垮?

下一篇预告(完结篇)——《安全与生产化:让 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