多数AI智能体的演示仅止于返回最终答案。 我一开始也不例外。一个能回答退款问题、调用保单工具、并绕开注入攻击路径的支持型智能体，在外部观察下一切正常。
接着我问了一个让自己不太舒服的问题：如果这个智能体在生产中出了问题，我能真正知道发生了什么吗？ 那个问题最终变成了TraceGate。
TraceGate是一个为AI智能体设计的发布门控，建立在OpenTelemetry和SigNoz之上。它运行智能体场景，将遥测数据发送到SigNoz，然后检查这次运行是否产生了足够的安全证据，来决定能否安全发布。
AI智能体可以轻松通过演示，却仍然难以调试。一个工具可能要重试3次，最终仍返回成功；一次大模型调用可能在没有任何成本元数据的情况下完成；一个提示注入测试虽然通过了，但根本没留下使用了哪条安全路径的痕迹。这些并非传统意义上的产品缺陷，而是可观测性上的失败。这正是我想让TraceGate捕捉的东西。
核心思路简单：在智能体发布前，它必须满足一份可观测性合约。如果合约检查失败，发布就会被阻断。TraceGate通过一份YAML格式的合约来描述一次安全发布运行应当包含哪些内容。以下是我使用过的合约片段：
合约中定义了服务名称，设置了预算上限：单次运行最大成本0.005美元，P95延迟不超过2000毫秒，工具重试最多1次。然后是一系列检查项：必须有名为agent.run的span（严重级别critical），必须有llm.call的span，在llm.call的span上必须存在gen_ai.request.model这个属性，工具trace.lookup的重试次数不能超过1次。
默认的演示场景故意让其中一个检查失败。trace.lookup工具实际重试了3次，但合约只允许1次重试。这也使演示变得有意义，因为TraceGate并不是假装一切健康，而是直接阻断发布，并解释原因：
TraceGate FAIL
检查通过7/8项
关键失败1项
FAIL retry-budget-trace-lookup — trace.lookup的最差重试次数为3，限制为1。
有了这份输出，团队就能明确知道哪个工具在重试上超过了预算，而不是靠猜测。
技术栈包括Vite、React、TypeScript、Node.js、OpenTelemetry、SigNoz、OpenAI以及YAML合约。整体流程是：场景→智能体执行器→OpenTelemetry→SigNoz→TraceGate合约评估器→通过或阻断。Node执行器运行场景，OpenTelemetry记录span、指标和日志，SigNoz通过OTLP协议接收遥测数据，TraceGate读取运行结果，并与合约进行比对。
对于OpenTelemetry的配置，我使用了OTLP HTTP导出器。关键端点通过环境变量OTEL_EXPORTER_OTLP_ENDPOINT设定，默认为http://localhost:4318。初始化NodeSDK时，分别设置了追踪导出器指向/v1/traces，日志导出器通过BatchLogRecordProcessor和OTLPLogExporter指向/v1/logs，指标读取器则采用周期性导出。
这样一个门控的价值在于，它把“感觉可以发布”变成了“有证据可以发布”。在AI智能体变得越来越自主的今天，单纯靠人的直觉已经不够了。一份可观测性合约就像是代码旁边的那个“防呆”清单——如果你没有记录关键span、没有把模型版本写进属性、或者某个工具频繁重试试图蒙混过关，它就会直接告诉你：现在还不能上线。
热门跟贴