> ## 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, such as ad-hoc lookups and exploration from your IDE.

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