一、背景：AI Agent 的可观测性问题

当下大模型应用快速发展中，智能客服、代码助手、数据分析、内容生成等多种 AI Agent 被部署到生产环境，7×24 小时不间断运行，每天产生数以万计的 LLM 调用。然而，这些 Agent 的运行状态对团队来说往往是一个“黑箱”——调用了哪些模型、消耗了多少 Token、每次对话的具体内容是什么，这些信息很难被有效采集和分析。随之而来的是一系列管理问题：

• 调用量、Token 消耗、成本如何统计？

• 某次回复延迟高，是模型问题还是 Prompt 过长？

• 用户反馈回答异常，如何快速定位到具体的对话轮次？

• System Prompt 是否被修改？工具调用是否正常？

传统 APM 工具擅长监控服务的响应时间、错误率、吞吐量等指标，但它们无法理解 LLM 调用的语义层信息——比如 Prompt 的内容、多轮对话的上下文、工具调用的参数和结果。云舟观测平台的 LLM 监测功能针对这些场景而设计，提供从调用统计到对话回放的完整观测能力。

二、AgentOps 简介

AgentOps 是一个基于 OpenTelemetry 标准的 AI Agent 可观测框架。它的核心设计理念是：不仅采集性能指标（耗时、Token 用量、调用次数），还完整记录每一次人机对话的上下文，包括 System Prompt、用户输入、模型输出、工具调用的参数与返回结果等全链路信息。这些数据通过 OpenTelemetry 协议上报，可与现有的可观测基础设施无缝集成。

云舟观测平台通过集成 AgentOps，提供了AI Agent从数据采集、存储到可视化分析的完整链路。接入过程只需 3 行代码，对业务代码零侵入。

三、兼容性：支持主流 LLM 与 Agent 框架

AgentOps 支持广泛的 LLM Provider 和 Agent 编排框架。无论你的项目使用的是 OpenAI、Anthropic、Google、还是国内的智谱、通义千问等 Provider，AgentOps 均可自动识别并采集数据。在 Agent 框架层面，LangChain、CrewAI、AutoGen 等主流框架均已支持：

agentops.init() 会在初始化时自动扫描已导入的框架，无需额外配置。开发者不需要修改任何业务代码，也不需要手动指定要监控哪个框架。

四、快速接入

Step 1：安装 SDK

pip install agentops

Step 2：配置环境变量

在项目的 .env 文件中添加以下配置。其中 API_KEY 用于身份认证，EXPORTER_ENDPOINT 指向云舟的数据网关地址，API_ENDPOINT 指向 AgentOps 的 API 服务地址：

AGENTOPS_API_KEY="guance-llm-agentops"
AGENTOPS_EXPORTER_ENDPOINT="<数据网关地址>"
AGENTOPS_API_ENDPOINT="<AgentOps API地址>"

Step 3：业务代码接入

from dotenv import load_dotenv
load_dotenv()

import agentops
agentops.init()  # 自动开始采集

不需要修改业务代码，SDK 会自动检测已导入的 LLM 框架并开始采集。如果项目中同时使用了多个框架（如 LangChain + OpenAI），AgentOps 会同时采集所有框架的调用数据，无需分别配置。

五、数据展示

接入完成后，打开云舟观测平台的 LLM 监测页面，即可查看所有 Agent 的调用数据。页面提供了从宏观概览到微观详情的多层次视图。

5.1 Trace 列表

进入「LLM 监测 → 调用链分析(Trace)」页面，可以看到每次 AI 会话的调用记录。列表支持按时间范围、模型、健康状态等条件进行筛选，方便快速定位目标调用：

每条 Trace 记录包含：开始时间、Trace ID、健康状态、Input/Output 摘要、接口名称。点击任意一条即可进入详情页，查看完整的调用链、对话内容和性能数据。

5.2 对话内容回放

对话内容回放是云舟 LLM 监测的核心能力。它解决的核心问题是：当 AI 出现异常回答时，团队能够快速还原当时的完整对话现场，而不是仅仅看到一条报错日志。

点击任意一条 Trace，右侧面板展示该会话的完整对话历史：用户输入、模型输出、System Prompt、工具调用，逐轮呈现。对话以聊天气泡的形式展示，可读性很高，非技术人员也能快速理解每轮对话的内容。以下是一次真实对话回放示例（模型：glm-4.7，5 轮交互，共 8,579 Tokens）：

左侧调用链：

右侧对话的完整内容：

Trace 概览数据：

指标	数值
模型	glm-4.7
Trace 运行时长	4 分 23 秒
LLM 调用次数	5 次（4 次 chat.completion + 1 次 session）
Total Tokens	8,579
错误数	0

5.3 Span 级别的对话关联

每个 Span 对应一次具体的 LLM 调用。点击 Trace 时间线中的不同 Span，右侧会切换展示该次调用的具体对话内容、Token 用量和耗时。这意味着开发者可以精确定位到某一轮对话的具体问题，而不需要在整个会话中逐条翻找。以下对比展示了同一个 Trace 中两个不同 Span 的对话内容：

这种 Span 级别的关联让问题定位可以精确到单次 LLM 调用。典型场景包括：某一轮回复出现幻觉、某次工具调用失败、某个 Span 耗时异常等，都可以直接点击对应 Span 查看上下文。

5.4 回放内容一览

展示内容	价值场景
用户提问	查看用户实际输入了什么，是否有注入攻击或异常输入
AI 回复	完整的 AI 生成内容，便于质量审计和幻觉检测
System Prompt	查看系统提示词是否正确，是否被篡改
工具调用	展示 Available Tools 列表和实际调用情况
多轮对话	完整的上下文链路，看到对话是如何逐步深入的

六、Trace 时间线与性能分析

Trace 详情中的时间线视图以甘特图的形式展示每次 LLM 调用的耗时分布，可以直观看到哪次调用耗时最长、哪些调用之间存在串行等待：

Span	操作	耗时	状态
Session	default.session（父 Span，整个会话）	4m 23s	✅
LLM #1	openai.chat.completion	32.8s	✅
LLM #2	openai.chat.completion	41.3s	✅
LLM #3	openai.chat.completion	22.9s	✅
LLM #4	openai.chat.completion	27.0s	✅

示例：第 2 轮耗时最长（41.3s），因为模型生成了完整的学习路线规划；第 3 轮最快（22.9s），用户仅回复了一句话。这种调用级别的耗时数据，可以帮助团队判断性能瓶颈是出在模型侧（生成慢）还是 Prompt 侧（输入 Token 过多），从而有针对性地优化。

七、总结

云舟观测平台通过集成 AgentOps，为 AI Agent 提供了从调用统计、性能分析到对话回放的全链路可观测能力。接入过程简单，对业务代码零侵入，适用于任何已部署 LLM Agent 的生产环境。

特性	说明
极简接入	3 行代码，5 分钟完成，零代码侵入
对话回放	完整展示用户提问、AI 回复、System Prompt、工具调用
性能分析	每次 LLM 调用的耗时、Token 消耗一目了然
广泛兼容	支持 OpenAI/Anthropic/Google 等 5 大 Provider，10+ Agent 框架
安全审计	Prompt Injection 检测、System Prompt 篡改监控

八、关于云舟观测

云舟观测是由360智汇云推出的一款一站式数据采集与监控观测产品，可以对基础设施、应用性能，以及云原生下业务指标和日志进行全面的监控和观测，构建全链路的可观测性服务，帮助用户及时发现和解决系统及应用性能问题，提高系统的稳定性和可靠性。