观测介绍

背景：从“黑箱”到“透明视图”

在AI应用的开发与部署过程中，请求调用路径往往复杂交错，难以追踪关键节点，导致问题定位困难、性能瓶颈难以发现。为解决这一痛点，观测功能应运而生。

观测功能通过在请求处理的每个关键节点插入探针，自动采集处理时间、调用路径等信息，构建完整的调用链（Trace），并通过可视化界面展示，帮助开发者快速定位问题。

例如，当用户发起请求时，系统会记录从请求开始到最终返回响应的完整路径，并在“调用链详情”页面中展示每个步骤的耗时和状态。

核心能力

观测功能覆盖了以下几类关键数据，帮助开发者和运维人员全面掌握Agent的运行状态：

表1 观测概览
类别	名称	说明
智能体概览	业务指标	展示关键业务指标（如Tokens消耗、Trace数、响应成功率等），监测关键业务表现，及时发现异常趋势，支撑运营决策。
智能体概览	运营指标	聚焦用户使用行为与资源运行情况，提供多维度、可量化、可追踪的运营视图，帮助用户掌握应用实际运行状态，实现资源优化与成本控制。
智能体列表	上报第三方智能体Trace、Metric数据查看第三方智能体上报的Trace、Metric数据	如果您的智能体不是在AgentArts平台开发，可通过观测OpenAPI将其Trace（调用链）和Metric（指标）数据上报至平台，实现统一观测。数据上报：调用观测OpenAPI进行数据上报。接口数据格式遵循OpenTelemetry（OTel）开源标准协议，开发者可使用OTel SDK快速对接。数据查看：上报成功后，前往“智能体列表”页面查看数据。筛选查看：支持筛选“第三方托管”类型的智能体。统一视图：该页面同时展示AgentArts平台创建的智能体与第三方智能体数据，便于统一管理。
调用链分析	调用链分析	记录请求从发起到响应的完整路径，展示各组件的调用顺序、耗时与状态，快速定位性能瓶颈与异常调用，减少故障排查时间。
会话分析	会话分析	记录用户与系统的交互过程信息，深入理解用户行为，提升体验流畅度。
智能体运行分析	智能体运行时	展示高代码智能体的运行状态、更新时间及详细日志，辅助追踪执行流程。
	沙箱工具	展示沙箱工具调用过程中的日志信息，用于排查工具执行异常。
	网关	展示网关在使用过程中产生的日志信息。

基础概念

AgentArts智能体平台为开发者提供了完整的链路请求调用记录的可视化展示，具体包括以下部分：

Trace

一次完整请求的全生命周期记录，呈现了从请求发起到最终返回结果的完整过程。查看调用链详情，请参考查看应用调用链信息。

Span

在Trace中，每一个独立的操作步骤称为一个Span，比如一次模型调用或一个函数调用。Trace中的第一个Span被称为Root Span，它记录着整个请求的开始和结束。而Root Span下的子Span，则用于记录请求执行过程中更具体、更细粒度的操作信息，帮助了解整个流程的详细上下文。

下图是一次请求的完整数据记录，从请求输入到最终返回结果，链路会记录每一个环节的处理信息。

图1 调用链详情

链路信息

“链路信息”页签用于展示选中Span的输入与输出数据，帮助您追踪数据流转过程及排查调用错误。

查看数据流转：在左侧调用树中单击目标Span节点，可在“链路信息”页签查看该节点的具体输入与输出内容。
排查节点报错：如果调用过程中节点发生报错，单击左侧调用树中的报错节点，“链路信息”页签将展示相应的报错详情，便于您快速定位问题根因。

图2 链路信息

元数据

元数据是运行过程中的键值对集合，用于存储运行实例的补充信息，例如应用程序版本、运行环境、调用模型名称或其他需关联的自定义信息。

图3 元数据信息

标注

附加在Span上的自定义信息。可以使用标注对Trace数据进行分类、筛选或标记特殊事件。标注数据支持按场景筛选并回流至评测集，用于对特定场景下的智能体进行定向评估。

例如标记某次对话为“优质回答案例”。通过标注筛选，可以快速构建特定类型的评测数据集，用于后续的智能体效果验证。如何标注请参考人工标注Trace数据。

图4 标注信息

指标

用于反映系统运行的宏观状态和性能健康度，常见类型包括Tokens消耗、请求数、错误数和平均响应时间；您可以通过指标图表查看当前Span的指标。

图5 指标信息

日志

展示当前Span在智能体运行过程中产生的事件记录，包含时间戳与详细内容。在调用链中，日志详细记录了智能体的思考过程、工具调用的原始输入输出信息。作为排查问题的关键依据，当出现异常情况时，您可以通过查看日志快速定位根因。

图6 日志信息

应用场景

场景一：模型调用链路优化

示例问题：调用链路中存在多个耗时环节，导致整体响应时间过长。
解决思路：通过调用链分析功能，可以在“调用链详情”页面中查看每个Span的耗时，定位最长耗时的组件，从而进行优化。例如，发现某个工具调用耗时过长，可进一步分析其输入输出，优化调用逻辑。
处理结果：模型调用链路响应时间缩短，用户体验提升。

场景二：模型输出不符合预期

示例问题：通过旅游智能助手查询南京的博物馆信息，模型调用博物馆推荐工具，但助手返回“未找到该类型景点”。
解决思路：在“调用链详情”页面，通过查看模型节点的Span详细信息，发现模型生成的attraction_type参数为“博物馆”，但博物馆推荐应用预期的入参是“文化机构”，导致应用查询返回异常。
处理结果：优化模型Prompt，调整参数名称为“文化机构”，应用调用成功，返回正确博物馆推荐信息。

场景三：Token消耗异常，成本飙升

示例问题：某智能体Token消耗激增，导致成本失控。
解决思路：调用链分析发现，模型在多次对话中反复调用高成本的长文本生成服务，且未做上下文判断或缓存。
处理结果：通过增加上下文判断逻辑避免重复生成，引入缓存机制复用常见问题答案，并设置调用频率与Token阈值告警，实现成本可控、响应高效、运行稳定的智能体服务。

场景四：智能体评测