AgenticX 可观测性指南:用Prometheus与OpenTelemetry实时监控智能体轨迹

原创2026-10-30 18:03:092,000 阅读

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 流程图用于文档或报告。

Meta-Agent 多智能体协作:每条 Trace 完整覆盖任务、LLM 调用与工具执行的嵌套过程

私有化观测盒: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),实现「智能体自己查自己的轨迹」。

AgenticX 长时运行循环:长时间任务中轨迹与指标持续记录每一步进展

轨迹事后分析:失败定位与瓶颈检测

Trace 落地之后,分析工具把原始数据变成结论。所有分析器都接受 ExecutionTrajectory 作为输入:

分析器 输出 典型用途
TrajectorySummarizer 结构化摘要(可接 LLM 生成叙述) 快速回顾一次运行
FailureAnalyzer 失败报告(错误类型 + 修复建议) 线上故障定责
BottleneckDetector 瓶颈洞察列表 找出耗时最长、重复最多的步骤
PerformanceAnalyzer 综合性能报告 版本间性能对比

配合 DataExporter,轨迹可一键导出为 CSV / JSON,方便离线统计与团队共享。

最佳实践清单

  1. 日志级别要克制:生产用 INFO,调试信息按需临时开启,避免噪音淹没关键事件;
  2. 采样率分级:全量采样用于排查,稳态运行把 AGENTICX_OTEL_SAMPLE_RATE 调低以节省开销;
  3. 控制轨迹内存:用 max_trajectories 限制缓存条数,定期清理历史数据;
  4. 盯住三大指标:任务成功率、响应时延、Token 成本——任何一条劣化都值得深挖对应 Trace;
  5. 失败即分析:任务失败后先跑 FailureAnalyzer,再人工复核,能省掉大量排查时间。

💡 记住:观测不是为了「看」,而是为了让每一次智能体行为可观测、可分析、可优化。从 Prometheus 指标开始,再到 OTel Trace 深入,AgenticX 已经帮你把最难的管道工作做完了——剩下的只是把面板搭起来。

登录后查看全文
AgenticX