智能体观测功能提供对AgentX内置智能体运行状态的全链路可观测能力。通过集成高性能观测平台 Langfuse，支持以图形化界面记录智能体的完整执行轨迹、多轮会话聚合分析以及关键性能指标监控，帮助运维人员与开发者快速定位故障、持续优化智能体表现。

功能配置

智能体观测功能默认开启，如需关闭，请按本章节指引完成配置。观测数据遵循只读与审计原则，不对智能体业务逻辑产生侵入影响。

智能体观测功能提供独立的配置文件，用户可按需修改，相关配置项均位于AgentX Server安装目录下的 observation.env（Docker安装包）文件中，重点关注下列配置项即可：

# ENV for Observation
 
# 基础开关
# ====================
# 是否开启智能体观测功能，默认为 true（启用）
OBSERVATION_ENABLED=true

 

...

# 存储配置（ClickHouse）
# ClickHouse 数据库的用户名
CLICKHOUSE_USER=clickhouse
# ClickHouse 数据库的密码
CLICKHOUSE_PASSWORD=clickhouse

 

...

 

# 初始化时创建的管理员用户邮箱
OBSERVATION_INIT_USER_EMAIL=agentx_admin@supermap.com
# 初始化时创建的管理员用户名
OBSERVATION_INIT_USER_NAME=agentx_admin
# 初始化时创建的管理员用户密码
OBSERVATION_INIT_USER_PASSWORD=agentx@2025

 

修改完成后保存文件，执行安装目录下的 startup.sh 脚本，以重启 SuperMap AgentX Server 服务使配置生效。

功能使用

以管理员账户登录SuperMap AgentX Server，依次点击后台管理->智能体观测。在智能体观测模块下，对接Langfuse观测平台的总览仪表盘（Dashboard）、调用链追踪（Traces）、会话聚合分析（Sessions）三大核心视图，分别对自主规划式智能体、知识库问答、工作流式智能体（低代码搭建工作流、智能制图工作流）提供了会话列表追踪（Sessions）与问答追踪（Traces）的能力，点击智能体页面对应按钮可跳转内置Langfuse页面查看观测详情，掌握智能体运行全貌监控与深度下钻分析。

智能体观测功能基于Langfuse观测框架构建。下文是对Langfuse三大核心视图功能与使用场景的简要介绍，帮助您快速掌握智能体观测功能的使用场景。具体使用细节、图表配置方式及高级查询语法，可参考Langfuse官方文档获取更深入的指导。

总览仪表盘（Dashboard）

总览视图以图表形式聚合展示智能体集群的关键运行指标，帮助用户快速掌握整体健康状况与性能趋势。

• 核心指标：实时展示请求总量、错误率、平均响应延迟等核心KPI，支持按时间窗口（1小时、24小时、7天）动态筛选。
• 维度下钻：支持按智能体名称、用户标识、会话ID等维度对指标进行分组聚合，快速定位异常来源。
• 可视化图表：提供折线图（趋势分析）、柱状图（对比分析）及饼图（构成分析）等多种图表类型，满足不同监控场景。
• 使用场景：适用于生产环境日常巡检、性能基准对比、异常突发告警及资源优化评估。

总览界面中的指标数据与底层追踪记录保持实时同步，用户可通过点击图表区域快速跳转至对应的追踪列表或会话详情。

追踪（Traces）

追踪视图以时间轴形式记录智能体单次请求的全链路执行细节，涵盖从用户输入到最终响应的每一个步骤，包括工具调用、LLM交互（模型调用）、内部逻辑节点等。每个追踪单元可展开查看详细的输入输出、耗时及状态标记。

• 完整执行轨迹：记录智能体运行过程中的所有Span（工作单元）、Generation（模型调用）和Event（事件点），并以树状结构呈现嵌套关系，直观展示决策流程。
• 性能归因分析：每个步骤均标注精确耗时，支持按耗时排序，快速定位长耗时节点或异常工具调用。
• 高级筛选与检索：列表页支持按时间范围、智能体类型、会话ID、标签、状态（成功/失败）等条件精细化筛选。支持全文检索输入输出内容，快速定位特定语义的追踪记录。
• 数据复现能力：记录版本标签、请求载荷等元数据，为问题复现与版本对比提供可靠依据。
• 典型场景：调试智能体异常行为、分析工具调用链性能瓶颈、对比不同版本智能体表现、审计关键请求的完整输入输出。

在追踪列表中，用户可通过点击任意追踪记录进入详情页，查看每一步的详细输入输出、模型参数、错误堆栈等信息。详情页支持ChatML、Markdown、JSON等多种格式内容的友好渲染。

会话（Sessions）

会话视图将同一用户或同一业务过程中产生的多次追踪记录聚合为完整的对话维度，帮助分析多轮交互场景下的用户体验与智能体响应质量。

• 跨请求聚合：自动将属于同一会话（基于会话标识）的多个追踪记录进行分组，形成连贯的会话时间线，还原完整对话流程。
• 会话级指标：提供会话总耗时、总交互轮数、聚合状态（成功/部分失败）等摘要信息，支持按会话时长、轮数、创建时间等排序与筛选。
• 逐轮重放与上下文：支持按时间顺序展示会话内每一次交互的输入、输出及中间调用细节，便于复盘用户意图变化及智能体决策演变。
• 人工评分与协作：支持通过界面为会话添加质量评分（如满意度、准确性）或标记书签，评分结果可作用于后续模型优化。同时可生成公开分享链接，便于团队协作评审或向客户支持人员提供上下文。
• 使用场景：用户体验分析、人工标注数据集准备、合规审计对话追溯、复杂多轮故障的根因定位。

会话列表提供简要摘要预览，点击任一会话可进入详情页查看完整的对话时间线、关联追踪列表及聚合指标，并支持一键跳转至具体追踪记录。