Choose a setup method
Start with one method for a call path. Combining SDK tracking with framework
OpenTelemetry on the same call can create duplicate interactions.
Recommended: Agnost AI skill
Recommended. Choose this path when you want your coding agent to inspect the
project, select a supported transport, make the smallest instrumentation change,
send a test event, and verify that it reached Agnost AI.
1. Install the tracing extra
2. Configure the OTLP destination
Set these variables in the bot’s environment:3. Register the exporter
Callsetup_tracing once, before the bot creates its PipelineWorker. The
HTTP exporter reads the endpoint and header from the environment.
4. Enable tracing on the worker
Turn on tracing for each conversation and pass your own call and user IDs:additional_span_attributes is attached to Pipecat’s conversation span. Agnost
applies it to the whole conversation, including turns exported before the call ends.
What appears in Agnost AI
- Each LLM reply becomes one user/assistant turn: the user’s latest message and the bot’s response, in order.
- Function calls become tool calls with their arguments and results, nested under the reply that used them.
- LLM spans keep the model, token usage, time to first byte (
metrics.ttfb), and latency. - Conversation, turn, STT, and TTS spans stay visible in the trace with turn duration and interruption state.
- Every Pipecat attribute, plus your custom attributes, remains available on events.
Pipecat does not create spans for function execution. Agnost recovers each call
and its result from the context of the LLM request that follows it. This works
for OpenAI-compatible LLM services, which send context in OpenAI chat format.
Flush on shutdown
setup_tracing exports in batches. Flush before the process exits so the final
turn and the conversation span are sent:
Verify
Run one real conversation with the bot, then open Users in Agnost AI. Confirm:- The user appears under the value sent in
enduser.id. - The conversation ID matches
conversation_idand shows alternating user and assistant turns. - A turn that called a function shows the tool call with its arguments and result.
- LLM events show the model, token counts, and latency.
Troubleshooting
- Call
setup_tracingbefore creating thePipelineWorker; spans started earlier are not exported. - Set
enable_tracing=Trueon everyPipelineWorker. It is off by default. - Use the traces URL ending in
/v1/traceswith the HTTP/protobuf exporter, not the gRPC exporter from Pipecat’s Jaeger example. - Confirm
X-Agnost-Org-IDis present inOTEL_EXPORTER_OTLP_HEADERS. - Leave
enable_turn_trackingat its default (True); turn spans carry the conversation ID. - Flush the tracer provider when a short-lived bot or test exits.
References
- Pipecat: OpenTelemetry tracing
- Pipecat OpenTelemetry examples
- OpenTelemetry GenAI semantic conventions
Next steps
- Conversations: review complete voice interactions.
- Events: inspect Pipecat spans and attributes.
- Tool calls: analyze function arguments, results, errors, and latency.