SDK Unity

Le SDK Unity ElevenAgents connecte une scène Unity à un agent ElevenLabs. Il capture le microphone du joueur, diffuse en continu la voix de l’agent via un AudioSource et expose la session par l’intermédiaire d’une API Conversation unique, dont le comportement est identique dans l’éditeur, les lecteurs autonomes desktop et les versions WebGL.

Prérequis

• Unity 6.3 LTS (6000.3.0f1) ou version ultérieure. Le SDK utilise les API audio scriptables introduites dans Unity 6.3.
• Niveau de compatibilité des API défini sur .NET Standard 2.1, valeur par défaut pour Unity 2023.1 et versions ultérieures.
• Un compte ElevenLabs et un agent. Concevez-en un dans le Dashboard ou suivez le guide de démarrage rapide.

Prise en charge des plateformes

Le SDK sélectionne automatiquement le transport correspondant à la cible de build active. WebRTC est disponible uniquement sur WebGL ; pour toutes les autres cibles, ConnectionType.WebRTC génère une NotSupportedException.

Installation

Dans Unity, ouvrez Window > Package Manager, sélectionnez + > Install package from git URL, puis collez l’URL du dépôt :

https://github.com/elevenlabs/unity.git

Le Package Manager installe le package ElevenAgents (io.elevenlabs.agents) avec ses dépendances : Input System et Newtonsoft Json.

Démarrage rapide

Cette section ajoute un agent vocal à une scène vide. L’agent commence à parler lorsque vous passez en mode Play et la session se termine lorsque vous le quittez.

using System;
using ElevenLabs.Agents;
using ElevenLabs.Protocol;
using UnityEngine;
public sealed class AgentConversation : MonoBehaviour
{
    [SerializeField]
    private string agentId = "agent_7101k5zvyjhmfg983brhmhkd98n6";
    private Conversation conversation;
    private async void Start()
    {
        try
        {
            conversation = await Conversation.StartSessionAsync(
                new ConversationOptions { AgentId = agentId }
            );
        }
        catch (Exception ex)
        {
            Debug.LogError($"Failed to start session: {ex.Message}");
            return;
        }
        Debug.Log($"Connected: {conversation.ConversationId}");
        conversation.UserTranscriptReceived += OnUserTranscript;
        conversation.AgentResponded += OnAgentResponse;
        conversation.ErrorOccurred += message => Debug.LogError(message);
        conversation.Disconnected += details => Debug.Log($"Disconnected: {details.Reason}");
    }
    private void OnUserTranscript(UserTranscriptArgs args) =>
        Debug.Log($"User: {args.UserTranscript}");
    private void OnAgentResponse(AgentResponseArgs args) =>
        Debug.Log($"Agent: {args.AgentResponse}");
    private void OnDestroy()
    {
        _ = conversation?.EndSession();
    }
}

Agents publics et privés

var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" }
);

Définissez exactement l’un des paramètres AgentId, SignedUrl ou ConversationToken. Définissez UserId pour associer la conversation à un joueur dans vos propres systèmes.

Audio spatial

Par défaut, le SDK lit la voix de l’agent via un AudioSource masqué qu’il crée. Pour placer la voix dans la scène, transmettez votre propre AudioSource comme OutputAudioSource :

[SerializeField]
private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio
var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions
    {
        AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6",
        OutputAudioSource = voiceSource,
    }
);

Le SDK conserve le mélange spatial, l’atténuation, le routage du mixeur et la position de la source. Il restaure les paramètres de clip, de boucle et de volume de la source à la fin de la session.

Pour piloter un effet visuel à partir de la voix de l’agent, comme une animation de bouche, lisez conversation.GetOutputVolume() à chaque image. Cette méthode renvoie une valeur comprise entre 0 et 1 sur toutes les plateformes.

Personnalisation

Utilisez les variables dynamiques pour renseigner les espaces réservés dans le prompt et le premier message de l’agent, ainsi que les remplacements pour remplacer des parties de la configuration de l’agent pour une session :

