Trace OpenAI Realtime sessions

Add the maintained traceAI-openai-realtime instrumentor to your OpenAI Python client to inspect Realtime sessions in Future AGI Observe.

Before you start

Use Python 3.10 to 3.13 and the server-side OpenAI Realtime API, opened with client.realtime.connect(). This instrumentor does not trace client.beta.realtime, browser WebRTC sessions, or voice pipelines managed by frameworks such as LiveKit and Pipecat.

Install

python -m pip install traceAI-openai-realtime

The package is published on PyPI. It declares the OpenAI Realtime client dependency as openai[realtime]>=2.0.0,<4.

Set credentials

Provide your Future AGI keys and OpenAI API key in the environment. For a self-hosted Future AGI instance, also set FI_BASE_URL to your collector origin.

export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"
export OPENAI_API_KEY="your-openai-api-key"

Register and instrument

Register the Future AGI provider and instrument the OpenAI Realtime client once, before your application opens a session.

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_openai_realtime import OpenAIRealtimeInstrumentor

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="my-voice-agent",
)
OpenAIRealtimeInstrumentor().instrument(tracer_provider=trace_provider)

Your existing client.realtime.connect() code can stay as it is. The instrumentor records server-side Realtime sessions, including user turns, model responses, function calls, and server errors. To include what the user said in user turns and the Voice transcript, enable input audio transcription in your session.update.

Run a complete example

Download the maintained voice_agent.py example into your application directory. It includes instrumentation, a Realtime session, audio handling, and a sample function tool. The tool returns sample weather data; replace it with your application’s tool before using it for real tasks.

Set the credentials above, then run a typed question. The example returns a spoken answer and exercises a function call without requiring a microphone.

python voice_agent.py --typed "What's the weather in Paris?" --project my-voice-agent

To use a model other than the example’s default, pass --model with a model available to your OpenAI project. For the complete Realtime event and audio workflow, see OpenAI’s Realtime guide, server events, and client events.

Open the trace

In Observe, select your project. Audio sessions appear in Voice and Tracing; text-only sessions appear in Tracing.

Privacy

The instrumentor does not add audio bytes to traces. It captures session text—such as instructions, transcripts, tool arguments and results, and error messages—by default. Set FI_HIDE_INPUTS=true and FI_HIDE_OUTPUTS=true before starting your application, or pass TraceConfig(hide_inputs=True, hide_outputs=True) to instrument(), to omit input and output content. See trace configuration and mask span attributes for the limits of those controls; avoid adding sensitive values to your own span attributes.

Troubleshooting

• No trace appears: call register() before instrument(), and instrument before opening a Realtime connection. Check that the Future AGI and OpenAI keys are present in the process environment.
• The session appears only in Tracing: text-only Realtime sessions are traces, not voice calls. Audio sessions are also listed in the Voice view.