> ## 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` reports span data to the Cozeloop platform over OTLP (HTTP). Once connected, you can observe traces with Cozeloop's trace feature or evaluate agents with its evaluation feature. Data is isolated by workspace (space).

## When to use

* You want to observe your agent's traces on Cozeloop;
* You want to analyze conversation quality and tool-usage effectiveness with Cozeloop's evaluation capabilities;
* You already have a Cozeloop workspace and access token.

## Usage

```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="How is the weather in Beijing?", session_id="session_id_demo"))
```

You can also pass connection parameters explicitly via `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",
    )
)
```

## Parameters

### Constructor parameters

`CozeloopExporter` carries its connection parameters in the `config` field of type `CozeloopExporterConfig`; when omitted, each field is read automatically from the corresponding environment variable.

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `config` | `CozeloopExporterConfig` | Read from environment variables | Cozeloop connection and authentication config. |
| `resource_attributes` | `dict` | `{}` | Resource attributes attached to spans. |
| `headers` | `dict` | `{}` | Extra request headers; the exporter merges in `cozeloop-workspace-id` and `authorization` automatically. |

### Cozeloop connection config

`config` is a `CozeloopExporterConfig`; each field defaults from `CozeloopConfig`, with the following environment variables:

| Config | Environment variable | Type | Default | Description |
| :- | :- | :- | :- | :- |
| `endpoint` | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT` | `str` | `https://api.coze.cn/v1/loop/opentelemetry/v1/traces` | Cozeloop OTLP endpoint (HTTP). |
| `space_id` | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME` | `str` | Creates a default workspace automatically when unset | Workspace ID for data isolation. |
| `token` | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY` | `str` | `""` | Access token; supports personal access tokens, OAuth access tokens, and service access tokens. |

<Note>
  `space_id` is taken from the environment variable `OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME`; when unset, the exporter creates a default workspace automatically using `token` as the credential. After logging in to Cozeloop, the segment after `space` in the URL is the workspace ID.
</Note>

## Environment variables

```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"
```

You can also let `Agent` attach the Cozeloop exporter automatically from an environment variable, without constructing it explicitly:

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

<Tip>
  With `ENABLE_COZELOOP=true`, `Agent` creates an `OpentelemetryTracer` and attaches `CozeloopExporter` automatically, even when the agent provides no `tracers`.
</Tip>