1. 多 Agent 调用链路为什么需要可观测性工程你开一辆没有仪表盘的车不知道速度、油量、水温只能凭感觉踩油门。很多团队管理 Agent 系统就是这个状态任务在跑但没人说得清它为什么快、为什么慢、为什么这个月 Token 账单翻了三倍。Agent 可观测性工程要解决的就是把 Metrics、Traces、Logs 三类信号装进同一块仪表盘让每一次调用都有据可查。我先把场景说清楚。假设你有一个多 Agent 编排Planner 拆解目标Builder 写代码Reviewer 审查Verifier 跑测试。一个 Goal 从进入到交付可能跨 4 个 Agent、十几次模型调用、几十次工具调用。出问题时你面对的是这样的困境整体成功率 87%看起来还行但某个 Skill 只有 62%平均延迟 4.2 秒但 p99 是 89 秒错误率 3.1%可你不知道错误集中在哪个环节。传统微服务的可观测性三支柱在这里需要做一次「Agent 原生映射」。Metrics 是系统脉搏记录任务完成率、延迟分位、Token 消耗、错误率、自进化增益率Traces 是执行地图把 Goal→Plan→Build→Review→Verify→Deliver 串成 Span Tree标出每个环节耗时Logs 是行为记录用 JSON 结构化带上 TraceID、AgentID、Timestamp 和决策快照。三者通过 TraceID 互相关联Metrics 告诉你失败率上升Traces 告诉你是 Reviewer 环节慢了Logs 告诉你 Reviewer 在第三步因为规范问题拒绝了输出。对本地调试来说可观测性让你复现一次失败任务的全过程对线上排障来说它让你在告警触发时直接跳到根因 Span。这篇要交付的是可复制的采集配置和一次端到端验证把仪表盘从概念落到能跑起来的状态。统一 Key 和 API 通道是入口因为所有 Agent 的模型调用都要经过它采集点天然收敛在这里。2. TaoToken 统一 Key 与 API 通道前置准备在动手接采集之前先把调用入口统一。多 Agent 系统最容易乱的地方就是每个 Agent 各自配一套 Key、各自指向不同地址结果 Trace 断链、账单对不上、限流策略没法统一。TaoToken 在这里扮演的是统一入口的角色一个 Key 走所有模型调用Base URL 固定模型 ID 按需切换。你需要准备三样东西我把它叫「三件套」Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面创建建议按环境分 Key本地调试一个、线上一个方便按环境过滤 Trace。Model ID 按你实际用的模型填比如claude-sonnet-4-5或gpt-4o这类具体以文档里的模型列表为准。创建 Key 的入口在这里访问 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys 登录后在控制台生成。生成后立刻复制保存页面刷新后不再完整显示。如果你要跑长期编码或 Agent 任务建议同时了解 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan 它更适合高频、长周期的调用场景。为什么强调统一入口因为可观测性的采集点要收敛。如果每个 Agent 直连不同供应商你就要在每个供应商侧分别埋点Trace 上下文无法跨供应商传播Metrics 口径也不一致。统一走一个 API 通道后你可以在通道层做统一的请求日志、延迟统计、Token 计数Agent 内部只需要透传 TraceID。这里有个容易踩的坑不要把 Key 硬编码进 Agent 的业务代码。用环境变量或配置文件注入本地用.env线上用密钥管理。下面这段是本地调试的最小配置你可以直接抄export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_MODEL_IDclaude-sonnet-4-5配好之后先做一次连通性验证确认通道可用再往下接采集。验证命令curl -sS $TAOTOKEN_BASE_URL/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json | head -c 500返回模型列表就说明 Key 和通道都正常。如果返回 401先检查 Key 是否复制完整、有没有多余空格如果返回连接错误检查 Base URL 是否写成了带路径的地址。这一步过了再进入采集配置。3. 可复制采集配置Metrics、Traces、Logs 三件套这一节是全文的核心我给你三份可直接复制的配置片段分别对应 Metrics、Traces、Logs 的采集。路径和字段名保持和实际一致你按自己的目录调整。先说 Metrics。Agent 系统的核心指标我建议先落五个任务完成率、执行延迟分位、Token 消耗、错误率、自进化增益率。用 OpenTelemetry 的 Metrics SDK 埋点导出到 Prometheus。下面是一个 Node.js 侧的配置片段文件放在observability/metrics.js// observability/metrics.js const { MeterProvider, PeriodicExportingMetricReader } require(opentelemetry/sdk-metrics); const { PrometheusExporter } require(opentelemetry/exporter-prometheus); const exporter new PrometheusExporter({ port: 9464, endpoint: /metrics }); const meterProvider new MeterProvider({ readers: [new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 10000 })], }); const meter meterProvider.getMeter(agent-observability); const taskCounter meter.createCounter(agent_task_total, { description: Agent 任务总数按状态和 Skill 拆分, }); const latencyHistogram meter.createHistogram(agent_task_latency_seconds, { description: 任务执行延迟分布, boundaries: [0.5, 1, 2, 4, 8, 16, 32, 64, 128], }); const tokenCounter meter.createCounter(agent_token_total, { description: Token 消耗总量按 Agent 和模型拆分, }); module.exports { taskCounter, latencyHistogram, tokenCounter };Traces 用 OpenTelemetry 的 Tracer关键是 Span 之间的上下文传播。每个 Goal 生成 Root Span每个 Agent 接手时创建子 Span工具调用创建孙 Span。文件放在observability/tracing.js// observability/tracing.js const { NodeTracerProvider } require(opentelemetry/sdk-trace-node); const { BatchSpanProcessor } require(opentelemetry/sdk-trace-base); const { OTLPTraceExporter } require(opentelemetry/exporter-trace-otlp-http); const { Resource } require(opentelemetry/resources); const provider new NodeTracerProvider({ resource: new Resource({ service.name: agent-orchestrator }), }); provider.addSpanProcessor(new BatchSpanProcessor( new OTLPTraceExporter({ url: http://localhost:4318/v1/traces }) )); provider.register(); const tracer provider.getTracer(agent-tracing); function startGoalSpan(goalId) { return tracer.startSpan(goal.execute, { attributes: { goal.id: goalId, agent.role: coordinator }, }); } function startAgentSpan(parentCtx, agentId, skillId) { return tracer.startSpan(agent.execute, { attributes: { agent.id: agentId, skill.id: skillId }, }, parentCtx); } module.exports { tracer, startGoalSpan, startAgentSpan };Logs 用 JSON 结构化每条日志必须带 TraceID、GoalID、AgentID、Timestamp 和决策快照。文件放在observability/logger.js// observability/logger.js const pino require(pino); const logger pino({ level: process.env.LOG_LEVEL || info, formatters: { level: (label) ({ level: label }), }, timestamp: pino.stdTimeFunctions.isoTime, }); function agentLog({ traceId, goalId, agentId, skillId, event, decisionSnapshot, latencyMs }) { logger.info({ trace_id: traceId, goal_id: goalId, agent_id: agentId, skill_id: skillId, event, decision_snapshot: decisionSnapshot, latency_ms: latencyMs, }); } module.exports { logger, agentLog };三份配置的关联点就是 TraceID。你在 Agent 入口处从请求头或上下文里取出 TraceID一路透传到 Metrics 的标签、Logs 的字段。这样在 Grafana 里点开一个异常 Trace就能直接跳到对应的日志行和指标曲线。采集端建议用 OpenTelemetry Collector 做汇聚配置放在otel-collector-config.yamlreceivers: otlp: protocols: http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 5s exporters: prometheus: endpoint: 0.0.0.0:8889 otlphttp/jaeger: endpoint: http://localhost:4318 loki: endpoint: http://localhost:3100/loki/api/v1/push service: pipelines: metrics: receivers: [otlp] processors: [batch] exporters: [prometheus] traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/jaeger] logs: receivers: [otlp] processors: [batch] exporters: [loki]这套配置跑起来后Metrics 进 PrometheusTraces 进 JaegerLogs 进 LokiGrafana 统一展示。如果你用 Claude Code 做本地开发可以在 settings 里把模型调用指向统一通道配置片段如下路径按你的实际 settings 文件位置放{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意 Base URL、Key、Model ID 三件套要写全缺一个都会导致调用失败。Cline 的 MCP 配置同理在 MCP 服务器配置里把模型通道指向统一地址Key 用环境变量注入不要写死在 JSON 里。4. 端到端验证一次请求跑通三类信号配置写完不算完要跑一次端到端验证确认三类信号都能采到、能关联。我给你一个最小验证脚本模拟一个 Goal 从进入到交付的完整链路文件放在scripts/verify-observability.js// scripts/verify-observability.js const { startGoalSpan, startAgentSpan } require(../observability/tracing); const { taskCounter, latencyHistogram, tokenCounter } require(../observability/metrics); const { agentLog } require(../observability/logger); async function runGoal(goalId) { const start Date.now(); const goalSpan startGoalSpan(goalId); const agents [planner, builder, reviewer, verifier]; for (const agentId of agents) { const agentStart Date.now(); const agentSpan startAgentSpan(goalSpan.spanContext(), agentId, skill_${agentId}); // 模拟模型调用 const resp await fetch(${process.env.TAOTOKEN_BASE_URL}/v1/messages, { method: POST, headers: { Authorization: Bearer ${process.env.TAOTOKEN_API_KEY}, Content-Type: application/json, }, body: JSON.stringify({ model: process.env.TAOTOKEN_MODEL_ID, max_tokens: 256, messages: [{ role: user, content: 你是 ${agentId}请返回一行确认。 }], }), }); const data await resp.json(); const latency (Date.now() - agentStart) / 1000; agentLog({ traceId: agentSpan.spanContext().traceId, goalId, agentId, skillId: skill_${agentId}, event: agent.completed, decisionSnapshot: { model: process.env.TAOTOKEN_MODEL_ID, stop_reason: data.stop_reason }, latencyMs: latency * 1000, }); taskCounter.add(1, { agent: agentId, status: success }); latencyHistogram.record(latency, { agent: agentId }); tokenCounter.add(data.usage?.output_tokens || 0, { agent: agentId, model: process.env.TAOTOKEN_MODEL_ID }); agentSpan.end(); } goalSpan.end(); console.log(Goal ${goalId} 完成总耗时 ${(Date.now() - start) / 1000}s); } runGoal(goal-verify-001).catch(console.error);跑之前先启动 Collector 和 Prometheus然后执行node scripts/verify-observability.js预期结果分三处验证。第一控制台输出Goal goal-verify-001 完成总耗时 Xs说明链路跑通。第二访问http://localhost:9464/metrics能看到agent_task_total、agent_task_latency_seconds、agent_token_total三个指标且标签里有 agent 维度。第三打开 Jaeger UI搜索 serviceagent-orchestrator能看到一个goal.execute的 Root Span下面挂着四个agent.execute子 Span每个子 Span 有耗时和属性。Logs 侧去 Loki 查{service_nameagent-orchestrator}应该看到四条 JSON 日志每条都有trace_id、goal_id、agent_id、decision_snapshot。拿其中一条的trace_id去 Jaeger 搜能定位到对应的 Trace拿goal_id去 Metrics 过滤能看到这个 Goal 贡献的计数。三类信号通过 TraceID 和 GoalID 串起来仪表盘就活了。如果你要验证模型对话侧的连通性可以访问 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels 做一次对话测试确认通道和模型都正常。这一步和采集验证分开做避免把通道问题和采集问题混在一起排查。5. 常见报错排查401、local proxy failed、reading choices、OAuth接入过程中有几类报错出现频率最高我按实际遇到的顺序列出来对照着查。第一类401 Unauthorized。报错长这样{error:{type:authentication_error,message:invalid api key}}。原因通常是 Key 复制不完整、带了空格、或者环境变量没生效。排查步骤先echo $TAOTOKEN_API_KEY确认变量有值且无空格再用 curl 直接带 Key 请求/v1/models排除代码层问题如果 curl 也 401去控制台重新生成 Key。注意 Key 只在创建时完整显示一次页面刷新后看不全别拿截断的 Key 去试。第二类local proxy failed。报错类似Error: connect ECONNREFUSED 127.0.0.1:4318或local proxy failed to forward request。这是采集侧的问题不是模型通道的问题。原因通常是 OpenTelemetry Collector 没启动或者端口被占用。排查lsof -i :4318看端口占用docker ps看 Collector 容器是否在跑。如果 Collector 没起先起 Collector 再跑验证脚本。注意区分模型调用走https://taotoken.net/api采集上报走本地localhost:4318两者不要混。第三类reading choices。报错类似Cannot read properties of undefined (reading choices)。这是解析响应时字段路径不对。不同模型的响应结构不一样有的返回choices有的返回content数组。排查先把原始响应console.log(JSON.stringify(data))打出来看清楚结构再取字段。如果你用的是 Anthropic 风格接口取data.content[0].text如果是 OpenAI 风格取data.choices[0].message.content。别照抄网上的解析代码按实际响应改。第四类OAuth 相关报错。报错类似OAuth token expired或invalid_grant。如果你用的是 Claude Code 这类带 OAuth 流程的工具注意 OAuth token 和 API Key 是两套东西。OAuth 过期就重新走授权流程API Key 过期就去控制台重新生成。排查时先确认你用的是哪种认证方式别把 API Key 塞进 OAuth 的字段里。Claude Code 的配置里ANTHROPIC_API_KEY和 OAuth 是互斥的配了 Key 就走 Key 认证。第五类Trace 断链。现象是 Jaeger 里只看到孤立的 Span没有父子关系。原因是上下文没透传。排查检查startAgentSpan的第二个参数是不是父 Span 的spanContext()检查跨进程调用时有没有把 TraceID 放进请求头。跨 Agent 调用时把traceparent头带上接收侧从头部解析出上下文再创建子 Span。第六类Metrics 标签爆炸。现象是 Prometheus 里agent_task_total的标签组合过多查询变慢。原因是把goal_id这种高基数维度打进了标签。排查goal_id、trace_id这类唯一值不要做 Metrics 标签它们属于 Traces 和 Logs 的领域。Metrics 标签只保留 agent、skill、status、model 这类有限枚举。把这几类排完你的采集链路基本就稳了。如果还有通道层的疑问接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 里面有各语言的调用示例和字段说明。6. 把仪表盘用起来从看见到行动配置跑通只是起点仪表盘的价值在于用起来。我给你三个实际用法。第一个用法按 Skill 拆分完成率。整体完成率 87% 会掩盖问题按 Skill 拆开看可能发现「数据库操作」类只有 62%。这个信号直接指向需要优化的 Skill而不是笼统地说「系统不够好」。在 Prometheus 里用sum by (skill) (rate(agent_task_total{statussuccess}[1h])) / sum by (skill) (rate(agent_task_total[1h]))就能算出分 Skill 成功率。第二个用法用 Trace 定位瓶颈。延迟 p99 高的时候去 Jaeger 找最慢的几个 Trace看时间花在哪个 Span。我试过的一个典型情况是37% 的执行时间花在等待工具响应上Agent 在干等。这个瓶颈在没有 Tracing 之前完全隐形因为从外部看 Agent 一直在「运行中」。定位到之后做工具预加载、异步 Pipeline、连接池等待时间从 10.6 秒降到 4.1 秒。第三个用法用 Logs 的决策快照做回溯。Agent 为什么拒绝了某个输出去 Logs 里找decision_snapshot字段里面有当时的模型、stop_reason 和推理依据。这比事后猜要靠谱得多。长期积累下来这些日志还能汇入进化数据管道成为 Skill 优化的语料。告警策略建议分三层静态阈值兜底动态基线做主关联模式做深。静态阈值比如错误率超过 10% 告警动态基线按 Skill 类型和时段分别算关联模式监控指标之间的关系比如某个 Skill 刚完成优化但完成率反而下降这是进化走偏的信号应该自动回滚。第三层最有价值也最容易被忽略。最后说一句实操建议先把 Metrics 和 Logs 跑起来Traces 可以稍后接。因为 Metrics 给你全局视图Logs 给你细节Traces 给你链路。三者都重要但落地顺序上先有全局再抠细节比一上来就追完整链路更容易坚持。等三类信号都稳了再考虑接 Grafana 做统一面板把任务总览、延迟分布、Token 趋势、Agent 健康矩阵、自进化面板放到一屏里。到那时你的 Agent 系统才算真正装上了仪表盘。