Agent 全链路追踪

一、Agent 全链路追踪是如何工作的

1. 以 Trace 树记录一次运行

把单个 Agent 任务（一次用户请求、一个触发事件或一条定时任务）建模为一棵 Trace 树，从根节点到叶子节点完整表达"用户请求 → 推理 → 调工具 → 再推理 → 最终响应"的链路。

2. 在关键语义边界自动埋点

在 Agent 入口与出口、LLM 调用、工具调用、Agent 间调用等语义边界插入 Span，而非对每一行代码埋点。每个边界代表一次具有独立延迟特征与失败模式的操作。

3. 统一上下文贯穿全链路

通过 W3C Trace Context（traceparent / tracestate）在 HTTP 调用、消息队列等传输介质上传播 trace_id，使分散在不同服务、不同进程中的观测数据自动关联为同一条 Trace。

4. 采集后聚合分析与闭环

Span 数据上报到可观测后端后，按 trace_id 还原完整调用树，结合指标与日志进行排障、成本与质量分析，并进一步驱动 Prompt 调整、模型替换与工具顺序优化。

二、Agent 全链路追踪中的 Trace 与 Span 是什么关系

1. Trace 表示一次完整任务

一个 Trace 对应一次端到端的 Agent 运行，具有全局唯一的 trace_id，自动生成于任务开始时，贯穿整个执行过程直至最终响应。

2. Span 表示单个执行步骤

每个 Span 是一次具体操作（模型调用、工具调用、规划、检索等）的记录，包含自身的 span_id、指向父节点的 parent_span_id、起止时间戳以及执行状态（ok / error）。

3. 父子嵌套构成执行树

Span 通过 parent_span_id 指向上一层 Span，形成树状嵌套结构。阅读这棵树即可按时间顺序看到规划、工具调用、检索与输出的完整路径。

4. 二者是整体与局部的关系

一个 Trace 由多个 Span 组成，Span 不能脱离 Trace 独立存在。Trace 提供"这次任务发生了什么"的全景，Span 提供"某一步具体做了什么、用了多久、是否出错"的细节。

三、Agent 全链路追踪一次完整执行链路包含哪些环节

1. 请求入口与根 Span

用户请求作为 root span 进入系统，携带 trace_id、session_id 以及 Agent 标识，后续所有步骤都挂接在其之下。

2. 规划与推理环节

规划 Span（plan）记录任务分解与分支选择，推理 Span（reasoning）记录每一步的思考过程，使"为什么这样决策"可被追溯。

3. 模型调用环节

chat Span 包裹每一次 LLM 调用，记录模型名、输入与输出 Token、首 Token 耗时、结束原因（如 stop、tool_calls）。

4. 工具执行环节

工具调用作为嵌套 Span，记录工具名、调用参数、返回值与耗时，工具成功或失败的状态被标记在该 Span 上。

5. 子 Agent 委派与记忆环节

多智能体场景下，子 Agent 的 invoke_agent Span 作为调用方某 Span 的子节点递归挂接；记忆读写通过 memory 类 Span（create_memory / search_memory 等）记录上下文变化。

6. 输出与结束

最终响应作为 Trace 的末端，记录完成状态、总成本与总耗时，使一次任务从入口到出口形成闭合记录。

7. 基础结构字段（数据模型）

一次追踪记录的典型基础结构字段包括 trace_id、run_id（运行实例标识）、span_id、parent_span_id、step_type（如 reasoning / tool_call / llm_generate）、latency_ms 与 status，这些字段构成 Span 之间关联与还原的骨架。

四、Agent 全链路追踪的系统架构由哪几层组成

1. 采集层（Instrumentation）

在 Agent 代码或运行时注入探针，于语义边界创建 Span 并关联上下文，尽量以非阻塞方式导出，避免影响 Agent 正常执行。

2. 传输与处理层（Collector）

Span 通过 OTLP 协议上报，经 OpenTelemetry Collector 完成批处理、脱敏、采样与路由，采集链路本身不应成为阻塞关键路径的依赖。

3. 存储层（Backend）

Trace 数据写入支持 Trace 查询的后端（如 Jaeger、Grafana Tempo 或云上可观测平台），提供瀑布图、检索与留存能力。

4. 分析展示层

在链路可视化之上叠加会话分析、指标看板、告警与评估能力，把"看见"转化为"定位问题并优化"。

五、Agent 全链路追踪中采集端、处理层与存储层分别承担什么职责

1. 采集端职责

在语义边界创建 Span 并关联 trace 上下文；通过缓冲或批处理导出，避免追踪写入阻塞业务关键路径；同一 Trace 内不同服务可分别使用不同采集方案，通过标准协议自动关联。

2. 处理层职责

对 Span 进行缓冲、批处理与导出；执行脱敏（redaction）、采样决策与多后端路由，是连接采集与存储的"加工中枢"。

3. 存储层职责

提供快速 Trace 检索（热数据保留数天到数周）与长周期审计留存（按需更久）的分离存储；前者支撑日常排障，后者满足合规与回溯要求。

六、Agent 全链路追踪如何实现跨服务与跨 Agent 的上下文关联

1. 统一 Trace 上下文传播

使用 W3C Trace Context 的 traceparent / tracestate 头在 HTTP 调用中自动传播 trace_id，使跨服务的调用落在同一条 Trace 上。

2. 队列与异步场景的显式注入

在消息队列等异步场景中，需把 trace 上下文序列化进消息体，消费端提取并恢复上下文，避免出现两条割裂的 Trace。

3. 子 Agent 递归挂接

当 Agent A 调用 Agent B 时，B 的 invoke_agent Span 作为 A 某 Span 的子节点存在，调用链由统一 trace_id 串联，排障时可从顶层任务一路下钻到具体工具调用。

4. 跨组织联邦追踪

当 Agent 跨企业边界调用外部工具与服务时，通过标准上下文传播实现跨组织的 trace 关联与隐私合规的数据共享。

七、Agent 全链路追踪的数据采集方式有哪些

1. 自动插桩（Auto-Instrumentation）

在用户代码加载前注入 instrumentation，对主流 LLM SDK 与 Agent 框架自动产生 Span，无需修改业务代码即可采集模型调用、工具执行等环节。

2. 手动插桩（Manual Instrumentation）

通过 OpenTelemetry SDK 的 tracer.startActiveSpan 在业务代码中显式创建 Span，适用于自动插桩尚未覆盖的自定义逻辑、内部步骤与领域事件。

3. eBPF 零侵入采集

基于 eBPF 从操作系统内核层实现零代码侵入的采集，可覆盖网络通信、文件操作与 GPU 利用率等底层信号，适合已在 Kubernetes 环境中运行推理引擎的团队。

八、Agent 全链路追踪的探针接入方案有哪些类型

1. 多语言 SDK 探针

提供 Python 探针、Java 探针等，覆盖 LangChain、LlamaIndex、CrewAI、OpenAI SDK 等 AI 框架，以及 FastAPI、Django、MySQL、Redis 等传统组件，一个探针覆盖混合形态应用。

2. 兼容 OpenTelemetry 标准的 SDK 接入

通过 OpenTelemetry 协议标准自动关联同一链路中不同服务，同一条链路内的不同服务可分别选用不同方案，适配各类技术栈组合。

3. 第三方可观测平台 SDK 兼容接入

如兼容 Langfuse SDK 的接入方式，可将已有 Langfuse 埋点数据接入同一链路体系。腾讯云 Agent 可观测平台即提供此类兼容接入：它兼容 OpenTelemetry 协议，支持 AgentScope、OpenAI Agents SDK 等主流 Agent 框架与自研应用接入，自研应用可通过 Langfuse SDK 将 Trace 数据上报至平台，一次接入即可完成 Agent 全链路采集。

九、Agent 全链路追踪如何与 OpenTelemetry GenAI 语义约定对接

1. 以 OpenTelemetry 为标准输出

让 Agent 框架以 OpenTelemetry 规范输出 Trace，使采集层成为相对标准化的环节，降低对单一后端的锁定。

2. 遵循 GenAI 语义约定的属性命名

