> 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** > > Läs [översikten över ElevenAgents](/docs/sv/eleven-agents/overview) för en förklaring av hur > ElevenAgents fungerar. [ElevenAgents Unity SDK](https://github.com/elevenlabs/unity) ansluter en Unity-scen till en ElevenLabs-agent. Det fångar spelarens mikrofonljud, strömmar tillbaka agentens röst via en `AudioSource` och exponerar sessionen via ett enda `Conversation`-API som fungerar likadant i editorn, fristående desktop-spelare och WebGL-byggen. ## Krav * Unity 6.3 LTS (`6000.3.0f1`) eller senare. SDK:t använder scriptable-audio-API:er som introducerades i Unity 6.3. * **Api Compatibility Level** inställd på **.NET Standard 2.1**, standardvärdet för Unity 2023.1 och senare. * Ett ElevenLabs-konto och en agent. Skapa en i [dashboarden](https://elevenlabs.io/app/agents) eller följ [snabbstarten](/docs/sv/eleven-agents/quickstart). ### Plattformsstöd | Mål | Transport | Status | | -------------------------------------------------------------- | ------------------------------------- | ---------------------------- | | Editor (Play Mode), fristående desktop (macOS, Windows, Linux) | Native WebSocket | Stöds | | WebGL | `@elevenlabs/client` via en JS-brygga | Stöds (WebSocket och WebRTC) | | iOS, Android, XR | Native WebSocket | Otestat | SDK:t väljer automatiskt transport för det aktiva byggmålet. WebRTC är endast tillgängligt på WebGL; på alla andra mål ger `ConnectionType.WebRTC` ett `NotSupportedException`. > **Note** > > SDK:t begär inte mikrofonbehörighet. På iOS och Android måste du själv begära den innan > du startar en session. ## Installation I Unity öppnar du **Window** > **Package Manager**, väljer **+** > **Install package from git URL** och klistrar in repository-URL:en: ```text https://github.com/elevenlabs/unity.git ``` Package Manager installerar paketet som **ElevenAgents** (`io.elevenlabs.agents`) tillsammans med dess beroenden: Input System och Newtonsoft Json. > **Tip** > > Paketet innehåller två exempel. Importera dem från **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** är ett enda MonoBehaviour som visar den aktiva transkriptionen. > **GettingStarted** är en scen där du går fram och pratar, med rumsligt ljud och dynamiska variabler. Se > [genomgången Kom igång](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) för en > steg-för-steg-guide. ## Snabbstart I det här avsnittet lägger du till en röstagent i en tom scen. Agenten börjar prata när du går in i Play Mode och sessionen avslutas när du lämnar det. #### Skapa en offentlig agent Skapa en agent i [ElevenLabs-dashboarden](https://elevenlabs.io/app/agents). I agentens **Security**-inställningar stänger du av **Authentication** så att spelet kan ansluta med endast agent-ID:t. Kopiera agent-ID:t. För agenter som kräver autentisering, se [Offentliga och privata agenter](#public-and-private-agents). #### Installera SDK:t Installera paketet från git-URL:en enligt beskrivningen i [Installation](#installation). #### Lägg till ett konversationsskript Skapa `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` returnerar när anslutningen är öppen och ljudenheterna är klara. `EndSession` är idempotent, så det är säkert att anropa den från `OnDestroy` även om sessionen redan har avslutats. #### Kör scenen Skapa ett tomt GameObject, lägg till komponenten `AgentConversation` och klistra in ditt agent-ID i fältet **Agent Id**. Gå in i Play Mode och tillåt mikrofonåtkomst om operativsystemet frågar efter det. Agenten säger sitt första meddelande och transkriptionen visas i Console. ## Offentliga och privata agenter #### Offentliga agenter Skicka agent-ID:t direkt. Alla som har ID:t kan starta ett samtal med agenten. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Privata agenter Agenter med aktiverad autentisering behöver en kortvarig autentiseringsuppgift som utfärdas av din egen server. Begär en [signerad URL](/docs/sv/eleven-agents/customization/authentication) från din backend och skicka den som `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() } ); ``` För WebRTC-sessioner på WebGL skickar du en konversationstoken som `ConversationToken` och anger `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > Leverera aldrig din ElevenLabs API-nyckel i en spelbyggnad. Generera signerade URL:er och konversationstoken på en server som du kontrollerar. Ange exakt en av `AgentId`, `SignedUrl` eller `ConversationToken`. Ange `UserId` för att koppla samtalet till en spelare i dina egna system. ## Rumsligt ljud Som standard spelar SDK:t agentens röst via en dold `AudioSource` som det skapar. Om du vill placera rösten i scenen skickar du din egen `AudioSource` som `OutputAudioSource`: ```csharp [SerializeField] private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6", OutputAudioSource = voiceSource, } ); ``` SDK:t behåller källans rumsliga mixning, avståndsdämpning, mixer-routning och position. Det återställer källans inställningar för klipp, loop och volym när sessionen avslutas. Om du vill styra en visuell effekt med agentens röst, till exempel en munanimation, läser du `conversation.GetOutputVolume()` varje bildruta. Den returnerar ett värde mellan 0 och 1 på alla plattformar. ## Personalisering Använd [dynamiska variabler](/docs/sv/eleven-agents/customization/personalization/dynamic-variables) för att fylla platshållare i agentens prompt och första meddelande, och [åsidosättningar](/docs/sv/eleven-agents/customization/personalization/overrides) för att ersätta delar av agentkonfigurationen för en 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" }, }, }; ``` Värden för dynamiska variabler måste vara strängar, tal eller booleska värden. Varje åsidosättning måste aktiveras i agentens **Security**-inställningar innan servern godkänner den. ## Klientverktyg [Klientverktyg](/docs/sv/eleven-agents/customization/tools/client-tools) låter agenten utlösa åtgärder i ditt spel. Definiera verktyget i agentens inställningar och registrera sedan en hanterare med samma namn: ```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."; }); ``` SDK:t deserialiserar verktygsparametrarna till `TParams` med Newtonsoft Json, så använd `[JsonProperty]` när ett parameternamn skiljer sig från egenskapsnamnet. Returvärdet serialiseras som verktygsresultatet. Returnera en `Awaitable` för asynkrona hanterare. Kasta `ClientToolException` med en `errorType` för att rapportera ett specifikt fel till agenten; alla andra undantag rapporteras som ett generiskt fel. Anrop till verktyg utan registrerad hanterare utlöser `ErrorOccurred`, eller `UnhandledClientToolCall` om du prenumererar på den. ## Händelser Prenumerera på händelser i `Conversation` som returneras av `StartSessionAsync`. SDK:t utlöser dem i Unitys huvudtråd. | Händelse | Nyttolast | Beskrivning | | ------------------------- | ---------------------- | ---------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | Sessionen avslutades. `Reason` är `User`, `Agent` eller `Error`. | | `ErrorOccurred` | `string` | Ett fel inträffade efter att sessionen startade. | | `StatusChanged` | `Status` | Anslutningsstatusen ändrades. | | `ModeChanged` | `Mode` | Agenten växlade mellan `Speaking` och `Listening`. | | `UserTranscriptReceived` | `UserTranscriptArgs` | En slutförd transkription av spelarens tal. | | `AgentResponded` | `AgentResponseArgs` | Texten i agentens svar. | | `Interrupted` | `InterruptionArgs` | Spelaren avbröt agenten. | | `AgentToolRequested` | `AgentToolRequestArgs` | Agenten startade ett verktygsanrop. `AgentToolResponded` utlöses när det är klart. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | Agenten anropade ett klientverktyg utan registrerad hanterare. | | `CanSendFeedbackChanged` | `bool` | Feedback blev tillgänglig eller otillgänglig för agentens senaste svar. | Händelsen `Connected` utlöses innan `StartSessionAsync` returnerar, så läs `ConversationId` och `Status` direkt när anropet är klart. [Paketets ändringslogg](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) listar alla händelser. ## Metoder | Metod | Beskrivning | | ------------------------------------------------------------- | ----------------------------------------------------------------- | | `EndSession()` | Stäng anslutningen och frigör ljudenheterna. | | `SendUserMessage(string text)` | Skicka ett textmeddelande som om spelaren hade sagt det. | | `SendContextualUpdate(string text)` | Dela spelstatus med agenten utan att avbryta samtalet. | | `SendUserActivity()` | Signalera att spelaren är aktiv så att agenten väntar på sin tur. | | `SendFeedback(bool like)` | Betygsätt agentens senaste svar när `CanSendFeedback` är `true`. | | `SetMicMuted(bool isMuted)` | Stäng av eller slå på mikrofonen. | | `SetVolume(float volume)` | Ställ in agentens uppspelningsvolym mellan 0 och 1. | | `GetInputVolume()`, `GetOutputVolume()` | Läs aktuell ljudnivå för mikrofonen eller agenten mellan 0 och 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Fyll en bytebuffert med frekvensdata för ljudvisualiseringar. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Ladda upp en fil och bifoga den till ett användarmeddelande. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Byt mikrofon eller utdataenhet under en session. | Du kan till exempel skicka spelarens aktuella plats till agenten när spelaren går in i ett nytt område: ```csharp conversation.SendContextualUpdate("The player entered the abandoned lighthouse."); ``` ## WebGL-byggen WebGL-byggen behöver ytterligare en Player Setting. I **Player Settings** > **WebGL** > **Publishing Settings** aktiverar du **Use WebAssembly.Table**. SDK:t misslyckar bygget med instruktioner om den här inställningen är av. Unity har ingen scriptable audio-pipeline på WebGL, så SDK:t spelar agentens röst via webbläsarens Web Audio API och speglar volym-, positions- och rumsinställningarna för din `OutputAudioSource`. Därför returnerar `AudioSource.GetOutputData` och `OnAudioFilterRead` tystnad på WebGL. Använd i stället `GetOutputVolume()` och `GetOutputByteFrequencyData()`. > **Note** > > Play Mode i editorn stöds ännu inte när det aktiva byggmålet är WebGL. Växla till ett > desktop-byggmål för att testa i editorn. Se [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/COMPATIBILITY.md) för hela kompatibilitetsmatrisen för WebGL. ## Felsökning * **`StartSessionAsync` kastar `ArgumentException`.** Ange exakt en av `AgentId`, `SignedUrl` eller `ConversationToken`. * **Sessionen kan inte ansluta med ett giltigt agent-ID.** Agenten kräver autentisering. Stäng av autentisering eller anslut med en signerad URL. * **En åsidosättning har ingen effekt.** Aktivera motsvarande åsidosättning i agentens **Security**-inställningar. * **Spelaren hör ingenting på WebGL.** Webbläsare håller ljud pausat tills spelaren interagerar med sidan. Starta sessionen efter ett klick eller en tangenttryckning. * **Mikrofonen är inte tillgänglig på WebGL.** Webbläsare ger bara mikrofonåtkomst till sidor som levereras över HTTPS eller från `localhost`. Rapportera buggar och begär funktioner på [GitHub](https://github.com/elevenlabs/unity/issues).