Skip to main content

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:
  1. OpenAI Account: Sign up at OpenAI Platform
  2. API Key: Generate an OpenAI API key from your account dashboard
  3. Model Access: Ensure access to the gpt-live-1 model
  4. 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.
OpenAILiveLLMService.Settings
default:"None"
Runtime-updatable settings. See Settings below.
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 the settings 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 as delegation=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".
The backend model’s tools and 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 as delegation=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.
A delegation names no task: the GPT-Live model signals only that it is handing work over. The service sends the backend the transcript of the conversation since the previous delegation, and the backend works out the request from it. Delegations run one at a time: one created while another is in progress waits for it to finish. Each turn the backend’s model writes is sent as soon as it is produced and appended to the live session according to its 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:
The service adds 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 with prefers_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:
The result lets the model know the user has already been told. For code that should see every output the model produces, 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()

Drops the session and starts a new one configured from the context as it is now. See Restoring a Conversation.

Notes

  • Turn taking is the model’s: The service proposes user turn boundaries from the API’s transcript stream, and LLMContextAggregatorPair resolves them with the recommended ExternalUserTurnStrategies(enable_interruptions=False). No InterruptionFrame is broadcast: the model handles being talked over itself, and a delegation keeps running when that happens. As a consequence every tool behaves as cancel_on_interruption=False; use cancellable_by_llm=True for 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_mode on 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 an LLMRunFrame. The context’s leading system message (or Settings.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_instruction from 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 SpeechOutputAudioRawFrame so 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 no ErrorFrame. 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.

Event Handlers