使用 gen_ai.* 统一命名空间（如 gen_ai.request.model、gen_ai.usage.input_tokens），保证不同框架、不同厂商产生的遥测数据可以互相对齐与查询。

3. 接入标准 OTLP 端点

主流可观测后端均消费标准 OTLP 端点，切换后端通常只需更换 exporter 而非重写埋点，提升可移植性。

4. 注意规范成熟度

GenAI 语义约定由 OpenTelemetry 于 2024 年 4 月成立的 GenAI SIG 维护；自 v1.41 起相关规范已从核心语义约定仓库迁至独立的 semantic-conventions-genai 仓库，但截至 2026 年中期官方文档仍将其标注为 Development（开发中）状态，属性命名可能演进，可通过 OTEL_SEMCONV_STABILITY_OPT_IN（取值 gen_ai_latest_experimental）管理版本过渡。

十、OpenTelemetry GenAI 语义约定定义了哪些 Span 类型

1. invoke_agent

调用一个智能体（远程服务或同进程），既可作为根 Span，也可作为子 Span 出现在多智能体委派中。

2. create_agent

记录智能体初始化，承载智能体 ID、名称、描述、版本与请求的模型等属性。

3. plan

记录任务规划或任务分解阶段，包含计划步骤与分支选择。

4. invoke_workflow

调用协调多个智能体或生成式 AI 操作的 workflow，承载工作流 ID 与包含的智能体信息。

5. execute_tool

记录工具执行，典型属性包括工具名、调用 ID、参数（gen_ai.tool.call.arguments）与结果（gen_ai.tool.call.result）。

6. chat / text_completion / embeddings

对应模型调用的操作类型，承载模型名、Token 用量与结束原因等属性。

7. 记忆操作 Span

create_memory / search_memory / update_memory / upsert_memory / delete_memory 等，记录记忆的读写与上下文变化。

十一、Agent 全链路追踪涉及哪些核心属性字段

1. 提供者与会话标识

gen_ai.provider.name 标识模型提供者，gen_ai.agent.name / id / version 标识智能体及其版本，gen_ai.conversation.id 用于聚合多轮对话。

2. 模型与 Token

gen_ai.request.model 与 gen_ai.response.model 区分请求模型与实际响应模型，gen_ai.usage.input_tokens、gen_ai.usage.output_tokens 记录基础 Token 消耗；提示词缓存相关则另记 gen_ai.usage.cache_read.input_tokens（缓存命中）与 gen_ai.usage.cache_creation.input_tokens（缓存写入，2026-08 仓库迁移后写作 cache_write），二者已计入 input_tokens，不可重复扣减。

3. 工具调用

gen_ai.operation.name=execute_tool 标识工具操作类型，gen_ai.tool.name、gen_ai.tool.call.arguments、gen_ai.tool.call.result 记录工具调用的关键信息。

4. 完成与延迟

gen_ai.response.finish_reasons 记录完成原因，gen_ai.client.operation.duration 记录操作耗时，二者是告警与 SLO 计算的基础。

十二、Agent 全链路追踪如何采集模型调用环节的数据

1. chat Span 包裹每次模型调用

每个 LLM 调用生成独立 Span，记录模型名、输入与输出 Token、首 Token 耗时与结束原因，使单次调用的成本与延迟可量化。

2. 输入输出与缓存

记录 prompt 与 completion 内容（需显式开启内容捕获）；启用提示词缓存时记录 gen_ai.usage.cache_read.input_tokens 与 gen_ai.usage.cache_creation.input_tokens，区分缓存命中带来的节省。

3. 多模态与推理 Token

多模态请求记录生成内容类型，推理模型记录 gen_ai.usage.reasoning.output_tokens（自 v1.41 起成为独立属性，不再并入 output_tokens），使不同模型形态的用量被正确归集。

4. 模型性能分位度量

按 P50 / P95 / P99 分位展示首 Token 耗时与模型调用耗时，支持按模型、应用、时间维度下钻对比，为模型选型与调优提供数据依据。

十三、Agent 全链路追踪如何记录工具调用与 MCP 交互

1. execute_tool Span 承载工具调用

