TraceGate实战：别被AI Agent的Demo结果给骗了

能跑通Demo并不代表Agent已经准备好上线了。很多时候，Agent给出了正确答案，但背后可能经历了三次工具重试，或者调用LLM时丢失了成本元数据，甚至安全路径根本没被触发。这种“结果正确但过程不可控”的情况，其实就是典型的可观测性缺失。

为了解决这个问题，我研究了TraceGate，它本质上是给AI Agent建立了一套“发布门禁”。通过OpenTelemetry和SigNoz，它在发布前运行场景测试，检查遥测数据是否符合预设的合同（Contract），如果不达标直接拦截发布。

最核心的逻辑是通过YAML定义一套可观测性合同，比如限制最大成本、延迟或工具重试次数。

name: TraceGate AI Agent Release Contract
serviceName: tracegate-demo-agent

budgets:
 maxRunCostUsd: 0.005
 maxP95LatencyMs: 2000
 maxToolRetries: 1

checks:
 - id: span-agent-run
   type: required-span
   spanName: agent.run
   severity: critical

 - id: attr-llm-model
   type: required-attribute
   spanName: llm.call
   attribute: gen_ai.request.model
   severity: critical

如果某个工具（比如 trace.lookup）重试了3次，而合同规定上限是1次，TraceGate就会直接报错并拦截，而不是像传统测试那样只看最终答案是否正确。

在部署这个工作流时，Node.js端的OpenTelemetry配置是关键，需要正确指向OTLP端点：

const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318";

const sdk = new NodeSDK({
 traceExporter: new OTLPTraceExporter({
   url: `${endpoint}/v1/traces`
 }),
 logRecordProcessor: new BatchLogRecordProcessor(
   new OTLPLogExporter({
     url: `${endpoint}/v1/logs`
   })
 ),
 metricReader: new PeriodicExportingMetricReader({
   exporter: new OTLPMetricExporter({
     url: `${endpoint}/v1/metrics`
   }),
   exportIntervalMillis: 1000
 })
});

整个技术栈涵盖了 Vite, React, TypeScript, Node.js 以及 SigNoz。这种从零构建可观测性门禁的思路，对于需要大规模部署AI Agent的团队来说非常实用，能有效避免很多生产环境的诡异Bug。