Plateforme d'Agents ElevenLabs

Construisez des agents vocaux IA avec des conversations naturelles, plusieurs fournisseurs LLM, des outils personnalisés et un intégration web facile.

Configuration : Voir le Guide d'installation pour la configuration du CLI et du SDK.

Démarrage rapide avec le CLI

Le CLI ElevenLabs est le moyen recommandé de créer et gérer des agents :

# Installer le CLI et s'authentifier
npm install -g @elevenlabs/cli
elevenlabs auth login

# Initialiser le projet et créer un agent
elevenlabs agents init
elevenlabs agents add "My Assistant" --template complete

# Envoyer vers la plateforme ElevenLabs
elevenlabs agents push

Templates disponibles : complete, minimal, voice-only, text-only, customer-service, assistant

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

agent = client.conversational_ai.agents.create(
    name="My Assistant",
    enable_versioning=True,
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I help?",
            "language": "en",
            "prompt": {
                "prompt": "You are a helpful assistant. Be concise and friendly.",
                "llm": "gemini-2.0-flash",
                "temperature": 0.7
            }
        },
        "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}
    }
)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient();

const agent = await client.conversationalAi.agents.create({
  name: "My Assistant",
  enableVersioning: true,
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      language: "en",
      prompt: {
        prompt: "You are a helpful assistant.",
        llm: "gemini-2.0-flash",
        temperature: 0.7
      }
    },
    tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" }
  }
});

cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/agents/create?enable_versioning=true" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "My Assistant", "conversation_config": {"agent": {"first_message": "Hello!", "language": "en", "prompt": {"prompt": "You are helpful.", "llm": "gemini-2.0-flash"}}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}}'

Démarrage des conversations

Côté serveur (Python) : Obtenir une URL signée pour la connexion client :

signed_url = client.conversational_ai.conversations.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)

Côté client (JavaScript) :

import { Conversation } from "@elevenlabs/client";

const conversation = await Conversation.startSession({
  agentId: "your-agent-id",
  environment: "staging",
  onMessage: (msg) => console.log("Agent:", msg.message),
  onUserTranscript: (t) => console.log("User:", t.message),
  onError: (e) => console.error(e)
});

Hook React : Enveloppez les consommateurs de hook dans ConversationProvider. Préférez les hooks granulaires tels que useConversationControls et useConversationStatus pour les contrôles de session et l'état de l'interface ; useConversation reste disponible en tant que hook de commodité tout-en-un. Passez les callbacks au niveau du fournisseur tels que onError si vous souhaitez que React gère les erreurs de conversation en un seul endroit.

import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from "@elevenlabs/react";

function Agent({ signedUrl }: { signedUrl: string }) {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();

  if (status === "connected") {
    return <button onClick={endSession}>End conversation</button>;
  }

  return (
    <button onClick={() => startSession({ signedUrl })}>
      Start conversation
    </button>
  );
}

function App({ signedUrl }: { signedUrl: string }) {
  return (
    <ConversationProvider
      onError={(error) => console.error("Conversation error:", error)}
    >
      <Agent signedUrl={signedUrl} />
    </ConversationProvider>
  );
}

Configuration

Utilisez GET /v1/convai/llm/list pour inspecter le catalogue de modèles actuel, y compris l'état de dépréciation, les limites de tokens/contexte, les drapeaux de capacités tels que le support d'entrée d'images et le support d'effort de raisonnement spécifique au modèle.

Voix populaires : JBFqnCBsd6RMkjVDRZzb (George), EXAVITQu4vr4xnSDxMaL (Sarah), onwK4e9ZLuTAKqWW03F9 (Daniel), XB0fDUnXU5powFXDhCwa (Charlotte)

