在火山引擎观测

VeADK 通过不同的 Exporter 把 Tracing 数据上报至火山引擎平台。本页介绍 CozeLoop、APMPlus、TLS 三个平台的接入方式。各 Span 的字段含义见埋点字段说明。

共享配置

三个平台共用相同的 model 与 volcengine 配置，只是 observability 子树不同。下面是共享部分，后续各平台只展示各自的 observability 配置：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-8-251228
    api_base: https://ark.cn-beijing.volces.com/api/v3
    api_key: your api_key

volcengine:
  access_key: your ak
  secret_key: your sk

接入代码也基本一致：构造对应平台的 Exporter，交给 OpentelemetryTracer，再挂载到 Agent 上。

CozeLoop 平台

将 VeADK 开发的智能体接入扣子罗盘后，你可以通过扣子罗盘的 Trace 功能观测调用链路，或通过其评测功能对 Agent 进行评测。

准备工作

在 config.yaml 的 observability 字段中填写 cozeloop 属性：

endpoint：固定为 https://api.coze.cn/v1/loop/opentelemetry/v1/traces
api_key：扣子罗盘访问密钥，支持个人访问令牌、OAuth 访问令牌和服务访问令牌。获取方式参见配置个人访问令牌。
service_name：扣子罗盘工作空间 ID。登录扣子罗盘后，在左上角切换到目标工作空间，在 URL 中 space 之后的片段即为工作空间 ID。例如 https://loop.coze.cn/console/enterprise/personal/space/739XXXXXXXX092/pe/prompts 中，739XXXXXXXX092 为工作空间 ID。

cozeloop 空间

config.yaml（observability 子树）

observability:
  opentelemetry:
    cozeloop:
      endpoint: https://api.coze.cn/v1/loop/opentelemetry/v1/traces
      api_key: your api_key
      service_name: your cozeloop space id

接入代码

agent.py

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.demo_tools import get_city_weather
from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

exporters = [CozeloopExporter()]
tracer = OpentelemetryTracer(exporters=exporters)

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."

asyncio.run(runner.run(messages=prompt, session_id="session_id_pj"))

效果展示

python agent.py

cozeloop 控制台

cozeloop trace

APMPlus 平台

定义 APMPlus 数据导出器，即可将智能体的 Trace 与 Metrics 数据接入火山引擎 APMPlus 平台。

准备工作

在 config.yaml 的 observability 字段中填写 apmplus 属性：

endpoint：APMPlus 接入点，例如 http://apmplus-cn-beijing.volces.com:4317
api_key：有效的应用程序密钥
service_name：服务名称，可按需修改

config.yaml（observability 子树）

observability:
  opentelemetry:
    apmplus:
      endpoint: http://apmplus-cn-beijing.volces.com:4317
      api_key: your api_key
      service_name: apmplus_veadk_pj

接入代码

agent.py

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.demo_tools import get_city_weather
from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

exporters = [APMPlusExporter()]
tracer = OpentelemetryTracer(exporters=exporters)

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."

asyncio.run(runner.run(messages=prompt, session_id="session_id_pj"))

效果展示

本地运行上述代码，APMPlus 追踪器会记录 Agent 各节点的调用，并将 Metrics 上传至云端：

python agent.py

apmplus 控制台

会话信息：

apmplus 会话

Trace 信息：

apmplus trace

模型指标信息：

apmplus 指标

TLS 平台

定义 TLS 数据导出器，即可将智能体执行链路接入火山引擎日志服务 TLS，并在 TLS 观测模块中查看。

准备工作

在 config.yaml 的 observability 字段中填写 tls 属性：

config.yaml（observability 子树）

observability:
  opentelemetry:
    tls:
      endpoint: https://tls-cn-beijing.volces.com:4318/v1/traces
      service_name: tp_pj
      region: cn-beijing

接入代码

TLS 接入分两步：先用 VeTLS 客户端创建日志项目与追踪实例，再用 TLSExporter 上报数据。

agent.py

import asyncio
from os import getenv

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.demo_tools import get_city_weather
from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter, TLSExporterConfig
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer
from veadk.integrations.ve_tls.ve_tls import VeTLS

# 1. 创建日志项目与追踪实例
ve_tls_client = VeTLS()
log_project_id = ve_tls_client.create_log_project("veadk_pj")
print(f"Created log project with ID: {log_project_id}")

trace_instance_name = getenv("OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME")
trace_instance = ve_tls_client.create_tracing_instance(log_project_id, trace_instance_name)
print(f"Created trace instance with ID: {trace_instance['TraceInstanceId']}")

# 2. 用 TLSExporter 上报 Tracing 数据
tls_exporter = TLSExporter(
    config=TLSExporterConfig(
        topic_id=trace_instance.get("TraceTopicId", trace_instance_name),
    )
)
tracer = OpentelemetryTracer(exporters=[tls_exporter])

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."

asyncio.run(runner.run(messages=prompt, session_id="session_id_pj"))

效果展示

本地运行上述代码，会触发 TLS Project、Topic 的创建，并记录 Agent 各节点的调用：

python agent.py

控制台打印

tls trace

在火山引擎观测

本页导航