每次工具调用生成独立 Span，记录工具名、调用参数、返回值、耗时与成功状态，失败时写入 error 状态与异常信息。

2. MCP 工具调用的上下文嵌套

基于 MCP 语义约定，将 MCP 服务端的 Span 嵌套在调用方 tool Span 之下，通过 mcp.session.id、mcp.method.name 与传播的 W3C Trace Context 关联，避免产生"Agent 进程一条 trace、MCP 服务端另一条 trace"的割裂。

3. 异常标记与可观测

对工具超时、参数异常、执行失败等情况进行标记，使工具侧健康度（成功率、延迟、错误类型）可被持续监控。

十四、Agent 全链路追踪如何覆盖 RAG 检索环节

1. retrieval Span 记录检索步骤

检索步骤由 retrieval Span 承载，记录查询语句、召回片段与相关性得分（平台支持时），使检索过程可见。

2. 与模型调用链路对齐

检索作为 chat Span 的上游或子 Span 存在，使"检索到了什么 → 模型基于什么作答"在同一 Trace 中可追溯。

3. 幻觉与引用核验

通过比对检索上下文与模型输出，识别模型声称但检索未返回的信息，辅助幻觉检测与引用正确性核验。

十五、Agent 全链路追踪如何还原多轮会话的执行过程

1. 以 session / conversation 维度聚合

用 session_id 或 gen_ai.conversation.id 将多轮对话集中呈现，把"用户问了什么、Agent 如何回答、从哪一轮开始偏离预期"逐步还原。

2. 逐步回放执行链路

按时间顺序回放"提问—思考—调工具—回复"的每一跳，结合调用树定位偏离点或失败点。

3. 异常自动标记

针对输出截断、工具超时、参数异常等问题自动标记，并支持根据具体业务自定义规则，从被动响应转向主动发现共性问题。

十六、Agent 全链路追踪支持哪些异常检测与告警能力

1. 内置异常规则

覆盖模型侧与工具侧的异常，如输出截断、工具超时、参数异常等可自动标记，并支持业务自定义规则。

2. 关键告警条件

常见告警包括 Agent 循环迭代过多、工具调用成功率骤降、Token 预算超阈值、端到端延迟 p99 超阈值、以及长时间未收到 trace 等。

3. AI 辅助根因分析

结合调用链中的耗时、Token 使用与执行结果，自动识别异常环节并分析可能原因，例如判断高 Token 消耗主要来自输入上下文、模型输出还是重复调用。

十七、Agent 全链路追踪如何统计 Token 消耗与成本

1. 按 Span 与任务归集 Token

每个 Span 记录 input / output / cached tokens，向上聚合到单次任务，并支持按租户、用户、会话等维度统计。

2. 成本归因

将 Token 消耗按模型计费标准换算为成本，支持按项目、用户、会话维度进行成本聚合分析。

3. 高耗环节定位

当一次任务响应过慢或 Token 消耗异常时，可下钻查看消耗主要来自哪一轮模型调用或哪一次工具执行。

4. 按结果统计成本效率

区分成功完成与出错 / 转人工的调用，统计"有效产出成本"与"纠错成本"，判断 Token 支出是否落在 productive 工作上。

十八、Agent 全链路追踪的性能分析维度有哪些

1. 基础设施指标

包括 Token 消耗量、每请求延迟（P50 / P95 / P99）、错误率、GPU 利用率与网络 I/O 吞吐量，与传统微服务可观测基本一致。

2. Agent 行为指标

Agent 特有维度，包括工具调用序列与分布、决策路径长度（从输入到输出的推理步数）、状态转换频率与成功率。

3. 质量评估指标

通过评估模型对每次响应打分或分类，涵盖相关性、幻觉检测、任务完成度、安全性等维度。

4. 成本与效率指标

包括每会话成本、Token 利用率（有效 Token 占比）与人工介入率，用于衡量规模化部署后的经济性。

十九、Agent 全链路追踪如何支撑 Agent 效果评估

1. LLM-as-Judge 评估范式

由评估模型对 Agent 的每一次响应进行打分或分类（相关性、幻觉、任务完成度、安全性），是 2026 年的主流评估实践。

