> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # SDK Unity > **Info** > > Consultez la [présentation d’ElevenAgents](/docs/fr/eleven-agents/overview) pour comprendre le fonctionnement > d’ElevenAgents. Le [SDK Unity ElevenAgents](https://github.com/elevenlabs/unity) 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](https://elevenlabs.io/app/agents) ou suivez le [guide de démarrage rapide](/docs/fr/eleven-agents/quickstart). ### Prise en charge des plateformes | Cible | Transport | Statut | | ------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------ | | Éditeur (mode Play), application autonome desktop (macOS, Windows, Linux) | WebSocket natif | Pris en charge | | WebGL | `@elevenlabs/client` via un pont JS | Pris en charge (WebSocket et WebRTC) | | iOS, Android, XR | WebSocket natif | Non testé | 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`. > **Note** > > Le SDK ne demande pas l’autorisation d’accéder au microphone. Sur iOS et Android, demandez-la vous-même avant > de démarrer une session. ## Installation Dans Unity, ouvrez **Window** > **Package Manager**, sélectionnez **+** > **Install package from git URL**, puis collez l’URL du dépôt : ```text 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. > **Tip** > > Le package contient deux exemples. Importez-les depuis **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** est un unique MonoBehaviour qui affiche la transcription en direct. > **GettingStarted** est une scène d’approche et de conversation avec audio spatial et variables dynamiques. Consultez le > [guide de démarrage pas à pas](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) pour obtenir des > instructions détaillées. ## 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. #### Créer un agent public Concevez un agent dans le [Dashboard ElevenLabs](https://elevenlabs.io/app/agents). Dans les paramètres **Security** de l’agent, désactivez **Authentication** afin que le jeu puisse se connecter avec le seul ID de l’agent. Copiez l’ID de l’agent. Pour les agents nécessitant une authentification, consultez [Agents publics et privés](#public-and-private-agents). #### Installer le SDK Installez le package depuis l’URL git, comme décrit dans [Installation](#installation). #### Ajouter un script de conversation Créez `Assets/Scripts/AgentConversation.cs` : **`AgentConversation.cs`** ```csharp title="AgentConversation.cs" 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(); } } ``` `Conversation.StartSessionAsync` renvoie un résultat une fois la connexion ouverte et les périphériques audio prêts. `EndSession` est idempotente ; vous pouvez donc l’appeler depuis `OnDestroy` sans risque, même si la session est déjà terminée. #### Exécuter la scène Créez un GameObject vide, ajoutez le composant `AgentConversation` et collez l’ID de votre agent dans le champ **Agent Id**. Passez en mode Play et autorisez l’accès au microphone si votre système d’exploitation vous le demande. L’agent prononce son premier message et la transcription s’affiche dans la Console. ## Agents publics et privés #### Agents publics Transmettez directement l’ID de l’agent. Toute personne disposant de cet ID peut démarrer une conversation avec l’agent. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Agents privés Les agents dont l’authentification est activée nécessitent un identifiant à courte durée de vie émis par votre propre serveur. Demandez une [URL signée](/docs/fr/eleven-agents/customization/authentication) à votre backend et transmettez-la comme `SignedUrl` : ```csharp using UnityEngine.Networking; private static async Awaitable FetchSignedUrlAsync() { using var request = UnityWebRequest.Get("https://api.example-game.com/agent/signed-url"); await request.SendWebRequest(); if (request.result != UnityWebRequest.Result.Success) throw new InvalidOperationException(request.error); return request.downloadHandler.text; } var conversation = await Conversation.StartSessionAsync( new ConversationOptions { SignedUrl = await FetchSignedUrlAsync() } ); ``` Pour les sessions WebRTC sur WebGL, transmettez un jeton de conversation comme `ConversationToken` et définissez `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > N’intégrez jamais votre clé API ElevenLabs dans une build de jeu. Générez les URL signées et les jetons de conversation sur un serveur que vous contrôlez. 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` : ```csharp [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](/docs/fr/eleven-agents/customization/personalization/dynamic-variables) pour renseigner les espaces réservés dans le prompt et le premier message de l’agent, ainsi que les [remplacements](/docs/fr/eleven-agents/customization/personalization/overrides) pour remplacer des parties de la configuration de l’agent pour une session : ```csharp using System.Collections.Generic; using ElevenLabs.Protocol; var options = new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6", DynamicVariables = new Dictionary { ["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](/docs/fr/eleven-agents/customization/tools/client-tools) 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 : ```csharp using Newtonsoft.Json; public sealed class OpenDoorParams { [JsonProperty("door_id")] public string DoorId { get; set; } } conversation.RegisterTool("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` 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. | Événement | Charge utile | Description | | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------ | | `Disconnected` | `DisconnectionDetails` | La session est terminée. `Reason` vaut `User`, `Agent` ou `Error`. | | `ErrorOccurred` | `string` | Une erreur s’est produite après le démarrage de la session. | | `StatusChanged` | `Status` | L’état de la connexion a changé. | | `ModeChanged` | `Mode` | L’agent est passé de `Speaking` à `Listening`, ou inversement. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Une transcription finalisée de la parole du joueur. | | `AgentResponded` | `AgentResponseArgs` | Le texte de la réponse de l’agent. | | `Interrupted` | `InterruptionArgs` | Le joueur a interrompu l’agent. | | `AgentToolRequested` | `AgentToolRequestArgs` | L’agent a lancé un appel d’outil. `AgentToolResponded` se déclenche à la fin. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | L’agent a appelé un outil client sans gestionnaire enregistré. | | `CanSendFeedbackChanged` | `bool` | Les retours sont devenus disponibles ou indisponibles pour la dernière réponse de l’agent. | 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](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) répertorie l’ensemble des événements. ## Méthodes | Méthode | Description | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `EndSession()` | Ferme la connexion et libère les périphériques audio. | | `SendUserMessage(string text)` | Envoie un message texte comme si le joueur l’avait prononcé. | | `SendContextualUpdate(string text)` | Partage l’état du jeu avec l’agent sans interrompre la conversation. | | `SendUserActivity()` | Signale que le joueur est actif afin que l’agent conserve son tour de parole. | | `SendFeedback(bool like)` | Évalue la dernière réponse de l’agent lorsque `CanSendFeedback` vaut `true`. | | `SetMicMuted(bool isMuted)` | Coupe ou réactive le microphone. | | `SetVolume(float volume)` | Définit le volume de lecture de l’agent entre 0 et 1. | | `GetInputVolume()`, `GetOutputVolume()` | Lit le niveau audio actuel du microphone ou de l’agent, entre 0 et 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Remplit une mémoire tampon d’octets avec des données de fréquence pour les visualiseurs audio. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Téléverse un fichier et l’attache à un message utilisateur. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Change le microphone ou le périphérique de sortie pendant une session. | Par exemple, envoyez à l’agent la position actuelle du joueur lorsqu’il entre dans une nouvelle zone : ```csharp 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()`. > **Note** > > Le mode Play dans l’éditeur n’est pas encore pris en charge lorsque la cible de build active est WebGL. Passez à une > cible de build desktop pour effectuer vos tests dans l’éditeur. Consultez [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/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](https://github.com/elevenlabs/unity/issues).