ElevenLabs SDK — Field Guide
REV 2026-08-03PAGES 10STATUS CURRENT

SEC 05 / AGENTS

Agents SDKs

Agents SDKs cover the conversational, full-duplex side of the ecosystem: microphone in, audio out, WebRTC transport, and a growing list of client platforms. Every platform here shares the same underlying concern — keeping your permanent ElevenLabs API key off the device while still giving it a credential it can use.

Browser: @elevenlabs/client

This is the correct package for non-React browser applications. It owns browser-specific behaviour: microphone access, audio output, WebRTC sessions, conversation lifecycle, client tools, and real-time transcription.

A public agent can generally be opened directly from its agent identifier. A private agent should instead use a short-lived signed URL or conversation credential obtained from your backend. The permanent API key must never appear in browser code.

React: @elevenlabs/react

The React SDK re-exports the client functionality and wraps it in React context and hooks. Its current architecture is a ConversationProvider plus focused hooks for controls, status, input, mode, feedback, raw events, and client tools — rather than one large monolithic hook.

A recommended application boundary looks like this:

React UI
   │
   ├── your backend: authenticates user and authorizes agent access
   │       └── ElevenLabs REST API using permanent API key
   │
   └── ElevenLabs real-time service
           └── short-lived signed URL or conversation token

The browser gets direct, low-latency media transport without ever holding the long-lived API key.

Mobile at a glance

Platform Transport Notable constraint
React Native LiveKit/WebRTC peer dependencies Expo projects need a development build — it does not run inside Expo Go, since native WebRTC modules are involved
Swift LiveKit WebRTC, Swift concurrency iOS 13+/macOS 10.15+ baseline (also Mac Catalyst 14+, visionOS 1, tvOS 17); private-agent credentials should come from a trusted backend, not the app bundle
Kotlin/Android WebRTC voice sessions, plus text-only WebSocket sessions Voice needs runtime microphone permission; voice and text sessions use different ephemeral credential forms (conversation tokens vs. signed URLs) from your backend
Flutter LiveKit/WebRTC, reactive conversation state iOS 13 and Android API level 21 baseline

Every platform above pushes the same rule down to a different SDK surface: credentials for private agents come from your backend at session start, not from a key baked into the client.

Going deeper: real-device lifecycle testing checklist

The React Native docs spell this out explicitly, but it applies in spirit to every mobile platform above — voice sessions touch OS-level resources that simulators and unit tests won’t exercise realistically. Test at least:

  • iOS and Android permission flows;
  • Bluetooth route changes;
  • headphones being connected or removed;
  • backgrounding and foregrounding;
  • interruption by telephone calls;
  • session reconnection;
  • microphone release after ending a session.
Going deeper: the next-major migration warning

The official TypeScript repository contains a next-major migration guide describing significant future changes to the Agents surface, including:

  • stronger reliance on ConversationProvider;
  • Conversation becoming more of a namespace/type than an instantiated class;
  • granular hooks replacing broader interfaces;
  • changes to startSession;
  • removal or restructuring of direct input/output abstractions.

That guide concerns the coming major version, not the present stable API — but it’s a clear signal that the Agents surface is actively evolving. Pin stable versions, and don’t copy examples from unreleased migration documentation into stable applications without checking package versions first.

References