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.
NOT_GIVEN values are omitted, letting the service use its own defaults ("gpt-live-1" for model). The API fixes model, voice 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) are dropped with a warning.
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(...).
BaseWorker
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.
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. What comes back is appended to the live session according to each output’s 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.
Callable[[BackendOutput], Awaitable[BackendOutput]]
default:"None"
Called with each BackendOutput before it is sent, to adjust its text or whether the user may hear it. Without one, only the final answer asks to be spoken.
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.

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

By default only the backend’s final answer asks to be spoken. A transform_output callback sees every BackendOutput before it leaves the worker and can change that, or rewrite the text:

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:

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.
  • 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 is reported as cumulative session seconds. Token usage comes from the backend model’s completed responses in Responses delegation.
  • Delegation failures: When a client delegation fails or times out, the model is told the delegated work could not be completed and the detail is pushed as an ErrorFrame. A delegation that finishes without producing any text is reported to the model as having no answer, so the conversation moves on.

Event Handlers