Pipecat | Respan Docs

Pipecat is an open-source framework for building real-time, multimodal AI applications. It provides a pipeline architecture for voice agents, video processing, and other real-time experiences with support for speech-to-text, LLMs, and text-to-speech. Respan gives you full observability over every pipeline run, frame, LLM call, and STT/TTS step — and gateway routing through the OpenAI-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key. For gateway, also add credits or a provider key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Python examples

Tracing

Gateway

Setup

Install packages

$ pip install respan-ai openinference-instrumentation-pipecat pipecat-ai

Set environment variables

$ export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

OPENAI_API_KEY is used for LLM requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

1 import os
2 import asyncio
3 from pipecat.pipeline.pipeline import Pipeline
4 from pipecat.pipeline.runner import PipelineRunner
5 from pipecat.pipeline.task import PipelineTask
6 from pipecat.services.openai import OpenAILLMService
7 from respan import Respan
8 from openinference.instrumentation.pipecat import PipecatInstrumentor
9 
10 respan = Respan(instrumentations=[PipecatInstrumentor()])
11 
12 async def main():
13     llm = OpenAILLMService(
14         api_key=os.environ["OPENAI_API_KEY"],
15         model="gpt-4.1-nano",
16     )
17 
18     pipeline = Pipeline([llm])
19     task = PipelineTask(pipeline)
20     runner = PipelineRunner()
21     await runner.run(task)
22 
23     respan.flush()
24 
25 asyncio.run(main())

View your trace

Open the Traces page to see your Pipecat pipeline with frame processing, LLM calls, and real-time latency metrics.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate (e.g. `PipecatInstrumentor()`).
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

Attributes

In Respan()

Set defaults at initialization — these apply to all spans.

1 from respan import Respan
2 from openinference.instrumentation.pipecat import PipecatInstrumentor
3 
4 respan = Respan(
5     instrumentations=[PipecatInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "voice-agent", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request using a context scope.

1 from respan import Respan, propagate_attributes
2 from openinference.instrumentation.pipecat import PipecatInstrumentor
3 
4 respan = Respan(instrumentations=[PipecatInstrumentor()])
5 
6 async def handle_session(user_id: str):
7     with propagate_attributes(
8         customer_identifier=user_id,
9         thread_identifier="session_abc_123",
10         metadata={"plan": "pro"},
11     ):
12         await runner.run(task)

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.