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

# Pipecat

> Trace Pipecat AI voice pipelines in Braintrust to debug LLM turns, speech-to-text, text-to-speech, and tool calls

[Pipecat](https://www.pipecat.ai/) is a framework for building real-time voice AI pipelines. Braintrust traces Pipecat pipelines to capture LLM turns, speech-to-text transcriptions, text-to-speech responses, and tool calls.

**Python**

> [!NOTE]
>
> Requires `pipecat-ai` v1.3.0 or later and Python 3.11 or later.

## Setup

**1. Install packages**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust "pipecat-ai[openai]>=1.3.0"
```

**2. Set your environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=your-api-key
OPENAI_API_KEY=your-openai-api-key
```

## Auto-instrumentation

Call `auto_instrument()` before creating your pipeline to trace all `PipelineWorker` instances automatically.

```python title="agent.py" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import asyncio

import braintrust

braintrust.auto_instrument()
braintrust.init_logger(project="my-pipecat-project")  # Replace with your project name

from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.worker import PipelineWorker

async def main():
    # Build your pipeline as usual. Tracing is injected automatically.
    pipeline = Pipeline([...])  # Add your pipeline processors
    worker = PipelineWorker(pipeline)

    runner = PipelineRunner()
    await runner.run(worker)

asyncio.run(main())
```

> [accordion] Trace only Pipecat
>
> To instrument Pipecat without auto-instrumenting other libraries, use `setup_pipecat()` instead of `auto_instrument()`:
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> from braintrust.integrations.pipecat import setup_pipecat
>
> setup_pipecat(project_name="my-pipecat-project")  # Replace with your project name
> ```

> [accordion] Opt out of Pipecat tracing
>
> If you use `auto_instrument()` for other libraries but want to exclude Pipecat, pass `pipecat=False`:
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> braintrust.auto_instrument(pipecat=False)
> ```

> [accordion] Attach audio recordings
>
> By default, audio is not stored as attachments. To attach user and agent audio to spans, set these environment variables:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> BRAINTRUST_CAPTURE_USER_AUDIO_ATTACHMENTS=true   # Attach user speech to user_speaking spans
> BRAINTRUST_CAPTURE_AGENT_AUDIO_ATTACHMENTS=true  # Attach TTS audio to tts_response spans
> ```
>
> You can also configure this when calling `setup_pipecat()`:
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> from braintrust.integrations.pipecat import setup_pipecat
>
> setup_pipecat(
>     project_name="my-pipecat-project",
>     capture_user_audio_attachments=True,
>     capture_agent_audio_attachments=True,
> )
> ```

## Manual instrumentation

To add a `BraintrustPipecatObserver` to a specific `PipelineWorker` rather than patching globally, pass it explicitly:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from braintrust.integrations.pipecat import BraintrustPipecatObserver

observer = BraintrustPipecatObserver()
worker = PipelineWorker(pipeline, observers=[observer])
```

## What Braintrust traces

Braintrust attaches a `BraintrustPipecatObserver` to each `PipelineWorker` and emits spans as frames flow through the pipeline.

* Pipeline spans (`pipecat_pipeline`), the root span covering the full pipeline run, with audio sample rate and format metadata.
* LLM response spans (`pipecat_llm_response`), nested under the pipeline span, with input messages, output text or tool calls, token usage, time to first token, and model name and provider.
* Tool spans (named by the function), with tool arguments and result.
* STT transcription spans (`stt_transcription`), with transcript text and language.
* TTS response spans (`tts_response`), with input text and, when enabled, an audio attachment.
* User speaking spans (`user_speaking`), with optional user audio attachment.

## Resources

* [Pipecat documentation](https://docs.pipecat.ai/)
* [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md)
* [Braintrust Python SDK reference](https://docs.braintrust.dev/sdks/python/versions/latest.md)


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