React voice agent adapters

Choose an orb-ui adapter when a provider SDK owns your voice session but your React UI needs one consistent state and audio-level contract. The provider guides linked here are the canonical setup pages for each integration. Every provider integration follows the same UI pattern:

const adapter = createProviderAdapter(/* provider connection */)

export function VoiceUI() {
  return <Orb adapter={adapter} theme="circle" aria-label="Start voice assistant" />
}

The orb subscribes to the adapter and calls its start() and stop() methods. The adapter converts provider events into idle, connecting, listening, thinking, speaking, and error signals, including normalized input and output volume when the provider exposes audio.

Compare providers and integration styles

Provider	Browser code you provide	What orb-ui owns
Vapi	A configured `Vapi` client and assistant ID	Provider event mapping, SDK microphone track metering, and output metering
ElevenLabs	The `Conversation` class and agent/session credential	Session lifecycle, state mapping, playback, and both volume levels
LiveKit	A token endpoint and optional agent name	SDK setup, room lifecycle, agent discovery, playback, and both volume levels
Pipecat	A configured `PipecatClient` and its connect callback	RTVI state mapping, remote playback, and both volume levels
OpenAI GPT-Live	A callback that exchanges SDP through your server	Browser WebRTC, full-duplex metering, playback, and session finalization
OpenAI Realtime	A callback that returns a fresh client secret	Browser WebRTC, microphone, playback, state, and both volume levels
Gemini Live	A callback that opens the official Google Live session	Microphone PCM streaming, turn detection, playback, state, and both volume levels
Retell	Current WebCall client and session options	Session event mapping and supported audio snapshots
Hume EVI	Existing VoiceProvider/useVoice session	Controlled state and FFT bridge; app retains audio ownership
Deepgram	Browser Agent SDK or existing React provider	Managed browser audio or controlled React bridge
Agora	Conversational AI toolkit plus app RTC client	Agent state, interruption, and supplied audio levels
Azure Voice Live	Fresh authenticated JavaScript SDK session	PCM capture/playback, state, interruption, and cleanup
Cartesia	Scoped short-lived managed-agent WebSocket URL	PCM media, agent events, interruption, and cleanup
Nova 2 Sonic	Your Node/Socket.IO/Bedrock application	Controlled bridge; full-stack recipe supplies transport and media

The seven expansion integrations are available in orb-ui@0.10.0 and later. Their tests use real SDK types and synthetic events; no credential-based live provider test has been run. The individual guides document current SDK versions and limits. All public previews use local fixtures. For live applications, authenticate and limit your own backend, keep provider secrets server-side, and mint short-lived browser session credentials. The public site has no provider proxy or owner-funded voice endpoint. Choose based on who should own the session:

If your app already uses Vapi or Pipecat’s browser client, wrap that existing client.
If you want orb-ui to own browser media and connection lifecycle, use OpenAI Live, OpenAI Realtime, or a managed ElevenLabs or LiveKit setup.
If the provider requires an app-owned SDK connection, use Gemini Live’s connect callback.
If your application already normalizes session state, use controlled mode.
If the mapping will be shared across screens or projects, build a custom OrbAdapter using the signal architecture guide.

Provider authentication stays explicit. Standard OpenAI and Gemini API keys belong on your server; the browser receives the Live SDP answer or short-lived Realtime/Gemini credentials. LiveKit participant tokens should also be minted on a server. Pipecat Cloud can use its public agent-start key in the browser while private deployment credentials remain server-side. LiveKit’s recommended browser entrypoint keeps the SDK mechanical details out of application code:

import { createLiveKitAdapter } from 'orb-ui/adapters/livekit'

const adapter = createLiveKitAdapter({
  tokenEndpoint: '/api/livekit-token',
  agentName: 'your-agent-name',
})

It creates a fresh room name for every start. Import the advanced factory from orb-ui/adapters only when your app already owns a Room, token source, custom connection fetcher, or runtime helpers.

The three connection shapes

Most adapters fit one of three small patterns.

Wrap an existing provider client

Vapi and Pipecat already have a browser client. Pass that client to orb-ui:

const adapter = createVapiAdapter(vapi, { assistantId })

