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

# Pipecat

> Export Pipecat voice agent traces to Agnost AI over OpenTelemetry

## Choose a setup method

| Method | Use it when |
| - | - |
| **Agnost AI skill** | You want your coding agent to inspect the app, make the change, and verify it. |
| **Agnost AI SDK** | You want explicit control over the interaction boundaries and fields. |
| **OpenTelemetry** | The framework already emits useful spans or you operate an OTel pipeline. |

Start with one method for a call path. Combining SDK tracking with framework
OpenTelemetry on the same call can create duplicate interactions.

## Recommended: Agnost AI skill

> [!NOTE]
>
> **Recommended.** Choose this path when you want your coding agent to inspect the
> project, select a supported transport, make the smallest instrumentation change,
> send a test event, and verify that it reached Agnost AI.

Install the skill once in your coding-agent environment:

```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
npx skills add AgnostAI/skills --skill agnost-ai
```

Run the framework-specific prompt below from the application root. Review the
resulting diff before deploying it.

```text theme={null}
Use the agnost-ai skill to add Agnost AI analytics to this Pipecat voice agent.
Org ID: your-org-id
Use Pipecat's built-in OpenTelemetry tracing and verify one fresh conversation.
```

Pipecat already traces conversations, turns, and STT, LLM, and TTS calls with
OpenTelemetry. Point those spans at Agnost AI; no Agnost SDK wrapper or extra
instrumentation package is required.

## 1. Install the tracing extra

```bash theme={null}
pip install "pipecat-ai[tracing]" opentelemetry-exporter-otlp-proto-http
```

## 2. Configure the OTLP destination

Set these variables in the bot's environment:

```bash theme={null}
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.agnost.ai/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="X-Agnost-Org-ID=your-org-id"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
```

## 3. Register the exporter

Call `setup_tracing` once, before the bot creates its `PipelineWorker`. The
HTTP exporter reads the endpoint and header from the environment.

```python theme={null}
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from pipecat.utils.tracing.setup import setup_tracing

setup_tracing(service_name="support-voice-bot", exporter=OTLPSpanExporter())
```

## 4. Enable tracing on the worker

Turn on tracing for each conversation and pass your own call and user IDs:

```python theme={null}
from pipecat.pipeline.worker import PipelineParams, PipelineWorker

worker = PipelineWorker(
    pipeline,
    params=PipelineParams(enable_metrics=True, enable_usage_metrics=True),
    enable_tracing=True,
    conversation_id=call_id,
    additional_span_attributes={
        "enduser.id": customer_id,
        "user.plan": "enterprise",
        "conversation.channel": "phone",
    },
)
```

| Setting | Agnost behavior |
| - | - |
| `conversation_id` | Becomes the Agnost conversation ID. Pipecat generates a UUID when omitted. |
| `enduser.id` | Groups conversations into one user. |
| `user.*` or `enduser.*` | Promoted to user metadata. |
| `conversation.*` or `session.*` | Promoted to conversation metadata. |
| `enable_usage_metrics=True` | Adds token usage to LLM spans. |

`additional_span_attributes` is attached to Pipecat's conversation span. Agnost
applies it to the whole conversation, including turns exported before the call ends.

## What appears in Agnost AI

* Each LLM reply becomes one user/assistant turn: the user's latest message and the bot's response, in order.
* Function calls become tool calls with their arguments and results, nested under the reply that used them.
* LLM spans keep the model, token usage, time to first byte (`metrics.ttfb`), and latency.
* Conversation, turn, STT, and TTS spans stay visible in the trace with turn duration and interruption state.
* Every Pipecat attribute, plus your custom attributes, remains available on events.

> [!NOTE]
>
> Pipecat does not create spans for function execution. Agnost recovers each call
> and its result from the context of the LLM request that follows it. This works
> for OpenAI-compatible LLM services, which send context in OpenAI chat format.

## Flush on shutdown

`setup_tracing` exports in batches. Flush before the process exits so the final
turn and the conversation span are sent:

```python theme={null}
from opentelemetry import trace

trace.get_tracer_provider().force_flush()
```

## Verify

Run one real conversation with the bot, then open **Users** in Agnost AI. Confirm:

1. The user appears under the value sent in `enduser.id`.
2. The conversation ID matches `conversation_id` and shows alternating user and assistant turns.
3. A turn that called a function shows the tool call with its arguments and result.
4. LLM events show the model, token counts, and latency.

## Troubleshooting

* Call `setup_tracing` before creating the `PipelineWorker`; spans started earlier are not exported.
* Set `enable_tracing=True` on every `PipelineWorker`. It is off by default.
* Use the traces URL ending in `/v1/traces` with the HTTP/protobuf exporter, not the gRPC exporter from Pipecat's Jaeger example.
* Confirm `X-Agnost-Org-ID` is present in `OTEL_EXPORTER_OTLP_HEADERS`.
* Leave `enable_turn_tracking` at its default (`True`); turn spans carry the conversation ID.
* Flush the tracer provider when a short-lived bot or test exits.

## References

* [Pipecat: OpenTelemetry tracing](https://docs.pipecat.ai/api-reference/server/utilities/opentelemetry)
* [Pipecat OpenTelemetry examples](https://github.com/pipecat-ai/pipecat-examples/tree/main/open-telemetry)
* [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)

## Next steps

* [Conversations](https://docs.agnost.ai/using-conversations.md): review complete voice interactions.
* [Events](https://docs.agnost.ai/using-events.md): inspect Pipecat spans and attributes.
* [Tool calls](https://docs.agnost.ai/using-tool-calls.md): analyze function arguments, results, errors, and latency.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.