Trace Pipecat applications

This integration is in beta, so its API may change.

Trace your Pipecat voice agents to LangSmith with the LangSmith Pipecat integration. For high-level conventions, see Voice tracing fundamentals.

The Pipecat integration requires langsmith[pipecat]>=0.9.7.

The integration hooks into the spans Pipecat already emits and maps them onto LangSmith’s tracing format, so each conversation becomes a single LangSmith trace, with a span per pipeline stage (STT, LLM, TTS).

Install

Install the integration along with the Pipecat service extras your pipeline uses:

pip

pip install "langsmith[pipecat]" "pipecat-ai[openai,local,tracing]"

uv add "langsmith[pipecat]" "pipecat-ai[openai,local,tracing]"

Set environment variables

The integration reads your LangSmith credentials from the environment and exports to LangSmith for you via OpenTelemetry:

.env

LANGSMITH_API_KEY=<your-langsmith-api-key>
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=pipecat-voice
OPENAI_API_KEY=<your-openai-api-key>

Set up tracing

Import configure_pipecat and call it once before building your pipeline. Enable tracing on the PipelineTask:

from langsmith.integrations.pipecat import configure_pipecat
from pipecat.pipeline.task import PipelineParams, PipelineTask

# Install the tracer and the LangSmith span processor.
configure_pipecat()

task = PipelineTask(
    pipeline,
    params=PipelineParams(enable_metrics=True),
    enable_tracing=True,
    enable_turn_tracking=True,
    conversation_id=conversation_id,
)

Set enable_tracing=True, enable_turn_tracking=True, and enable_metrics=True. Turn tracking is required for tracing, and metrics drive the latency and token data on each span.

Use a LangGraph or LangChain agent as the LLM

If your LLM stage is an in-process LangGraph or LangChain agent, its model and tool runs should nest inside Pipecat’s llm span rather than forming a separate trace. To achieve this:

• Pass configure_pipecat(llm_span_kind="chain"). This avoids nested llm spans that don’t actually represent inference requests.
• Set LANGSMITH_TRACING_MODE=otel in the environment. Without it, those runs post to LangSmith directly and form a separate trace instead of nesting.

Use your own tracer provider

configure_pipecat() builds a TracerProvider, registers the LangSmith span processor, and wires it into Pipecat. To send spans through a TracerProvider you already manage (for example, one that also exports to another OpenTelemetry backend), skip configure_pipecat and add the processor to your provider directly:

from langsmith.integrations.pipecat import PipecatLangSmithSpanProcessor

provider.add_span_processor(PipecatLangSmithSpanProcessor())

Group a conversation into a thread

To group a conversation’s runs into a LangSmith thread for thread-level views and token and cost aggregation, call set_thread_id once per conversation before its spans are emitted:

from langsmith.integrations.pipecat import configure_pipecat, set_thread_id

configure_pipecat()
set_thread_id(conversation_id)

Record the conversation audio

Attach the conversation audio to the trace using Pipecat’s AudioBufferProcessor. Place it after transport.output() so it captures what was actually played (after any barge-in truncation), hand it to the integration, and start it once the session is running:

from pipecat.processors.audio.audio_buffer_processor import AudioBufferProcessor

span_processor = configure_pipecat()

# Stereo: user on the left channel, agent on the right.
audiobuffer = AudioBufferProcessor(num_channels=2, buffer_size=32_000)
span_processor.attach_audio_buffer(audiobuffer, conversation_id=conversation_id)

pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,
    transport.output(),
    audiobuffer,                     # after output(): records what was heard
    context_aggregator.assistant(),
])

await audiobuffer.start_recording()

The integration attaches the recording to the conversation root when it ends. For the underlying attachment API, see Upload files with traces.

Next steps

Voice fundamentals

Core conventions for tracing voice agents.

Upload files with traces

Attach the conversation audio recording to your trace.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.