链路追踪

Tracing（链路追踪）对智能体执行过程进行全链路记录，是企业级智能体应用实现可观测性的核心。它把一次请求的完整流程——用户输入、模型推理、工具调用、记忆与知识库读写、响应生成——转化为可分析、可追溯的结构化数据，为调试、监控和优化提供依据。

在 VeADK 中开启观测

为智能体配置一个 OpentelemetryTracer，并指定一个或多个 Exporter，即可开启全链路观测。下例使用 APMPlus Exporter：

examples/tracing/tracing_exporter.py

import asyncio
from veadk import Agent, Runner
from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

# 初始化 Tracing Exporter
exporters = [APMPlusExporter()]
tracer = OpentelemetryTracer(exporters=exporters)

# 定义智能体并挂载 tracer
agent = Agent(tracers=[tracer])

runner = Runner(agent=agent)
response = asyncio.run(runner.run(messages="hi!"))
print(response)

可通过环境变量配置 Exporter：

OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY：APM 服务的 API Key
OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT：APM 服务的 Endpoint，例如 http://apmplus-cn-beijing.volces.com:4317
OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME：APM 的 Service Name，例如 python_coder_agent - OBSERVABILITY_OPENTELEMETRY_TRACE_CONTENT：是否采集 Agent、LLM 与工具输入输出内容，默认 true`

或在 config.yaml 中定义：

config.yaml

observability:
  opentelemetry        trace_content: true
    apmplus:
      endpoint: ...
      api_key: ...
      service_name: ...

开启后，日志中会打印出相关 Tracing 数据的 ID：

TraceID 示意

针对不同平台的完整接入方式，参见在火山引擎观测。

Tracing 的价值

引入 Tracing 后，你可以：

调试与定位问题：快速定位逻辑错误、工具调用失败或模型输出异常发生的环节；
性能分析：通过各模块的执行耗时发现瓶颈，优化模型调用与工具执行策略；
审计与合规：保留完整的请求、响应与决策记录；
多 Agent 协调：分析多 Agent 协作中各 Agent 的调用关系与数据流向。

Tracing 数据结构

Tracing 数据由一系列 Span 组成，每个 Span 记录一次操作（如调用模型、执行工具）的名称、ID、起止时间与属性。下面是单个工具调用 Span 的示例：

tracing.json

{
  "name": "execute_tool get_city_weather",
  "span_id": 15420762184471404328,
  "trace_id": 195590910357197178730434145750344919939,
  "start_time": 1762770336065962000,
  "end_time": 1762770336066380000,
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "get_city_weather",
    "gen_ai.tool.input": "{\"name\": \"get_city_weather\"}",
    "gen_ai.tool.output": "{\"response\": {\"result\": \"Sunny, 25°C\"}}",
    "cozeloop.input": "{\"name\": \"get_city_weather\"}",
    "cozeloop.output": "{\"response\": {\"result\": \"Sunny, 25°C\"}}"
  },
  "parent_span_id": 18301436667977577407
}

各属性字段的含义见埋点字段说明。

在多 Agent 场景中，多个 Span 通过 parent_span_id 串联，展现 coding_agent 调度 python_coder 的完整链路：

tracing.json

[
  {
    "name": "execute_tool transfer_to_agent",
    "span_id": 8839983747734433620,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "agent.name": "coding_agent",
      "gen_ai.operation.name": "execute_tool",
      "gen_ai.tool.name": "transfer_to_agent"
    },
    "parent_span_id": 5680387922600458423
  },
  {
    "name": "call_llm",
    "span_id": 6376035117066938110,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "agent.name": "python_coder",
      "gen_ai.request.model": "openai/doubao-seed-1-8-251228",
      "gen_ai.request.type": "chat",
      "gen_ai.span.kind": "llm",
      "gen_ai.prompt.0.role": "user",
      "gen_ai.prompt.0.content": "使用 Python 帮我写一段快速排序的代码。"
    },
    "parent_span_id": 11028930176666491606
  },
  {
    "name": "invoke_agent python_coder",
    "span_id": 11028930176666491606,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "gen_ai.span.kind": "agent",
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.description": "擅长使用 Python 编程语言来解决问题。",
      "gen_ai.system": "openai",
      "agent.name": "python_coder"
    },
    "parent_span_id": 5680387922600458423
  },
  {
    "name": "invoke_agent coding_agent",
    "span_id": 987150150265236585,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "gen_ai.span.kind": "agent",
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.description": "可以调用适合的智能体来解决用户问题。",
      "gen_ai.system": "openai",
      "agent.name": "coding_agent"
    },
    "parent_span_id": 11431457420615823859
  },
  {
    "name": "invocation",
    "span_id": 11431457420615823859,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "gen_ai.operation.name": "chain",
      "gen_ai.span.kind": "workflow",
      "gen_ai.system": "openai",
      "agent.name": "python_coder"
    },
    "parent_span_id": null
  }
]

与 OpenTelemetry 的兼容性

VeADK 的字段命名遵循 OpenTelemetry 生成式 AI 规范，你可以直接将 Tracing 数据导入到 OpenTelemetry 兼容的系统中进行分析和可视化。

链路追踪

在 VeADK 中开启观测

Tracing 的价值

Tracing 数据结构

本页导航