01引言
Cloud Native
2025 年,AI Agent 从实验室走向规模化生产落地。从开发者日常使用的代码助手到企业服务场景下的智能客服,到复杂度持续升级的多智能体协同系统,AI Agent 正在以前所未有的速度重塑软件开发方式和业务运转流程。
然而,当 Agent 真正跑起来之后,一个尖锐的问题浮出水面:AI Agent 的实际运行行为难以感知、追溯与管控。
代码类 Agent 深夜擅自修改核心配置文件,变更内容、修改动因无从知晓;智能客服 Agent 自主下达“取消订单”指令,决策逻辑、工具调用链路、Token 资源消耗无法复盘;多智能体协同任务中途失败,故障节点与根因难以定位。
这些问题指向一个共同的诉求:AI Agent 需要完备的可观测能力。而且,这种可观测性不能仅停留在“请求成功/失败”的浅层统计维度,必须深入覆盖 LLM 调用、工具执行、多轮推理、记忆检索等 AI Agent 特有的运行环节中去。
阿里云基于 OpenTelemetry (OTel) 社区标准,结合自身在可观测领域的深度实践,打造了一套覆盖三大类 Agent 形态的完整数据采集方案,并在 OTel GenAI 语义规范基础上推出了 LoongSuite GenAI 可观测语义规范。本文将系统介绍这套方案的设计理念、技术实现和使用方法。
02Agent 形态分类与可观测挑战
Cloud Native
当前 AI Agent 市场百花齐放,不同类型 Agent 的运行模式、部署环境、使用场景差异显著,对应的观测、审计需求也各有侧重。我们将市面上主流 AI Agent 划分为三大类别:
▍2.1 三大 Agent 形态
▍2.2 三大核心挑战
无论采用何种形态,AI Agent 在规模化使用后,均会遭遇三大共性难题:
- 执行过程黑盒化。Agent 的执行过程涉及 LLM 调用、工具执行、多轮推理、记忆检索等环节,传统的 Metrics + Log + Trace 三板斧无法有效刻画这一新型计算范式。例如一轮包含 10 次 ReAct 推理的 Agent 任务,传统方案仅能识别出 10 条独立 HTTP 请求,无法还原分层、有序的完整决策流程。
- 行为轨迹难追溯。Agent 具备较高的自主操作权限,可读写本地文件、执行系统命令、调用第三方 API。在缺少专项审计能力的前提下,无法完整追溯 Agent 的全部操作行为,在企业安全、合规管控场景中存在极大风险。
- 成本难度量。大模型 Token 消耗是 Agent 的主要成本来源,多轮迭代和工具调用会指数级放大消耗。若缺少按 Agent、用户、任务维度的精细化成本拆分能力,企业将无法开展预算管控与投入产出评估。
03差异化采集方案:
适配 Agent 原生运行形态
Cloud Native
核心设计原则:让数据采集能力适配 AI Agent 原生运行模式,而非强制 Agent 改造适配采集工具。
▍3.1 Coding Agent:LoongSuite Pilot 端侧轻量数据采集平台
Coding Agent 运行在开发者本地设备,所有代码编辑、文件新建、终端命令执行等核心行为均发生在本地环境,传统服务端探针完全无法感知,为此我们推出 LoongSuite Pilot 端侧数据采集平台,专门适配代码类 Agent。
核心优势
- 一次部署,全域覆盖。Pilot 不是针对某一个 Agent 的专属方案,而是一个统一平台。目前已支持 Claude Code、Codex、Cursor、Qoder、QoderWork 五大主流 Coding Agent。开发者仅需完成一次安装,即可自动对所有已使用的代码助手完成数据采集,无需重复配置。
- 后台静默运行,零使用干扰。Pilot 以本地守护进程形式常驻后台,自动识别设备内已安装的 Coding Agent 并完成能力部署。全程无需开发者修改 Agent 配置、改变使用习惯,在无感状态下完整记录大模型调用、工具执行、代码修改等全量行为。
- 断点续采,数据稳定可靠。针对本地设备网络波动、设备重启、终端关闭等不稳定场景,内置断点续采机制。进程异常中断重启后,不会出现数据重复、数据丢失问题,保障采集数据完整性。
- 采集粒度灵活,兼顾观测与数据安全。不同团队对数据安全的要求不同。Pilot 支持按 Agent 类型灵活配置采集粒度:需要完整审计时,可采集消息内容、工具参数等详细信息;在数据敏感场景下,可仅上报元数据(模型名、Token 消耗、耗时等),在观测需求与数据安全之间取得精准平衡。
- 插件化架构,快速兼容新 Agent。Pilot 采用插件化架构,针对不同 Agent 的数据形态(Hook 日志、IDE 快照、SQLite 数据库、会话文件等)预置了开箱即用的采集基类。接入全新 Coding Agent 仅需实现 2-3 个抽象方法,可快速跟进生态迭代。
已支持的 Coding Agent 及覆盖能力
▍3.2 个人通用助理:一行命令接入完整观测和审计
个人通用助理通常以独立服务的形式运行,面向终端用户提供对话和任务执行能力。针对这类 Agent,我们提供了专用插件,实现一行命令即可接入完整链路追踪。
设计理念
以 OpenClaw 为例,其内置的 diagnostics-otel 扩展虽然能输出 Metrics 和部分 Trace,但采用的是事件驱动架构,每个事件独立创建 Span,彼此之间没有父子关系和 Trace Context 传播,本质上是一组“独立打点”。而 LoongSuite 的 openclaw 插件从设计上就是完整的链路追踪——所有 Span 共享同一个 traceId,通过显式的父子关系串联成一棵调用树。
Span 语义模型
各类 Span 通过父子关系串联为完整 Trace 调用树,运维人员可直观查看单条请求的大模型调用次数、Token 消耗、工具调用清单、耗时节点与故障信息。
与内置观测的本质差异
LoongSuite 的插件相比 OpenClaw 内置的观测能力,核心差异体现在两个维度:
链路完整性。内置观测通常是扁平化独立打点,事件之间缺乏关联;而我们的插件基于 OTel Context 传播机制,确保 ENTRY → AGENT → STEP → LLM / TOOL 形成完整的调用树,能够还原一次请求的全貌。
数据丰富度。内置观测往往只记录模型用量等基础指标;而我们的插件完整记录 gen_ai.input.messages、gen_ai.output.messages、gen_ai.system.instructions、gen_ai.tool.call.arguments、gen_ai.tool.call.result 等字段,满足深度审计和故障排查的需求。
同样的插件机制已覆盖 Hermes Agent、QwenPaw 等个人通用助理。
▍3.3 高低代码框架Agent:LoongSuite Python Agent 零代码探针插桩
针对 LangChain、AgentScope、dify 等框架开发的 Agent 应用,其运行方式与传统 Python 应用一致。我们提供 LoongSuite Python Agent(基于 OpenTelemetry Python Contrib 深度定制),通过一行命令实现零代码自动插桩。
快速开始
## 1. 安装 LoongSuite Python Agentpip install loongsuite-distro# 2. 自动检测并安装所需的插桩库loongsuite-bootstrap# 3. 一行命令启动,自动注入探针loongsuite-instrument \ --traces_exporter otlp \ --service_name my-agent-app \ python my_agent_app.py
loongsuite-bootstrap 会自动扫描当前环境中已安装的框架(如 langchain、dashscope、MCP 等),并安装对应的插桩包——开发者无需手动挑选和安装。
框架覆盖
目前 LoongSuite Python Agent 已覆盖 17 个插桩库,涵盖主流 AI Agent 开发框架: