Overview
OpenAILiveLLMService provides full-duplex speech-to-speech conversation using OpenAI’s GPT-Live API and the gpt-live-1 model. The GPT-Live model listens and speaks at the same time: it decides on its own when to answer, stops when the user talks over it, and delegates work that needs search, reasoning, or tools to a backend text model while the conversation continues. The pipeline streams audio in and plays audio out; there is no client-side turn detection or response triggering.
The backend runs in one of two delegation modes. In Responses delegation, OpenAI hosts the backend: a Responses API model you configure with OpenAILiveLLMService.ResponsesDelegation, using the tools from your pipeline’s LLMContext as normal. In client delegation, the backend is any Pipecat LLM service running in a BackendLLMWorker you provide, configured with OpenAILiveLLMService.ClientDelegation, with tools of its own.
OpenAI GPT-Live API Reference
Pipecat’s API methods for GPT-Live integration
Example Implementation
Complete GPT-Live conversation example with Responses delegation
Client Delegation Example
Delegating to a Pipecat backend worker running another LLM
OpenAI Documentation
Official GPT-Live documentation
OpenAI Platform
Access GPT-Live models and manage API keys
Installation
To use GPT-Live, install the required dependencies:Prerequisites
OpenAI Account Setup
Before using GPT-Live, you need:- OpenAI Account: Sign up at OpenAI Platform
- API Key: Generate an OpenAI API key from your account dashboard
- Model Access: Ensure access to the
gpt-live-1model - Usage Limits: Configure appropriate usage limits and billing
Required Environment Variables
OPENAI_API_KEY: Your OpenAI API key for authentication
Key Features
- Full-Duplex Speech-to-Speech: The model listens while it speaks and handles interruptions itself
- Delegation: Tool use and heavier reasoning run on a backend model while the conversation continues
- Two Backend Modes: Responses delegation, where OpenAI hosts the backend model, or client delegation, where any Pipecat LLM service runs as the backend in a
BackendLLMWorker - Function Calling: In Responses delegation mode, the functions registered in your pipeline, written as for any other LLM service; in client delegation mode, the functions registered in the backend worker’s pipeline
- Conversation Seeding: Prior conversation history is loaded into the session at start
Configuration
OpenAILiveLLMService
str
required
OpenAI project API key for authentication.
str
default:"wss://api.openai.com/v1/live/sessions"
WebSocket base URL of the GPT-Live API. Override for custom or proxied
deployments.
ResponsesDelegation | ClientDelegation | None
default:"None"
Where the model’s delegated work runs. See
ResponsesDelegation and
ClientDelegation below.
None selects client delegation
with no backend configured, so delegated requests are declined.Any
Additional arguments passed to parent LLMService.
Settings
Settings passed via thesettings constructor argument using OpenAILiveLLMService.Settings(...). See Service Settings for details.
None values are omitted, letting the service use its own defaults. The API
fixes model, voice, store and system_instruction when the session
starts, so a change sent with LLMUpdateSettingsFrame is stored, logged as
unsupported for the session in progress, and applied to the next session
started by reset_conversation().ResponsesDelegation
OpenAI hosts the backend model. Passed asdelegation=OpenAILiveLLMService.ResponsesDelegation(...).
OpenAIResponsesLLMService.Settings
required
Request settings for the backend model, the same object
OpenAIResponsesLLMService
takes. model is required. system_instruction becomes the backend’s
instructions, max_completion_tokens its max_output_tokens, and reasoning
is sent when configured. Fields the GPT-Live API does not accept for a
delegated model (temperature, top_p, the penalties, seed, top_k,
max_tokens, user_turn_completion_config, filter_incomplete_user_turns)
are dropped with a warning. extra is merged into the delegation
configuration.str | None
default:"None"
Responses API service tier for delegated requests:
"auto", "default",
"flex" or "priority".tool_choice come from the pipeline’s LLMContext. Its function calls are executed by the service with the handlers registered for those tools, and results go back to the API as soon as they are available. Tools changed with LLMSetToolsFrame reach the session as a sparse update.
ClientDelegation
A Pipecat worker is the backend. Passed asdelegation=OpenAILiveLLMService.ClientDelegation(...).
BackendLLMWorker | str
required
The worker that runs delegated tasks, normally a
BackendLLMWorker wrapping any LLM service. The service
registers it as a child of the pipeline worker at setup, so the pipeline must
run under a WorkerRunner. A string names a backend worker registered
elsewhere, in the app or in another process on a shared bus.float
default:"120.0"
How long a delegation may take before it is abandoned. The model is told that
the delegated work could not be completed.
prefers_spoken flag: text the backend wants heard is appended as commentary, which the model relays in its own words, and the rest as silent context the model can draw on.
BackendLLMWorker
pipecat.workers.llm.BackendLLMWorker runs an LLM service as the backend a GPT-Live model delegates to. It owns the backend’s conversation, an LLMContext plus aggregator pair, so multi-step tool calling works as it does in any pipeline.
LLMService
required
The backend LLM service.
LLMContext
default:"None"
The backend’s context, typically carrying its tools. A fresh empty context
when omitted.
str
default:"None"
Worker name; auto-generated when omitted. Give one when the backend runs in
another process, where the frontend addresses it by name.
Callable[[BackendOutput], Awaitable[BackendOutput | None]]
default:"None"
Called with each
BackendOutput the model produces before
it is sent, to adjust its text or whether the user may hear it. Return None
to send nothing for an output.str
default:"BACKEND_PAIRING_INSTRUCTION"
Text appended to the backend LLM’s system instruction about working as the
backend of a voice assistant, including how to mark what the user should hear.
Rarely worth replacing: a replacement that leaves out the marking leaves
nothing spoken. To shape what the user hears, use the backend’s own system
instruction instead (see Choosing What the User
Hears).
LLMUserAggregatorParams
default:"None"
Parameters for the backend’s user aggregator. Defaults to
ExternalUserTurnStrategies, since the backend has no audio.LLMAssistantAggregatorParams
default:"None"
Parameters for the backend’s assistant aggregator.
send_output(output, *, apply_transform_output=False) sends a BackendOutput of the app’s own, such as from a tool, alongside the model’s. It skips transform_output unless apply_transform_output=True. See Choosing What the User Hears.
BackendOutput
One piece of output from a backend, on its way to the GPT-Live model.Usage
Responses Delegation Mode
Client Delegation Mode
Any Pipecat LLM service can be the backend, with its own context and tools:backend to the runner as a child of the pipeline worker, so the pipeline must run under a WorkerRunner as in the example above.
Choosing What the User Hears
The backend’s model decides which of what it writes the user hears. It speaks up for a result, a question it cannot proceed without, or news the user should have now, and works through the steps in between in silence. What it chooses to say arrives withprefers_spoken=True. To shape that judgment, say in the backend’s own system instruction, in plain words, what the user should and should not be told.
When something must be said as given, such as a booking system’s confirmation code, a tool can send it itself with send_output, whatever the model would have chosen to say:
transform_output can drop one, rewrite it, or change whether it is spoken.
Restoring a Conversation
The GPT-Live API takes conversation history only at session start. To replace the context, for example with a saved conversation, set the messages and start a new session:Methods
reset_conversation()
Notes
- Turn taking is the model’s: The service proposes user turn boundaries from the API’s transcript stream, and
LLMContextAggregatorPairresolves them with the recommendedExternalUserTurnStrategies(enable_interruptions=False). NoInterruptionFrameis broadcast: the model handles being talked over itself, and a delegation keeps running when that happens. As a consequence every tool behaves ascancel_on_interruption=False; usecancellable_by_llm=Truefor tools the model should be able to cancel on request. - No local VAD: The model detects the user’s turns itself, so the pipeline needs no VAD analyzer and no
realtime_service_modeon the aggregators. The user aggregator writes each user turn to the context as it ends, before any tool calls it triggers. - Session start: The session starts on the first
LLMContextFrame, typically queued as anLLMRunFrame. The context’s leading system message (orSettings.system_instruction) becomes the model’s instructions and the remaining text messages seed the session as prior conversation. At most 128 messages are kept, dropping the oldest; tool calls, tool results and non-text content have no representation in the startup history and are skipped. Input audio is dropped until the session has started. - Opening the conversation: A trailing developer message in the context is delivered to the model once the session starts, as the request to speak first. Omit it to have the model wait for the user.
- System instruction precedence:
system_instructionfrom service settings takes precedence over an initial system message in the LLM context. A warning is logged when both are set. - Tools belong to the backend: The GPT-Live model calls no tools of its own. In Responses delegation mode this is invisible to your code: register functions and write their handlers as for any other LLM service, and the backend model calls them through the pipeline. In client delegation mode the
BackendLLMWorker’s own context carries the tools, and its pipeline runs them. - Audio format: Input audio is resampled to 24 kHz; output is 24 kHz PCM, pushed as
SpeechOutputAudioRawFrameso the output transport derives bot speaking state from the audio itself. - Usage metrics: GPT-Live usage, in cumulative session seconds, is logged at debug level and not reported as a metric. Token usage metrics come from the backend model’s completed responses in Responses delegation.
- Delegation failures: When a client delegation fails, the model is told the delegated work could not be completed and the detail is pushed as an
ErrorFrame. A delegation that times out pushes noErrorFrame. A delegation that finishes without producing any output meant to be spoken is reported to the model as having no answer, so the conversation moves on.