Cozeloop

CozeloopExporter 将 span 数据以 OTLP（HTTP）协议上报至Cozeloop平台。接入后，可通过Cozeloop的 Trace 功能观测调用链路，或通过其评测功能对智能体进行评测。数据按工作空间隔离。

何时使用

需要在Cozeloop上观测智能体的调用链路；
需要借助Cozeloop的评测能力分析对话质量与工具使用效果；
已有Cozeloop工作空间与访问密钥。

接入前准备

先完成安装和模型配置，再设置以下环境变量。占位符需要替换为有权限访问的实际资源和凭证；在启动 Python 前完成配置

Cozeloop 会接收链路数据。建议显式指定已存在的工作空间 ID；省略时会使用令牌尝试创建默认工作空间，需要相应权限。配置导出器不会自动创建或执行评测任务

export OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT="https://api.coze.cn/v1/loop/opentelemetry/v1/traces"
export OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY="your-cozeloop-token"
export OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME="your-cozeloop-space-id"

使用示例

保存为 app.py，运行 python app.py。示例复用已有资源，完成一次模型调用后刷新待导出的链路数据

app.py

import asyncio

from veadk import Agent, Runner
from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

tracer = OpentelemetryTracer(exporters=[CozeloopExporter()])
agent = Agent(name="trace_demo", tracers=[tracer])
runner = Runner(agent=agent, app_name="trace_demo", user_id="demo-user")
response = asyncio.run(
    runner.run("用一句话解释智能体的用途", session_id="demo-session")
)
print(response)
tracer.force_export()
print("Trace ID:", tracer.trace_id)

也可以通过 CozeloopExporterConfig 显式传入连接参数：

import os

from veadk.tracing.telemetry.exporters.cozeloop_exporter import (
    CozeloopExporter,
    CozeloopExporterConfig,
)

exporter = CozeloopExporter(
    config=CozeloopExporterConfig(
        endpoint="https://api.coze.cn/v1/loop/opentelemetry/v1/traces",
        space_id=os.environ["OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME"],
        token=os.environ["OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY"],
    )
)

参数

构造参数

CozeloopExporter 的连接参数由 config 字段承载，类型为 CozeloopExporterConfig；不传时各字段自动从对应环境变量读取。

参数	类型	默认值	说明
`config`	`CozeloopExporterConfig`	自动从环境变量读取	Cozeloop连接与认证配置。
`resource_attributes`	`dict`	`{}`	附加到 span 的资源属性。
`headers`	`dict`	`{}`	附加的请求头；导出器会自动并入 `cozeloop-workspace-id` 与 `authorization`。

Cozeloop 连接配置

config 为 CozeloopExporterConfig，各字段默认从 CozeloopConfig 读取，环境变量如下：

配置项	环境变量	类型	默认值	说明
`endpoint`	`OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT`	`str`	`https://api.coze.cn/v1/loop/opentelemetry/v1/traces`	Cozeloop OTLP 接入点（HTTP）。
`space_id`	`OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME`	`str`	未设置时自动创建默认工作空间	工作空间 ID，用于数据隔离。
`token`	`OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY`	`str`	`""`	访问密钥，支持个人访问令牌、OAuth 访问令牌与服务访问令牌。

space_id 取自环境变量 OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME；未设置时，导出器会以 token 为凭证自动创建一个默认工作空间。登录Cozeloop后，URL 中 space 之后的片段即为工作空间 ID。

也可以让 Agent 依据环境变量自动挂载 Cozeloop 导出器，无需显式构造：

export ENABLE_COZELOOP=true

设置 ENABLE_COZELOOP=true 后，即便智能体未显式提供 tracers，Agent 也会自动创建 OpentelemetryTracer 并挂载 CozeloopExporter。

验证与排查

运行后在目标平台按本次 Trace ID 查询。模型回复成功只说明智能体完成了调用，不代表链路上传成功；找不到数据时依次检查端点和地域、凭证权限、目标资源以及进程退出前是否调用 tracer.force_export()

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

接入前准备

使用示例

参数

构造参数

Cozeloop 连接配置

验证与排查

​何时使用

​接入前准备

​使用示例

​参数

​构造参数

​Cozeloop 连接配置

​验证与排查

何时使用

接入前准备

使用示例

参数

构造参数

Cozeloop 连接配置

验证与排查