2. 评估与 Trace 同源关联

评估运行与 trace_id 关联，质量数据与分析数据在同一视图中对照，既看"得分"也看"为什么得这个分"。

3. 失败 Trace 转为回归测试

将失败 Trace 直接转化为评估回归用例，在模型版本发布前与发布后持续监控质量退化。

4. 在线与离线评估闭环

离线批量打分与在线规则引擎实时告警结合，识别高延迟链路、Token 浪费模式与常见失败模式，驱动 Prompt 调整、模型替换与工具顺序优化，并经 A/B 验证后灰度上线。

二十、Agent 全链路追踪适用于哪些业务场景

1. 智能体客服与对话助手

还原多轮对话链路，定位答非所问、幻觉或工具调用错误的环节，提升对话质量。

2. 企业流程自动化 Agent

监控跨系统调用链路，保障任务"真实完成"而非仅接口返回成功，及时发现输出截断或工具失败。

3. 代码生成与研发助手

审查每一步工具调用（如文件读写、命令执行）是否符合授权边界，为安全治理提供执行证据。

4. 多智能体协同系统

在多 Agent 委派链路中定位责任环节，支撑审计、偏差检测与治理合规。

二十一、企业落地 Agent 全链路追踪需要哪些实施步骤

1. 明确接入边界与范围

确定需要追踪的 Agent、模型、工具与下游服务，优先覆盖语义边界（Agent 入口、LLM 调用、工具调用、Agent 间调用），避免在循环内部等低价值位置产生 Span 噪声。

2. 选择接入方式与探针

根据技术栈选择自动插桩、手动插桩或兼容 SDK 接入，同一条链路可混用。可基于腾讯云 Agent 可观测平台快速落地，该产品以 Agent 全链路追踪、Agent 评估实验、Agent 持续优化为核心能力：调用链追踪完整记录每一步的节点输入、输出、耗时与 Token 消耗，支持逐层展开；会话回放以 Session 为单位还原多轮对话与 Tool Call 交互；智能洞察支持以自然语言提问发起分析并输出优化建议；成本与性能监控按 Agent、模型、用户多维下钻；Agent 评估围绕准确率、工具调用正确率、任务完成率量化质量，结合人工标注形成质量管理体系；持续进化将评估结果沉淀为标注数据集，驱动 Prompt 与模型迭代，形成"观测—评估—优化"闭环。平台兼容 OpenTelemetry 协议，适用于 Agent 运维、运营分析、安全审计与评估优化等场景。

3. 搭建传输与处理管道

配置 OTLP 上报与 Collector，处理层执行脱敏、采样与多后端路由，确保采集链路不阻塞业务关键路径。

4. 配置采样、留存与告警

初期建议全量采集以建立基线，稳定后切换尾采样；设定留存分层与关键告警（循环过多、工具成功率骤降、Token 超阈值、延迟 p99 超阈值等）。

5. 接入分析与评估闭环

启用会话分析、Token 成本、性能度量与 LLM-as-Judge 评估，形成"观测—优化—验证"的持续闭环。

二十二、Agent 全链路追踪面临的主要技术挑战有哪些

1. 非确定性决策链路

相同输入可能因上下文累积、工具顺序差异或模型概率采样产生不同执行路径，使传统"固定输入 → 固定输出"的断言式测试失效。

2. 工具调用与决策的隐蔽性

问题常发生在 prompt 与最终响应之间，若只记录最终结果，难以暴露越权工具调用、错误数据传递等风险。

3. 海量异构数据的实时处理

一次会话可能包含数十轮 LLM 调用与数十次工具执行，每个步骤产生数 KB 到数 MB 的 Trace 数据，在千万级会话规模下数据量以 TB 级增长。

4. 高基数（High Cardinality）风险

trace_id、user_id、conversation_id 等维度若作为指标标签，会导致基数爆炸，推高存储成本并拖慢查询。

二十三、Agent 全链路追踪如何应对高并发与海量 Trace 数据

1. 非阻塞异步上报

采集层通过缓冲或批处理导出 Span，避免追踪写入阻塞 Agent 关键路径；采集链路本身不应成为故障来源。