const pipecatAdapter = createPipecatAdapter(pipecatClient, {
  connect: () => pipecatClient.connect({ webrtcUrl: '/api/offer' }),
})

Let orb-ui own the browser session

OpenAI GPT-Live uses native browser WebRTC. Exchange the SDP offer through your server:

const adapter = createOpenAILiveAdapter({
  createSession: async (sdp, signal) => {
    const response = await fetch('/api/openai-live-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sdp }),
      signal,
    })
    if (!response.ok) throw new Error('Could not create a Live session')
    return response.json()
  },
})

Start with the Live guide for server configuration. Existing Realtime sessions continue to use createOpenAIRealtimeAdapter({ getClientSecret }); the two APIs have different endpoints and event lifecycles.

Let the official SDK open the session

Gemini Live session creation stays in the application because @google/genai is an app-owned, optional dependency. orb-ui receives the connected session through one callback:

const adapter = createGeminiLiveAdapter({
  connect: async (callbacks) => {
    const token = await fetch('/api/gemini-live-token', { method: 'POST' }).then((response) =>
      response.json(),
    )
    const client = new GoogleGenAI({
      apiKey: token.value,
      httpOptions: { apiVersion: 'v1alpha' },
    })
    return client.live.connect({ model: token.model, config: token.config, callbacks })
  },
})

The adapter uses client-side activity detection by default, so the matching Gemini session config must disable automatic activity detection. The adapter sends explicit activity start/end markers using its local voice detector. Set activityDetection: 'server' only when the Gemini session keeps automatic activity detection enabled.

Advanced options stay optional

The adapter guides document alternate transports, existing-session modes, runtime overrides, and audio calibration hooks. Those options are escape hatches. Start with the first example in each guide and add advanced configuration only when your application already owns that part of the provider lifecycle.

Migrating calibration overrides in 0.8.0

The outputVolumeCalibration option remains, but its fields have changed. Replace the old noiseFloor, gain, exponent, attack, and release object with optional amplitude and envelope overrides:

amplitude.silenceFloor: raw activity treated as silence
amplitude.speechReference: raw ordinary speech mapped to 0.5
amplitude.speechPeak: raw strong speech mapped to 1
envelope.riseTimeMs and envelope.fallTimeMs: milliseconds to move 90% toward a new target

Remove old overrides to use the measured provider defaults. If your audio path needs a custom profile, use the playground’s guided calibration capture to measure new anchors. The old gain and curve values are not amplitude anchors, and per-sample attack/release rates do not directly convert to elapsed milliseconds. inputVolumeCalibration accepts the same new shape independently. Update any public type or constant imports:

Before 0.8.0	Replacement
`OutputVolumeCalibration`	`VolumeCalibration`
`OutputVolumeCalibrationSource`	`VolumeCalibrationSource`
`OutputVolumeSample`	`VolumeSample`
`DEFAULT_OUTPUT_VOLUME_CALIBRATION`	`DEFAULT_VOLUME_CALIBRATION`

Use VolumeCalibrationOverrides for a partial configuration and PROVIDER_VOLUME_CALIBRATIONS for the shipped provider-specific defaults. Diagnostic samples now expose mapped instead of shaped, along with raw, normalized, and elapsedMs. Controlled integrations must also replace the removed volume field with inputVolume and outputVolume. Before choosing a provider, use the React voice agent UI guide to plan the listening, thinking, speaking, error, accessibility, and recovery behavior shared by every integration.

To understand the provider-independent API behind every option, read Build a provider-agnostic, signal-based voice agent UI in React.

Start

Reference

Adapters

Recipes

Guides

React voice agent adapters

Compare providers and integration styles

The three connection shapes

Wrap an existing provider client

Let orb-ui own the browser session

Let the official SDK open the session

Advanced options stay optional

Migrating calibration overrides in 0.8.0

​Compare providers and integration styles

​The three connection shapes

​Wrap an existing provider client

​Let orb-ui own the browser session

​Let the official SDK open the session

​Advanced options stay optional

​Migrating calibration overrides in 0.8.0

Compare providers and integration styles

The three connection shapes

Wrap an existing provider client

Let orb-ui own the browser session

Let the official SDK open the session

Advanced options stay optional

Migrating calibration overrides in 0.8.0