AgenticX 可观测性指南:用Prometheus与OpenTelemetry实时监控智能体轨迹
AgenticX 可观测性指南:用Prometheus与OpenTelemetry实时监控智能体轨迹
AgenticX 是一个面向生产环境的统一多智能体(Multi-Agent)平台,内置完整的可观测性系统。当智能体自主调用工具、编排 LLM、长时间运行时,你一定会关心:任务失败在哪一步?Token 烧了多少?哪个工具在拖慢整体?本指南带你用 Prometheus 导出性能指标、用 OpenTelemetry 追踪智能体执行轨迹,快速搭建一套「实时监控 + 事后分析」的观测能力。
为什么智能体系统需要可观测性
智能体系统是非确定性、多步骤、重工具调用的:同一条指令可能走出不同的执行路径。没有可观测性,线上问题只能靠猜。AgenticX 的可观测性系统(M9 模块)把「看进展、回放过程、算成本、定故障」四类需求全部内置了:
| 观测目标 | AgenticX 提供的能力 | 核心组件 |
|---|---|---|
| 实时看任务进展 | 回调事件流、WebSocket 推送 | CallbackManager、EventStream |
| 事后回放执行过程 | 执行轨迹、Span 树 | TrajectoryCollector、SpanTree |
| 容量与成本规划 | Prometheus 指标(Token、成本、成功率) | MetricsCollector、PrometheusExporter |
| 故障根因定位 | OTel Trace + 失败分析 | OTelCallbackHandler、FailureAnalyzer |
| 性能回归控制 | 基准测试、自动评估 | BenchmarkRunner、AutoEvaluator |
官方完整文档见 docs/guides/observability.md,模块实现位于 agenticx/observability/。
架构总览:两层观测,各管一段
AgenticX 把观测拆成两层,各司其职:
- Studio / 对话运行时层:面向聊天场景,产出 Token 流式、工具轮次、确认门、子智能体事件(
EventType/RuntimeEvent),适合做实时 UX 监控; - 任务 / 工作流管线层:即
agenticx.observability模块,提供回调系统、结构化日志、轨迹收集、性能监控与数据导出,适合做系统性监控与离线分析。
两层共享同一套事件模型,指标与 Trace 天然对齐——你在 Prometheus 里看到的异常,能在 OTel Trace 里找到对应的那一次 LLM 调用。
AgenticX 系统架构总览:可观测性系统覆盖智能体运行时的任务、工具与 LLM 调用
最快接入步骤:Prometheus 指标监控
📊 想让智能体的成功率、响应时长、Token 成本出现在你的监控大盘里,只需两步。
第一步:注册监控回调处理器
创建 CallbackManager,把日志、监控、轨迹三类处理器注册进去。智能体运行期间,所有核心事件(任务开始/结束、工具调用、LLM 响应)都会被自动采集为指标:
from agenticx.observability import (
CallbackManager, MonitoringCallbackHandler,
MetricsCollector, TrajectoryCollector, PrometheusExporter,
)
collector = MetricsCollector()
mgr = CallbackManager()
mgr.register_handler(MonitoringCallbackHandler(metrics_collector=collector))
mgr.register_handler(TrajectoryCollector()) # 同时收集执行轨迹
第二步:导出 Prometheus 格式指标
text = PrometheusExporter(collector).export_metrics() # 挂到应用的 /metrics 端点
指标默认遵循 OpenTelemetry GenAI 语义约定(gen_ai.* 与 agenticx.* 命名空间),可切换到旧版 agenticx_* 命名保持向后兼容。覆盖的关键指标包括:
- 任务维度:任务数、成功/失败数、平均与极值耗时;
- 工具维度:调用次数、成功率、平均耗时;
- LLM 维度:调用次数、Token 消耗、累计成本、平均延迟;
- 系统维度:CPU、内存、磁盘(可通过
collect_system_metrics开启周期采样)。
实现细节可参考 agenticx/observability/monitoring.py,完整示例见 examples/m10_observability_demo.py。
用 OpenTelemetry 追踪智能体执行轨迹
🔍 指标回答「有没有问题」,Trace 回答「问题出在哪」。AgenticX 通过 OTelCallbackHandler 把执行事件桥接为标准的 OTel Span,形成清晰的层次结构:
agent_task(根 Span)
├── llm.chat # 每次 LLM 调用
├── tool.call # 每次工具执行
└── llm.chat
设计遵循三条原则:非阻塞(观测不拖慢业务)、低侵入(无需改业务代码,走回调桥接)、标准化(遵循 OpenTelemetry GenAI 语义约定)。
启用 OTel 只需设置环境变量(Studio agx serve 检测到后自动开启,默认关闭):
export AGENTICX_OTEL_ENABLED=true
export AGENTICX_OTEL_ENDPOINT=http://127.0.0.1:4317 # OTLP gRPC 端点
export AGENTICX_OTEL_SERVICE_NAME=my-agent
export AGENTICX_OTEL_SAMPLE_RATE=1.0 # 采样率,生产环境可调低
也可以在代码里调用 enable_otel() 一键启用,配置项定义在 agenticx/observability/otel/config.py。如果需要把 Trace 可视化,OTel Span 还能桥接进 SpanTree,直接生成 Mermaid 流程图用于文档或报告。
私有化观测盒:SigNoz 接收 Trace,Gateway 指标刮取
🏗️ 如果想在本地或私有化现场直接看 Trace,仓库自带一套「默认观测盒」配置,位于 deploy/observability/:
- 接收端:SigNoz,UI 在
http://127.0.0.1:8080,OTLP gRPC 端口4317、HTTP 端口4318,Docker 建议至少 4GB 内存; - 安装:官方自 v0.130.0 起使用
foundryctl+casting.yaml部署,见 deploy/observability/casting.yaml; - Gateway 指标刮取:Go 侧 Gateway 已内置 Prometheus
/metrics(默认宿主机9090端口,源码见 enterprise/apps/gateway/internal/observability/metrics.go)。用现成的 OTel Collector sidecar 刮取后转发到观测盒,一条命令即可启动:
docker compose -f deploy/observability/gateway-scrape/docker-compose.yml up -d
此外,调查类 Agent 可通过只读工具 get_trace / get_logs / get_channel_slo 按关联键取证(设置 AGENTICX_OPS_TOOLS=1 开启,适配器见 agenticx/ops/signoz.py),实现「智能体自己查自己的轨迹」。
轨迹事后分析:失败定位与瓶颈检测
Trace 落地之后,分析工具把原始数据变成结论。所有分析器都接受 ExecutionTrajectory 作为输入:
| 分析器 | 输出 | 典型用途 |
|---|---|---|
TrajectorySummarizer |
结构化摘要(可接 LLM 生成叙述) | 快速回顾一次运行 |
FailureAnalyzer |
失败报告(错误类型 + 修复建议) | 线上故障定责 |
BottleneckDetector |
瓶颈洞察列表 | 找出耗时最长、重复最多的步骤 |
PerformanceAnalyzer |
综合性能报告 | 版本间性能对比 |
配合 DataExporter,轨迹可一键导出为 CSV / JSON,方便离线统计与团队共享。
最佳实践清单
- 日志级别要克制:生产用
INFO,调试信息按需临时开启,避免噪音淹没关键事件; - 采样率分级:全量采样用于排查,稳态运行把
AGENTICX_OTEL_SAMPLE_RATE调低以节省开销; - 控制轨迹内存:用
max_trajectories限制缓存条数,定期清理历史数据; - 盯住三大指标:任务成功率、响应时延、Token 成本——任何一条劣化都值得深挖对应 Trace;
- 失败即分析:任务失败后先跑
FailureAnalyzer,再人工复核,能省掉大量排查时间。
💡 记住:观测不是为了「看」,而是为了让每一次智能体行为可观测、可分析、可优化。从 Prometheus 指标开始,再到 OTel Trace 深入,AgenticX 已经帮你把最难的管道工作做完了——剩下的只是把面板搭起来。