2. 尾采样降低存储压力

对错误、慢调用、高 Token 消耗的 Trace 全量保留，对常规成功 Trace 按 1%～10% 抽样，在不丢失诊断价值的前提下控制存储成本。

3. 分层存储

热数据（快速 Trace 检索）保留数天到数周，审计所需的长周期记录按合规要求更久留存，二者分离设计。

4. 高基数维度治理

仅将低基数字段（如 agent version、model、environment、tool name、region）作为指标标签，高基数明细（用户、文档、对话）存入可检索日志或搜索后端。

二十四、Agent 全链路追踪的采样策略该如何设计

1. 头采样与尾采样的选择

头采样在 Trace 开始时即决定保留与否，实现简单但易丢弃罕见故障；尾采样在 Trace 完成后根据错误、延迟、成本等属性决定，是 Agent 系统的推荐默认。

2. 尾采样策略配置

典型策略为对错误 Trace 100% 保留、超过 p95 延迟阈值的 100% 保留、常规成功 Trace 抽样 5%～10%，并对复杂多步 Trace（如 Span 数超过阈值的）重点保留。

3. 分层留存

完整 payload 保留 7～14 天（覆盖绝大多数排障会话），元数据与评分保留 90～365 天（满足趋势分析与回归对比），是控制可观测总成本的主要杠杆。

4. 采样与评估分离

评估应在独立的随机样本上进行，避免基于"偏失败富集"的留存集得出有偏差的在线质量结论；采样决策应留档，因其影响后续可证明的交易记录完整性。

二十五、Agent 全链路追踪如何保障数据隐私与合规

1. 内容捕获默认关闭

prompt、tool arguments、outputs 等敏感内容默认不进入 Span，需显式开启（通常通过环境变量），开启与否本身是一项安全决策而非默认行为。

2. 传输与存储脱敏

通过 Collector 的 redaction 处理器在落库前遮蔽个人数据、密钥与凭证，敏感内容可路由到受限访问的专用表。

3. 留存与权限分级

Trace 数据按生产遥测对待，应用与日志一致的访问控制与留存策略；不同敏感级别的数据应分级存储与分级授权。

4. 合规与治理对齐

完整的 Agent 执行记录可映射到 NIST AI 风险管理框架、NIST SP 800-53 等治理与审计要求，为 Responsible AI 与合规举证提供证据链。

二十六、Agent 全链路追踪与传统 APM 链路追踪有什么区别

1. 观测对象不同

传统 APM 面向 HTTP 请求、数据库查询等确定性调用；Agent 全链路追踪面向多步推理、工具调用与子 Agent 委派等复合行为。

2. 数据结构不同

APM 多为扁平的调用列表；Agent 追踪是嵌套的 Span 树，包含决策、推理、检索等 Agent 特有节点，结构更复杂。

3. 关注目标不同

APM 主要回答"系统是否在运行（Liveness）"；Agent 追踪还需回答"输出质量是否可靠""模型为何给出此回答（Quality）"。

4. 数据形态不同

Agent 一次运行可产生数十个模型调用与工具调用，单步数据量从数 KB 到数 MB，其体量与非确定性远高于传统链路追踪。

二十七、Agent 全链路追踪与 LLM 监控有什么本质差异

1. 监控粒度不同

LLM 监控聚焦单次模型调用（prompt、completion、tokens、cost、model version）；Agent 全链路追踪覆盖完整的 Agent 运行。

2. 覆盖范围不同

LLM 监控是"一个点"；Agent 全链路追踪是"一条链"，把多次 LLM 调用、工具执行、子 Agent 委派与上下文整合为工作流。

3. 价值重心不同

LLM 监控帮助定位单次调用问题（坏 prompt、慢响应、高成本）；Agent 全链路追踪帮助定位流程问题（调错工具、Agent 死循环、把错误数据传给下一步）。

4. 二者并非替代关系

LLM 监控数据作为 Agent 追踪中的一个 Span 类型（chat Span）存在，二者共同汇入同一 Trace 体系：前者是后者的基础组成，后者是前者的流程化整合。