> 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. # Unity SDK > **Info** > > Raadpleeg het [overzicht van ElevenAgents](/docs/nl/eleven-agents/overview) voor uitleg over hoe > ElevenAgents werkt. De [ElevenAgents Unity SDK](https://github.com/elevenlabs/unity) verbindt een Unity-scène met een ElevenLabs-agent. De SDK vangt de microfoon van de speler op, streamt de stem van de agent terug via een `AudioSource` en maakt de sessie beschikbaar via één `Conversation`-API die hetzelfde werkt in de Editor, standalone desktopspelers en WebGL-builds. ## Vereisten * Unity 6.3 LTS (`6000.3.0f1`) of hoger. De SDK gebruikt scriptable-audio-API's die zijn geïntroduceerd in Unity 6.3. * **Api Compatibility Level** ingesteld op **.NET Standard 2.1**, de standaardinstelling voor Unity 2023.1 en hoger. * Een ElevenLabs-account en een agent. Maak er een in het [dashboard](https://elevenlabs.io/app/agents) of volg de [quickstart](/docs/nl/eleven-agents/quickstart). ### Platformondersteuning | Doel | Transport | Status | | -------------------------------------------------------------- | -------------------------------------- | --------------------------------- | | Editor (Play Mode), standalone desktop (macOS, Windows, Linux) | Native WebSocket | Ondersteund | | WebGL | `@elevenlabs/client` via een JS-bridge | Ondersteund (WebSocket en WebRTC) | | iOS, Android, XR | Native WebSocket | Niet getest | De SDK selecteert automatisch het transport voor het actieve builddoel. WebRTC is alleen beschikbaar op WebGL; op elk ander doel genereert `ConnectionType.WebRTC` een `NotSupportedException`. > **Note** > > De SDK vraagt geen microfoonmachtiging aan. Vraag deze op iOS en Android zelf aan voordat je een > sessie start. ## Installatie Open in Unity **Window** > **Package Manager**, selecteer **+** > **Install package from git URL** en plak de repository-URL: ```text https://github.com/elevenlabs/unity.git ``` De Package Manager installeert het pakket als **ElevenAgents** (`io.elevenlabs.agents`), samen met de afhankelijkheden Input System en Newtonsoft Json. > **Tip** > > Het pakket bevat twee voorbeelden. Importeer ze via **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** is één MonoBehaviour die het live transcript weergeeft. > **GettingStarted** is een scène waarin je naar een personage loopt en ermee praat, met ruimtelijke audio en dynamische variabelen. Zie de > [stapsgewijze handleiding om te beginnen](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) voor een > stap-voor-stapgids. ## Quickstart In dit gedeelte voeg je een spraakagent toe aan een lege scène. De agent begint te praten wanneer je Play Mode opent en de sessie eindigt wanneer je die verlaat. #### Een openbare agent maken Maak een agent in het [ElevenLabs-dashboard](https://elevenlabs.io/app/agents). Schakel in de **Security**-instellingen van de agent **Authentication** uit, zodat de game alleen met de agent-ID verbinding kan maken. Kopieer de agent-ID. Zie [Openbare en privéagenten](#public-and-private-agents) voor agents die authenticatie vereisen. #### De SDK installeren Installeer het pakket vanaf de git-URL zoals beschreven in [Installatie](#installation). #### Een gespreksscript toevoegen Maak `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` retourneert zodra de verbinding open is en de audioapparaten gereed zijn. `EndSession` is idempotent, dus je kunt deze veilig aanroepen vanuit `OnDestroy`, zelfs als de sessie al is beëindigd. #### De scène uitvoeren Maak een leeg GameObject, voeg het onderdeel `AgentConversation` toe en plak je agent-ID in het veld **Agent Id**. Open Play Mode en geef microfoontoegang als je besturingssysteem daarom vraagt. De agent spreekt het eerste bericht uit en het transcript verschijnt in de Console. ## Openbare en privéagenten #### Openbare agenten Geef de agent-ID rechtstreeks door. Iedereen met de ID kan een gesprek met de agent starten. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Privéagenten Agents waarvoor authenticatie is ingeschakeld, hebben een kortdurende credential nodig die door je eigen server wordt uitgegeven. Vraag een [ondertekende URL](/docs/nl/eleven-agents/customization/authentication) aan bij je backend en geef deze door als `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() } ); ``` Geef voor WebRTC-sessies op WebGL een gesprekstoken door als `ConversationToken` en stel `ConnectionType = ConnectionType.WebRTC` in. > **Warning** > > Lever je ElevenLabs API-sleutel nooit mee in een gamebuild. Genereer ondertekende URL's en gesprekstokens op een server die je beheert. Stel precies een van `AgentId`, `SignedUrl` of `ConversationToken` in. Stel `UserId` in om het gesprek te koppelen aan een speler in je eigen systemen. ## Ruimtelijke audio Standaard speelt de SDK de stem van de agent af via een verborgen `AudioSource` die de SDK maakt. Geef je eigen `AudioSource` door als `OutputAudioSource` om de stem in de scène te plaatsen: ```csharp [SerializeField] private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6", OutputAudioSource = voiceSource, } ); ``` De SDK behoudt de ruimtelijke blend, rolloff, mixerrouting en positie van de bron. De SDK herstelt de instellingen voor clip, loop en volume van de bron wanneer de sessie eindigt. Lees voor het aansturen van een visueel effect met de stem van de agent, zoals een mondanimatie, elk frame `conversation.GetOutputVolume()` uit. Dit retourneert op elk platform een waarde tussen 0 en 1. ## Personalisatie Gebruik [dynamische variabelen](/docs/nl/eleven-agents/customization/personalization/dynamic-variables) om placeholders in de prompt en het eerste bericht van de agent in te vullen, en [overschrijvingen](/docs/nl/eleven-agents/customization/personalization/overrides) om delen van de agentconfiguratie voor één sessie te vervangen: ```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" }, }, }; ``` Waarden van dynamische variabelen moeten strings, getallen of booleans zijn. Elke overschrijving moet zijn ingeschakeld in de **Security**-instellingen van de agent voordat de server deze accepteert. ## Clienttools Met [clienttools](/docs/nl/eleven-agents/customization/tools/client-tools) kan de agent acties in je game activeren. Definieer de tool in de instellingen van de agent en registreer vervolgens een handler met dezelfde naam: ```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."; }); ``` De SDK deserialiseert de toolparameters met Newtonsoft Json naar `TParams`, dus gebruik `[JsonProperty]` wanneer een parameternaam afwijkt van de eigenschapsnaam. De retourwaarde wordt geserialiseerd als het toolresultaat. Retourneer een `Awaitable` voor asynchrone handlers. Genereer `ClientToolException` met een `errorType` om een specifieke fout aan de agent te melden; elke andere uitzondering wordt als een algemene fout gemeld. Aanroepen van tools zonder geregistreerde handler activeren `ErrorOccurred`, of `UnhandledClientToolCall` als je je daarop abonneert. ## Events Abonneer je op events van de `Conversation` die wordt geretourneerd door `StartSessionAsync`. De SDK activeert deze op de hoofdthread van Unity. | Event | Payload | Beschrijving | | ------------------------- | ---------------------- | ---------------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | De sessie is beëindigd. `Reason` is `User`, `Agent` of `Error`. | | `ErrorOccurred` | `string` | Er is een fout opgetreden nadat de sessie was gestart. | | `StatusChanged` | `Status` | De verbindingsstatus is gewijzigd. | | `ModeChanged` | `Mode` | De agent schakelde tussen `Speaking` en `Listening`. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Een voltooid transcript van de spraak van de speler. | | `AgentResponded` | `AgentResponseArgs` | De tekst van het antwoord van de agent. | | `Interrupted` | `InterruptionArgs` | De speler onderbrak de agent. | | `AgentToolRequested` | `AgentToolRequestArgs` | De agent startte een toolaanroep. `AgentToolResponded` wordt geactiveerd bij voltooiing. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | De agent riep een clienttool aan zonder geregistreerde handler. | | `CanSendFeedbackChanged` | `bool` | Feedback werd beschikbaar of niet beschikbaar voor het laatste antwoord van de agent. | Het event `Connected` wordt geactiveerd voordat `StartSessionAsync` retourneert, dus lees `ConversationId` en `Status` rechtstreeks uit zodra de aanroep is voltooid. De [changelog van het pakket](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) bevat de volledige lijst met events. ## Methoden | Methode | Beschrijving | | ------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `EndSession()` | Sluit de verbinding en geeft de audioapparaten vrij. | | `SendUserMessage(string text)` | Stuur een tekstbericht alsof de speler het had uitgesproken. | | `SendContextualUpdate(string text)` | Deel de gamestatus met de agent zonder het gesprek te onderbreken. | | `SendUserActivity()` | Geef aan dat de speler actief is, zodat de agent zijn beurt vasthoudt. | | `SendFeedback(bool like)` | Beoordeel het laatste antwoord van de agent wanneer `CanSendFeedback` `true` is. | | `SetMicMuted(bool isMuted)` | Dempen of dempen opheffen voor de microfoon. | | `SetVolume(float volume)` | Stel het afspeelvolume van de agent in tussen 0 en 1. | | `GetInputVolume()`, `GetOutputVolume()` | Lees het huidige audiolevel van de microfoon of agent uit tussen 0 en 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Vul een bytebuffer met frequentiedata voor audiovisualisaties. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Upload een bestand en voeg het toe aan een gebruikersbericht. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Wissel tijdens een sessie van microfoon of uitvoerapparaat. | Stuur bijvoorbeeld de huidige locatie van de speler naar de agent wanneer deze een nieuw gebied betreedt: ```csharp conversation.SendContextualUpdate("The player entered the abandoned lighthouse."); ``` ## WebGL-builds WebGL-builds hebben één extra Player Setting nodig. Schakel in **Player Settings** > **WebGL** > **Publishing Settings** **Use WebAssembly.Table** in. De SDK laat de build mislukken met instructies als deze instelling is uitgeschakeld. Unity heeft geen scriptable-audiopipeline op WebGL, dus de SDK speelt de stem van de agent af via de Web Audio API van de browser en spiegelt het volume, de positie en de ruimtelijke instellingen van je `OutputAudioSource`. Daardoor retourneren `AudioSource.GetOutputData` en `OnAudioFilterRead` stilte op WebGL. Gebruik in plaats daarvan `GetOutputVolume()` en `GetOutputByteFrequencyData()`. > **Note** > > Play Mode in de Editor wordt nog niet ondersteund wanneer het actieve builddoel WebGL is. Schakel over naar een > desktopbuilddoel om in de Editor te testen. Zie [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/COMPATIBILITY.md) voor de volledige WebGL-compatibiliteitsmatrix. ## Problemen oplossen * **`StartSessionAsync` genereert `ArgumentException`.** Stel precies een van `AgentId`, `SignedUrl` of `ConversationToken` in. * **De sessie kan geen verbinding maken met een geldige agent-ID.** De agent vereist authenticatie. Schakel authenticatie uit of verbind met een ondertekende URL. * **Een overschrijving heeft geen effect.** Schakel de overeenkomende overschrijving in de **Security**-instellingen van de agent in. * **De speler hoort niets op WebGL.** Browsers houden audio onderbroken totdat de speler interactie heeft met de pagina. Start de sessie na een klik of toetsaanslag. * **De microfoon is niet beschikbaar op WebGL.** Browsers verlenen alleen microfoontoegang aan pagina's die via HTTPS of vanaf `localhost` worden aangeboden. Meld bugs en vraag functies aan op [GitHub](https://github.com/elevenlabs/unity/issues).