Agent instructions

Running package tests with Vitest

Run Vitest for individual packages from the package that owns the tests.

cd packages/client
pnpm exec vitest --browser.headless

You can also run a single package from the repo root with a workspace filter:

pnpm --filter @elevenlabs/client exec vitest --browser.headless
pnpm --filter @elevenlabs/react exec vitest --browser.headless
pnpm --filter @elevenlabs/convai-widget-core exec vitest --browser.headless

To run a single test file, pass the file path after run:

cd packages/react
pnpm exec vitest --browser.headless src/conversation/ConversationClientTools.test.tsx

Always pass --browser.headless to avoid launching a visible browser window.

Changesets

When changing a published package in a way that should trigger a release, add a Changeset in .changeset/ before committing. Include every affected package and the appropriate bump type (patch, minor, or major) with a concise summary that can be used in the changelog.

Use pnpm run changeset when interactive prompts are practical. Otherwise, write the Changeset file directly using the standard frontmatter format:

---
"@elevenlabs/client": patch
---

Describe the user-visible package change.

ElevenAgents SDK

Build multimodal agents with ElevenAgents. Our SDKs provide seamless integration with popular JavaScript/TypeScript frameworks, enabling you to create multimodal AI agents.

Installation

npm install @elevenlabs/react

Usage

import { useConversation } from "@elevenlabs/react";

const conversation = useConversation({
  agentId: "your-agent-id",
});

// Start conversation
conversation.startSession();

Overview

The ElevenAgents SDKs provide a unified interface for integrating multimodal AI agents into your applications.

Available Packages

Package	Description	Version	Links
@elevenlabs/client	Core TypeScript/JavaScript client		README • Docs
@elevenlabs/react	React hooks and components for web applications		README • Docs
@elevenlabs/react-native	React Native SDK for cross-platform applications		README • Docs
@elevenlabs/convai-widget-core	Core widget library for embedding Agents		Docs
@elevenlabs/convai-widget-embed	Pre-bundled embeddable widget		Docs

Package Details

@elevenlabs/client

The core TypeScript/JavaScript client provides the foundation for all ElevenLabs agent integrations.

Features

• Real-time Communication: WebRTC-based audio streaming for low-latency agent interactions
• Event-driven Architecture: Comprehensive event system for agent session lifecycle management
• Client Tools: Support for custom client-side tools and functions
• Flexible Authentication: Support for both public and private agent configurations
• Audio Controls: Fine-grained control over audio input/output devices

Installation

npm install @elevenlabs/client

@elevenlabs/react

React hooks and components for building multimodal agents with React/Next.js

Installation

npm install @elevenlabs/react

@elevenlabs/react-native

React Native SDK for building cross-platform mobile agents

Installation

npm install @elevenlabs/react-native

# Install peer dependencies
npm install @livekit/react-native @livekit/react-native-webrtc livekit-client

Platform Setup

iOS

Add the following to your Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs access to your microphone for voice agent interactions.</string>

Android

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />

Widgets

The ElevenAgents Widgets provide an easy way to embed AI agents into any website as a web component.

Learn how to embed the widget into your website here.

Client Tools

Client tools allow your agent to trigger actions in your application, for example in React:

import { useConversation } from "@elevenlabs/react";

const conversation = useConversation({
  agentId: "your-agent-id",
});

// Start conversation
conversation.startSession({
  clientTools: {
    logMessage: async ({ message }) => {
      console.log(message);
    },
  },
});

Learn more here

Examples

Explore our example applications to see the SDKs in action:

• Next.JS Example
• React Native Expo Example

Documentation

For detailed documentation, visit:

• React SDK API
• React Native SDK API
• TypeScript/JavaScript Client API
• Widget

Support

• Documentation
• Discord Community
• Issues
• Support Email

Development Setup

This project uses Turbo and pnpm to manage dependencies.

# Install pnpm globally
npm install -g pnpm

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Start development mode
pnpm run dev

# If the change needs a note in the changelog / release nodes, create a changeset
pnpm run changeset

Creating a New Package

pnpm run create --name=my-new-package

Releasing

We're using Changesets to coordinate changelog entries and release notes and as such, there's no more need to create per-package tags when preparing a release.

Simply, merge the latest "Version Packages" PR opened by the Changesets action.

See the Changesets documentation for answers to common questions.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Engineered by ElevenLabs