Impatience de réponse : patient (attend plus longtemps que l'utilisateur finisse), normal, ou eager (répond rapidement)

Voir Configuration d'agent pour toutes les options.

Outils

Étendez les agents avec des outils webhook, client ou système intégrés. Les outils sont définis dans conversation_config.agent.prompt :

Les variables d'environnement de l'espace de travail peuvent résoudre par environnement les URLs d'outils serveur, les en-têtes et les connexions d'authentification, et les variables système au moment de l'exécution telles que {{system__conversation_history}} peuvent passer le contexte de conversation complet dans les appels d'outils si nécessaire.

"prompt": {
    "prompt": "You are a helpful assistant that can check the weather.",
    "llm": "gemini-2.0-flash",
    "tools": [
        # Webhook: server-side API call
        {"type": "webhook", "name": "get_weather", "description": "Get weather",
         "api_schema": {"url": "https://api.example.com/weather", "method": "POST",
             "request_body_schema": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}},
        # Client: runs in the browser
        {"type": "client", "name": "show_product", "description": "Display a product",
         "parameters": {"type": "object", "properties": {"productId": {"type": "string"}}, "required": ["productId"]}}
    ],
    "built_in_tools": {
        "end_call": {},
        "transfer_to_number": {"transfers": [{"transfer_destination": {"type": "phone", "phone_number": "+1234567890"}, "condition": "User asks for human support"}]}
    }
}

Outils client exécutés dans le navigateur :

clientTools: {
  show_product: async ({ productId }) => {
    document.getElementById("product").src = `/products/${productId}`;
    return { success: true };
  }
}

Voir Référence des outils client pour la documentation complète.

Intégration de widget

<elevenlabs-convai agent-id="your-agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

Personnalisez avec les attributs : avatar-image-url, action-text, start-call-text, end-call-text.

Voir Référence d'intégration de widget pour toutes les options.

Appels sortants

Effectuez des appels téléphoniques sortants en utilisant votre agent via l'intégration Twilio :

Python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890",
    call_recording_enabled=True
)
print(f"Call initiated: {response.conversation_id}")

JavaScript

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "+1234567890",
  callRecordingEnabled: true,
});

cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id", "agent_phone_number_id": "your-phone-number-id", "to_number": "+1234567890", "call_recording_enabled": true}'

Voir Référence des appels sortants pour les remplacements de configuration et les variables dynamiques.

Gestion des agents

Utilisation du CLI (recommandé)

# Lister les agents et vérifier le statut
elevenlabs agents list
elevenlabs agents status

# Importer les agents de la plateforme vers la configuration locale
elevenlabs agents pull                      # Importer tous les agents
elevenlabs agents pull --agent <agent-id>   # Importer un agent spécifique

# Envoyer les modifications locales vers la plateforme
elevenlabs agents push              # Télécharger les configurations
elevenlabs agents push --dry-run    # Prévisualiser les modifications d'abord

# Ajouter des outils
elevenlabs tools add-webhook "Weather API"
elevenlabs tools add-client "UI Tool"

Structure du projet

Le CLI crée une structure de projet pour gérer les agents :

your_project/
├── agents.json       # Agent definitions
├── tools.json        # Tool configurations
├── tests.json        # Test configurations
├── agent_configs/    # Individual agent configs
├── tool_configs/     # Individual tool configs
└── test_configs/     # Individual test configs

Exemples SDK

# List
agents = client.conversational_ai.agents.list()

# Get
agent = client.conversational_ai.agents.get(agent_id="your-agent-id")

# Update (partial - only include fields to change)
client.conversational_ai.agents.update(agent_id="your-agent-id", name="New Name")
client.conversational_ai.agents.update(agent_id="your-agent-id",
    conversation_config={
        "agent": {"prompt": {"prompt": "New instructions", "llm": "claude-sonnet-4"}}
    })

# Delete
client.conversational_ai.agents.delete(agent_id="your-agent-id")

Voir Configuration d'agent pour toutes les options de configuration et les exemples SDK.

Gestion des erreurs

try:
    agent = client.conversational_ai.agents.create(...)
except Exception as e:
    print(f"API error: {e}")

Erreurs courantes : 401 (clé invalide), 404 (non trouvé), 422 (configuration invalide), 429 (limite de débit dépassée)

Références

• Guide d'installation - Configuration du SDK et migration
• Configuration d'agent - Toutes les options de configuration et exemples CRUD
• Outils client - Outils webhook, client et système
• Intégration de widget - Intégration de site web
• Appels sortants - Intégration d'appels téléphoniques Twilio