火山引擎 TLS AgentLoop 全链路可观测：LLM 应用会话透明复盘

火山引擎日志服务 TLS（Tinder Log Service）是一站式存储分析平台，统一承载日志、Trace、Metrics 等可观测数据。AgentLoop 则是 TLS 面向 AI Agent 提供的运行观测、问题沉淀、离线评测、实验对比与质量分析能力。借助 AgentLoop，开发者可以让 Agent 运行过程可观测、复杂链路可回放、线上问题可沉淀、版本优化可评测。

本文重点介绍如何基于 TLS 的 AgentLoop 做 LLM 应用观测，解决 LLM 应用运行过程中的黑盒问题。

LLM 应用可观测的价值与 TLS 能力支撑

LLM 应用的黑盒特征非常典型。以一个支持工具调用的智能助手为例，一次请求可能经历上下文组织、模型推理、工具执行、结果回传和二次总结等多个阶段；单次回答背后也可能包含多次模型与工具调用。

当结果偏离预期、响应延迟异常或 Token 消耗超出预估时，仅凭业务日志往往很难说清：到底调用了哪些模型和工具？各阶段耗时多少？Token 消耗在哪里？错误发生在哪个环节？多个请求是否属于同一会话？

可观测体系的核心目标，就是把运行过程转成结构化、标准化的全链路数据。TLS LLM 应用可观测方案包括：

1. 应用侧数据采集：在应用中接入 LLM Observer SDK，采集用户请求、模型交互、工具调用和异常信息。
2. 标准化数据处理：遵循 OpenTelemetry GenAI 语义约定，将原始调用数据转换为统一的 Trace 模型。
3. 数据存储与消费：通过 OTLP / HTTP 将 Trace 上报到 TLS，完成持久化存储、检索与聚合。
4. 可视化观测仪表盘：通过 AgentLoop 前端页面展示 Session、Trace 和调用链，支撑日常巡检与问题复盘。

TLS LLM 应用可观测体系

LLM Observer SDK 本身不负责调用模型。应用仍然通过模型客户端调用火山方舟等 OpenAI 兼容服务；SDK 的任务是采集模型、Token、耗时和错误状态，并把数据上报到 TLS。

用户输入
  └── TypeScript LLM 应用
      ├── 模型客户端 ──> 火山方舟 ──> 豆包模型
      └── LLM Observer SDK
          ├── Agent Span：一次业务请求
          ├── Model Span：一次模型调用
          └── Tool Span：一次工具执行
                    │
                    ▼
              TLS Trace Topic
                    │
                    ▼
       AgentLoop Session / Trace 页面

Session 表示一段用户会话，可以包含多个 Trace；Trace 表示一次请求或一轮对话；Span 表示具体的执行阶段。工具调用 Trace 可以还原模型决策、工具执行和最终回答：

Session
├── Trace 1：Agent → Model
├── Trace 2：Agent → Model → Tool → Model
└── Trace 3：Agent → Model

LLM 应用可观测数据接入

Node 环境接入

接入前需要准备 Node.js 18 及以上环境、可用的模型服务、TLS Trace Topic 以及对应的鉴权信息。模型凭证用于调用大模型，TLS 凭证用于上报 Trace，两者相互独立。

安装 SDK 后，为模型客户端添加观测能力，并在业务请求外层创建 Agent Span。模型调用和工具调用会形成子 Span，请求结束后即可在 TLS 中检索。

当前 SDK 覆盖以下典型场景：

• 单轮对话：记录一次用户请求和模型响应。
• 多轮对话：同一个 session.id 下，每轮生成独立 Trace。
• 流式响应：实时输出模型内容，在流结束后统一记录完整响应和 Token。
• 工具调用：串联模型决策、工具执行和最终回答。
• 异常链路：记录模型或工具调用错误，保留错误节点和上下文。

SDK 通过 TLS_TRACE_CAPTURE_CONTENT 控制是否采集 Input、Output、工具参数和工具结果。关闭正文采集后，模型、Token、耗时和状态等观测信息仍然保留。生产环境应结合业务数据治理要求配置采集范围，避免密码、AK / SK、API Key 等敏感信息进入 Trace。

import OpenAI from 'openai';
import { TraceClient, instrumentOpenAI } from '@volcengine/tls-llm-observer';

const traceClient = new TraceClient();

const ark = instrumentOpenAI(
  new OpenAI({
    apiKey: process.env.ARK_API_KEY,
    baseURL: 'https://ark.cn-beijing.volces.com/api/v3',
  }),
  { traceClient },
);

const response = await ark.responses.create({
  model: process.env.ARK_MODEL!,
  input: '请用一句话介绍火山引擎日志服务',
});

console.log(response.output_text);
await traceClient.shutdown();

开箱即用的可视化观测仪表盘

Trace 写入 TLS 后，由独立的 LLM Observer SDK Dashboard Model 驱动 AgentLoop 页面展示。它与其他采集插件的模板相互隔离，仅复用同一套前端组件。

会话分析

SessionTableV2 按 session.id 聚合多轮 Trace，展示会话首次 Input、Trace 数量、总 Token、使用模型和累计耗时。开发者可以先了解会话整体情况，再进入详情复盘每一轮请求。

Trace 分析

TraceTableV2 以单次请求为粒度展示 Input、状态、Input Tokens、Output Tokens、总 Token 和耗时，并支持按状态、时延和 Token 区间筛选，帮助快速定位失败请求、慢请求和高消耗请求。

调用链分析

Trace 详情按照父子关系还原 Agent、Model 和 Tool Span。对于普通问答，可以查看一次模型调用的 Input、Output 和 Token；对于工具场景，可进一步核对模型选择的工具、调用参数、执行结果以及各阶段耗时，从而定位故障和性能瓶颈。

上述观测能力最终可沉淀为三类开发动作：

1. 精准排障：通过 Trace 调用链定位模型、工具或业务逻辑中的异常环节。
2. 成本优化：通过 Trace 和 Session 级 Token 汇总识别高消耗请求与会话。
3. 完整复盘：结合会话和调用链数据，还原多轮交互中的模型决策与工具执行过程。

总结

针对 LLM 应用运行过程中的黑盒问题，TypeScript LLM Observer SDK 将用户请求、模型交互、流式响应和工具调用转换为标准化 Trace，并上报到 TLS。在此基础上，AgentLoop 通过 Session、Trace 和调用链视图，帮助开发者完成日常巡检、成本分析和问题复盘，让一次模型应用调用从不可见变为可检索、可分析、可追溯。

演进方向

1. 模型与框架生态扩展：持续增加更多模型服务商、Agent 框架和工作流框架的标准化接入能力。
2. 观测指标完善：补充首 Token 延迟、Output 速率、缓存命中和模型成本等指标，形成更完整的性能与成本分析体系。
3. 观测与评测闭环：将线上 Trace 与模型评测、Prompt 优化和工具优化打通，形成“观测—分析—优化—验证”的迭代闭环。