> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Cozeloop

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

## 何时使用

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

## 使用示例

```python lines theme={null}
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())

asyncio.run(runner.run(messages="北京天气怎么样？", session_id="session_id_demo"))
```

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

```python lines theme={null}
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="your-cozeloop-space-id",
        token="your-cozeloop-token",
    )
)
```

## 参数

### 构造参数

`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 访问令牌与服务访问令牌。 |

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

## 环境变量配置

```bash lines theme={null}
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"
```

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

```bash lines theme={null}
export ENABLE_COZELOOP=true
```

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