> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[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.

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <Note>
    Requires `pipecat-ai` v1.3.0 or later and Python 3.11 or later.
  </Note>

  <h2 id="setup-python">
    Setup
  </h2>

  <Steps>
    <Step title="Install packages">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      pip install braintrust "pipecat-ai[openai]>=1.3.0"
      ```
    </Step>

    <Step title="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
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

  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 title="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>

  <Accordion title="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>

  <Accordion title="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,
    )
    ```
  </Accordion>

  <h2 id="manual-instrumentation-python">
    Manual instrumentation
  </h2>

  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])
  ```

  <h2 id="what-traced-python">
    What Braintrust traces
  </h2>

  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.

  <h2 id="resources-python">
    Resources
  </h2>

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