using System.Collections.Generic;
using ElevenLabs.Protocol;
var options = new ConversationOptions
{
    AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6",
    DynamicVariables = new Dictionary<string, object>
    {
        ["player_name"] = "Ada",
        ["quest_stage"] = 3,
    },
    Overrides = new ConversationConfigOverride
    {
        Agent = new ConversationConfigOverrideAgent
        {
            FirstMessage = "Welcome back, {{player_name}}.",
        },
        Tts = new ConversationConfigOverrideTts { VoiceId = "JBFqnCBsd6RMkjVDRZzb" },
    },
};

Les valeurs des variables dynamiques doivent être des chaînes, des nombres ou des booléens. Chaque remplacement doit être activé dans les paramètres Security de l’agent avant que le serveur l’accepte.

Outils client

Les outils client permettent à l’agent de déclencher des actions dans votre jeu. Définissez l’outil dans les paramètres de l’agent, puis enregistrez un gestionnaire portant le même nom :

using Newtonsoft.Json;
public sealed class OpenDoorParams
{
    [JsonProperty("door_id")]
    public string DoorId { get; set; }
}
conversation.RegisterTool<OpenDoorParams, string>("open_door", parameters =>
{
    DoorRegistry.Open(parameters.DoorId);
    return $"Door {parameters.DoorId} is open.";
});

Le SDK désérialise les paramètres de l’outil dans TParams avec Newtonsoft Json. Utilisez donc [JsonProperty] lorsqu’un nom de paramètre diffère du nom de propriété. La valeur renvoyée est sérialisée comme résultat de l’outil. Renvoyez un Awaitable<TResult> pour les gestionnaires asynchrones. Générez une ClientToolException avec un errorType pour signaler un échec précis à l’agent ; toute autre exception est signalée comme une erreur générique.

Les appels à des outils sans gestionnaire enregistré déclenchent ErrorOccurred, ou UnhandledClientToolCall si vous vous y abonnez.

Événements

Abonnez-vous aux événements de la Conversation renvoyée par StartSessionAsync. Le SDK les déclenche sur le thread principal d’Unity.

L’événement Connected se déclenche avant que StartSessionAsync ne renvoie un résultat. Lisez donc directement ConversationId et Status une fois l’appel terminé. Le journal des modifications du package répertorie l’ensemble des événements.

Méthodes

Par exemple, envoyez à l’agent la position actuelle du joueur lorsqu’il entre dans une nouvelle zone :

conversation.SendContextualUpdate("The player entered the abandoned lighthouse.");

Builds WebGL

Les builds WebGL nécessitent un paramètre Player supplémentaire. Dans Player Settings > WebGL > Publishing Settings, activez Use WebAssembly.Table. Si ce paramètre est désactivé, le SDK fait échouer la build avec des instructions.

Unity ne dispose pas de pipeline audio scriptable sur WebGL. Le SDK lit donc la voix de l’agent via l’API Web Audio du navigateur et reflète les paramètres de volume, de position et de spatialisation de votre OutputAudioSource. Par conséquent, AudioSource.GetOutputData et OnAudioFilterRead renvoient du silence sur WebGL. Utilisez plutôt GetOutputVolume() et GetOutputByteFrequencyData().

Consultez COMPATIBILITY.md pour la matrice complète de compatibilité WebGL.

Résolution des problèmes

• StartSessionAsync génère une ArgumentException. Définissez exactement l’un des paramètres AgentId, SignedUrl ou ConversationToken.
• La session ne parvient pas à se connecter avec un ID d’agent valide. L’agent nécessite une authentification. Désactivez l’authentification ou connectez-vous avec une URL signée.
• Un remplacement n’a aucun effet. Activez le remplacement correspondant dans les paramètres Security de l’agent.
• Le joueur n’entend rien sur WebGL. Les navigateurs suspendent l’audio jusqu’à ce que le joueur interagisse avec la page. Démarrez la session après un clic ou une pression sur une touche.
• Le microphone n’est pas disponible sur WebGL. Les navigateurs n’accordent l’accès au microphone qu’aux pages servies en HTTPS ou depuis localhost.

Signalez les bugs et demandez des fonctionnalités sur GitHub.