ElevenLabs Agent Builder

Build a production-ready conversational AI voice agent. Produces a configured agent with tools, knowledge base, and SDK integration.

Packages

npm install @elevenlabs/react # React SDK npm install @elevenlabs/client # JavaScript SDK (browser + server) npm install @elevenlabs/react-native # React Native SDK npm install @elevenlabs/elevenlabs-js # Full API (server only) npm install -g @elevenlabs/agents-cli # CLI ("Agents as Code")

DEPRECATED: @11labs/react , @11labs/client — uninstall if present.

Server-only warning: @elevenlabs/elevenlabs-js uses Node.js child_process and won't work in browsers. Use @elevenlabs/client for browser environments, or create a proxy server.

Workflow

Step 1: Create Agent via Dashboard or CLI

Dashboard: https://elevenlabs.io/app/conversational-ai → Create Agent

CLI (Agents as Code):

elevenlabs-cli init my-agent

Edit agent.config.ts with agent settings

elevenlabs-cli deploy

Configure:

• Voice — Choose from 5000+ voices or clone

• LLM — GPT, Claude, Gemini, or custom

• System prompt — See assets/system-prompt-template.md

• First message — What the agent says when conversation starts

Step 2: Add Tools

Tools let the agent take actions during conversation:

// Client-side tools (run in browser) const clientTools = { navigate: { description: "Navigate to a page", parameters: { type: "object", properties: { url: { type: "string" } } }, handler: async ({ url }) => { window.location.href = url; return "Navigated"; } } };

// Server-side tools (webhooks) // Configure in dashboard: Settings → Tools → Add Webhook

See references/tool-examples.md for patterns.

Step 3: Add Knowledge Base (RAG)

Upload documents for the agent to reference:

• PDFs, text files, web URLs

• Configure via dashboard or API

• Agent automatically searches knowledge base during conversation

Step 4: Integrate SDK

React — copy and customise assets/react-sdk-boilerplate.tsx :

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

const { startConversation, stopConversation, status } = useConversation({ agentId: 'your-agent-id', signedUrl: '/api/elevenlabs/auth', clientTools, onEvent: (event) => { /* transcript, agent_response, tool_call */ }, });

React Native — see assets/react-native-boilerplate.tsx

Widget embed — see assets/widget-embed-template.html

Swift — see assets/swift-sdk-boilerplate.swift

Step 5: Test and Deploy

Test locally

elevenlabs-cli test my-agent

Simulate conversation

elevenlabs-cli simulate my-agent --scenario "Book appointment for tomorrow"

Deploy

elevenlabs-cli deploy my-agent

Before deploying, run a dry-run first: elevenlabs-cli deploy my-agent --dry-run to review changes.

For conversation simulation, create a JSON test scenario based on assets/simulation-template.json .

Critical Patterns

Signed URLs (Security)

Never expose API keys in client code. Use a server endpoint:

// Server endpoint app.get('/api/elevenlabs/auth', async (req, res) => { const response = await fetch('https://api.elevenlabs.io/v1/convai/conversation/get-signed-url', { headers: { 'xi-api-key': process.env.ELEVENLABS_API_KEY }, body: JSON.stringify({ agent_id: 'your-agent-id' }), method: 'POST' }); const { signed_url } = await response.json(); res.json({ signed_url }); });

Agent Versioning (A/B Testing)

Create version branches for testing different configurations:

• Dashboard: Agent → Versions → Create Branch

• Compare metrics between versions

• Promote winning version to production

Dynamic Variables

Pass user context to the agent's system prompt:

const { startConversation } = useConversation({ agentId: 'your-agent-id', dynamicVariables: { user_name: 'John', account_type: 'premium', } });

System prompt references them as {{user_name}} .

Asset Files

• assets/react-sdk-boilerplate.tsx — React integration template

• assets/react-native-boilerplate.tsx — React Native template

• assets/swift-sdk-boilerplate.swift — Swift/iOS template

• assets/javascript-sdk-boilerplate.js — Vanilla JS template

• assets/widget-embed-template.html — Embeddable widget

• assets/system-prompt-template.md — System prompt guide

• assets/agent-config-schema.json — Config schema reference

• assets/ci-cd-example.yml — CI/CD pipeline template

Reference Files

• references/api-reference.md — Full API endpoints

• references/tool-examples.md — Client and server tool patterns

• references/system-prompt-guide.md — Prompt engineering for agents

• references/cli-commands.md — CLI reference

• references/workflow-examples.md — End-to-end workflow examples

• references/testing-guide.md — Testing and simulation

• references/cost-optimization.md — Pricing and optimisation

• references/compliance-guide.md — Data residency and compliance