# Pipecat

Pipecat is an open-source Python framework built by Daily for creating real-time voice and multimodal conversational AI agents. The framework supports fully programmable voice agents and multimodal interactions, providing flexibility for developers building conversational systems.

This guide covers routing telemetry from Pipecat applications to InteractiveAI for monitoring, debugging, and evaluating voice agent behavior.

<details>

<summary>Key Features</summary>

* **Hierarchical Tracing**: Track complete conversations, individual turns, and service calls
* **Service Tracing**: Detailed spans for text-to-speech, speech-to-text, and LLM services with rich context
* **TTFB Metrics**: Time To First Byte measurements for latency analysis
* **Usage Statistics**: Character counts for text-to-speech and token usage for LLMs

</details>

### Prerequisites

* InteractiveAI account with API credentials
* Service API keys (Deepgram, Cartesia, OpenAI, or alternatives)&#x20;

***

### Trace Structure

Traces organize hierarchically by conversation and turn:

```
Conversation (conversation-uuid)
├── turn-1
│   ├── stt_deepgramsttservice
│   ├── llm_openaillmservice
│   └── tts_cartesiattsservice
└── turn-2
    ├── stt_deepgramsttservice
    ├── llm_openaillmservice
    └── tts_cartesiattsservice
    turn-N
    └── ...
```

This structure enables analysis at the conversation level and turn-by-turn inspection.

***

### Configuration

#### Encode API Credentials

Base64 encode your InteractiveAI public and secret key:

```bash
echo -n "pk-ia-YOUR_PUBLIC_KEY:sk-ia-YOUR_SECRET_KEY" | base64
```

#### Environment Variables

Create a `.env` file with your credentials:

```env
ENABLE_TRACING=true

# OTLP endpoint for InteractiveAI
OTEL_EXPORTER_OTLP_ENDPOINT=https://app.interactiveai.com/api/public/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic%20<base64_encoded_api_key>

# Enable console output for debugging (optional)
# OTEL_CONSOLE_EXPORT=true

# Service API keys
DEEPGRAM_API_KEY=your_key_here
CARTESIA_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
```

***

### Installation

```bash
uv sync
```

Use only the HTTP exporter. If conflicts occur, uninstall the gRPC exporter.

***

### Enabling Tracing

Configure OpenTelemetry with the HTTP exporter in your application:

```python
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Exporter reads configuration from environment variables
exporter = OTLPSpanExporter()

setup_tracing(
    service_name="pipecat-project",
    exporter=exporter,
)

# Enable tracing in your PipelineTask
task = PipelineTask(
    pipeline,
    params=PipelineParams(
        allow_interruptions=True,
        enable_metrics=True,  # Required for service metrics
    ),
    enable_tracing=True,  # Activates turn and conversation tracing
    conversation_id="customer-1",  # Optional - auto-generates if omitted
)
```

***

### Running the Application

```bash
uv run bot.py
```

***

### Trace Visibility

InteractiveAI then displays:

* Complete conversation flows with turn-by-turn breakdown
* Speech-to-text transcriptions and language detection
* LLM requests with prompts, completions, and token counts
* Text-to-speech synthesis with voice configuration and character usage
* Time To First Byte metrics for latency optimization
* Service-level performance data and processing durations


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.interactive.ai/integrations/ai-frameworks/pipecat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.