> 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** > > Eine Erklärung zur Funktionsweise von ElevenAgents finden Sie in der [ElevenAgents-Übersicht](/docs/de/eleven-agents/overview). Das [ElevenAgents Unity SDK](https://github.com/elevenlabs/unity) verbindet eine Unity-Szene mit einem ElevenLabs-Agenten. Es erfasst das Mikrofon des Spielers, streamt die Stimme des Agenten über eine `AudioSource` zurück und stellt die Sitzung über eine einzige `Conversation`-API bereit, die sich im Editor, in eigenständigen Desktop-Playern und in WebGL-Builds gleich verhält. ## Anforderungen * Unity 6.3 LTS (`6000.3.0f1`) oder höher. Das SDK verwendet Scriptable-Audio-APIs, die mit Unity 6.3 eingeführt wurden. * **Api Compatibility Level** auf **.NET Standard 2.1**, der Standard für Unity 2023.1 und höher. * Ein ElevenLabs-Konto und ein Agent. Erstellen Sie einen im [Dashboard](https://elevenlabs.io/app/agents) oder folgen Sie dem [Schnellstart](/docs/de/eleven-agents/quickstart). ### Plattformunterstützung | Ziel | Transport | Status | | ------------------------------------------------------------------ | ---------------------------------------- | ---------------------------------- | | Editor (Play Mode), eigenständiger Desktop (macOS, Windows, Linux) | Natives WebSocket | Unterstützt | | WebGL | `@elevenlabs/client` über eine JS-Bridge | Unterstützt (WebSocket und WebRTC) | | iOS, Android, XR | Natives WebSocket | Ungetestet | Das SDK wählt den Transport für das aktive Build-Ziel automatisch aus. WebRTC ist nur in WebGL verfügbar; bei allen anderen Zielen löst `ConnectionType.WebRTC` eine `NotSupportedException` aus. > **Note** > > Das SDK fordert keine Mikrofonberechtigung an. Fordern Sie sie auf iOS und Android selbst an, bevor > Sie eine Sitzung starten. ## Installation Öffnen Sie in Unity **Window** > **Package Manager**, wählen Sie **+** > **Install package from git URL** und fügen Sie die Repository-URL ein: ```text https://github.com/elevenlabs/unity.git ``` Der Package Manager installiert das Paket als **ElevenAgents** (`io.elevenlabs.agents`) zusammen mit seinen Abhängigkeiten: Input System und Newtonsoft Json. > **Tip** > > Das Paket enthält zwei Beispiele. Importieren Sie sie über **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** ist ein einzelnes MonoBehaviour, das das Live-Transkript rendert. > **GettingStarted** ist eine Szene zum Herangehen und Sprechen mit räumlichem Audio und dynamischen Variablen. Eine > Schritt-für-Schritt-Anleitung finden Sie im [Getting-started- Walkthrough](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md). ## Schnellstart Dieser Abschnitt fügt einer leeren Szene einen Sprachagenten hinzu. Der Agent beginnt zu sprechen, wenn Sie den Play Mode starten, und die Sitzung endet, wenn Sie ihn verlassen. #### Öffentlichen Agenten erstellen Erstellen Sie einen Agenten im [ElevenLabs-Dashboard](https://elevenlabs.io/app/agents). Deaktivieren Sie in den **Security**-Einstellungen des Agenten **Authentication**, damit sich das Spiel allein mit der Agenten-ID verbinden kann. Kopieren Sie die Agenten-ID. Informationen zu Agenten, die Authentifizierung erfordern, finden Sie unter [Öffentliche und private Agenten](#public-and-private-agents). #### SDK installieren Installieren Sie das Paket von der Git-URL wie unter [Installation](#installation) beschrieben. #### Gesprächsskript hinzufügen Erstellen Sie `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` gibt zurück, sobald die Verbindung geöffnet und die Audiogeräte bereit sind. `EndSession` ist idempotent. Daher können Sie die Methode sicher über `OnDestroy` aufrufen, auch wenn die Sitzung bereits beendet ist. #### Szene ausführen Erstellen Sie ein leeres GameObject, fügen Sie die Komponente `AgentConversation` hinzu und fügen Sie Ihre Agenten-ID in das Feld **Agent Id** ein. Starten Sie den Play Mode und erlauben Sie den Mikrofonzugriff, wenn Ihr Betriebssystem dazu auffordert. Der Agent spricht seine erste Nachricht und das Transkript erscheint in der Console. ## Öffentliche und private Agenten #### Öffentliche Agenten Übergeben Sie die Agenten-ID direkt. Jeder, der die ID hat, kann ein Gespräch mit dem Agenten starten. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Private Agenten Agenten mit aktivierter Authentifizierung benötigen Anmeldedaten mit kurzer Gültigkeit, die von Ihrem eigenen Server ausgestellt werden. Fordern Sie von Ihrem Backend eine [signierte URL](/docs/de/eleven-agents/customization/authentication) an und übergeben Sie sie 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() } ); ``` Übergeben Sie für WebRTC-Sitzungen in WebGL ein Gesprächs-Token als `ConversationToken` und setzen Sie `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > Veröffentlichen Sie Ihren ElevenLabs-API-Schlüssel niemals in einem Spiel-Build. Generieren Sie signierte URLs und Gesprächs-Tokens auf einem Server, den Sie kontrollieren. Setzen Sie genau eine der Optionen `AgentId`, `SignedUrl` oder `ConversationToken`. Setzen Sie `UserId`, um das Gespräch einem Spieler in Ihren eigenen Systemen zuzuordnen. ## Räumliches Audio Standardmäßig spielt das SDK die Stimme des Agenten über eine ausgeblendete `AudioSource` ab, die es erstellt. Um die Stimme in der Szene zu platzieren, übergeben Sie Ihre eigene `AudioSource` als `OutputAudioSource`: ```csharp [SerializeField] private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6", OutputAudioSource = voiceSource, } ); ``` Das SDK behält Spatial Blend, Rolloff, Mixer-Routing und Position der Quelle bei. Es stellt Clip-, Loop- und Lautstärkeeinstellungen der Quelle wieder her, wenn die Sitzung endet. Um einen visuellen Effekt mit der Stimme des Agenten zu steuern, etwa eine Mundanimation, lesen Sie in jedem Frame `conversation.GetOutputVolume()` aus. Die Methode gibt auf jeder Plattform einen Wert zwischen 0 und 1 zurück. ## Personalisierung Verwenden Sie [dynamische Variablen](/docs/de/eleven-agents/customization/personalization/dynamic-variables), um Platzhalter im Prompt und in der ersten Nachricht des Agenten zu füllen, und [Überschreibungen](/docs/de/eleven-agents/customization/personalization/overrides), um Teile der Agentenkonfiguration für eine Sitzung zu ersetzen: ```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" }, }, }; ``` Werte dynamischer Variablen müssen Strings, Zahlen oder boolesche Werte sein. Jede Überschreibung muss in den **Security**-Einstellungen des Agenten aktiviert werden, bevor der Server sie akzeptiert. ## Client-Tools [Client-Tools](/docs/de/eleven-agents/customization/tools/client-tools) ermöglichen es dem Agenten, Aktionen in Ihrem Spiel auszulösen. Definieren Sie das Tool in den Einstellungen des Agenten und registrieren Sie dann einen Handler mit demselben Namen: ```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."; }); ``` Das SDK deserialisiert die Tool-Parameter mit Newtonsoft Json in `TParams`. Verwenden Sie daher `[JsonProperty]`, wenn ein Parametername vom Eigenschaftsnamen abweicht. Der Rückgabewert wird als Tool-Ergebnis serialisiert. Geben Sie für asynchrone Handler ein `Awaitable` zurück. Lösen Sie `ClientToolException` mit einem `errorType` aus, um dem Agenten einen bestimmten Fehler zu melden; jeder andere Fehler wird als allgemeiner Fehler gemeldet. Aufrufe von Tools ohne registrierten Handler lösen `ErrorOccurred` aus oder `UnhandledClientToolCall`, wenn Sie es abonniert haben. ## Ereignisse Abonnieren Sie Ereignisse der von `StartSessionAsync` zurückgegebenen `Conversation`. Das SDK löst sie im Unity-Hauptthread aus. | Ereignis | Nutzlast | Beschreibung | | ------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | Die Sitzung wurde beendet. `Reason` ist `User`, `Agent` oder `Error`. | | `ErrorOccurred` | `string` | Nach dem Start der Sitzung ist ein Fehler aufgetreten. | | `StatusChanged` | `Status` | Der Verbindungsstatus hat sich geändert. | | `ModeChanged` | `Mode` | Der Agent wechselte zwischen `Speaking` und `Listening`. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Ein abgeschlossenes Transkript der Sprache des Spielers. | | `AgentResponded` | `AgentResponseArgs` | Der Text der Antwort des Agenten. | | `Interrupted` | `InterruptionArgs` | Der Spieler hat den Agenten unterbrochen. | | `AgentToolRequested` | `AgentToolRequestArgs` | Der Agent hat einen Tool-Aufruf gestartet. `AgentToolResponded` wird bei Abschluss ausgelöst. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | Der Agent hat ein Client-Tool ohne registrierten Handler aufgerufen. | | `CanSendFeedbackChanged` | `bool` | Feedback wurde für die letzte Agentenantwort verfügbar oder nicht verfügbar. | Das Ereignis `Connected` wird ausgelöst, bevor `StartSessionAsync` zurückgibt. Lesen Sie daher nach Abschluss des Aufrufs `ConversationId` und `Status` direkt aus. Das [Paket-Changelog](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) listet alle Ereignisse auf. ## Methoden | Methode | Beschreibung | | ------------------------------------------------------------- | ----------------------------------------------------------------------- | | `EndSession()` | Verbindung schließen und Audiogeräte freigeben. | | `SendUserMessage(string text)` | Eine Textnachricht senden, als hätte der Spieler sie gesprochen. | | `SendContextualUpdate(string text)` | Spielstatus mit dem Agenten teilen, ohne das Gespräch zu unterbrechen. | | `SendUserActivity()` | Signalisieren, dass der Spieler aktiv ist, damit der Agent wartet. | | `SendFeedback(bool like)` | Die neueste Agentenantwort bewerten, wenn `CanSendFeedback` `true` ist. | | `SetMicMuted(bool isMuted)` | Mikrofon stummschalten oder Stummschaltung aufheben. | | `SetVolume(float volume)` | Wiedergabelautstärke des Agenten zwischen 0 und 1 festlegen. | | `GetInputVolume()`, `GetOutputVolume()` | Aktuellen Mikrofon- oder Agenten-Audiopegel zwischen 0 und 1 auslesen. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Einen Byte-Puffer mit Frequenzdaten für Audio-Visualisierungen füllen. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Eine Datei hochladen und an eine Nutzernachricht anhängen. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Mikrofon oder Ausgabegerät während einer Sitzung wechseln. | Senden Sie dem Agenten beispielsweise den aktuellen Standort des Spielers, wenn dieser einen neuen Bereich betritt: ```csharp conversation.SendContextualUpdate("The player entered the abandoned lighthouse."); ``` ## WebGL-Builds WebGL-Builds benötigen eine zusätzliche Player-Einstellung. Aktivieren Sie unter **Player Settings** > **WebGL** > **Publishing Settings** die Option **Use WebAssembly.Table**. Wenn diese Einstellung deaktiviert ist, bricht das SDK den Build mit Anweisungen ab. Unity verfügt in WebGL über keine Scriptable-Audio-Pipeline. Daher spielt das SDK die Stimme des Agenten über die Web Audio API des Browsers ab und spiegelt Lautstärke, Position und räumliche Einstellungen Ihrer `OutputAudioSource`. Folglich geben `AudioSource.GetOutputData` und `OnAudioFilterRead` in WebGL Stille zurück. Verwenden Sie stattdessen `GetOutputVolume()` und `GetOutputByteFrequencyData()`. > **Note** > > Der Play Mode im Editor wird noch nicht unterstützt, während WebGL das aktive Build-Ziel ist. Wechseln Sie zu einem > Desktop-Build-Ziel, um im Editor zu testen. Die vollständige WebGL-Kompatibilitätsmatrix finden Sie in [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/COMPATIBILITY.md). ## Fehlerbehebung * **`StartSessionAsync` löst `ArgumentException` aus.** Setzen Sie genau eine der Optionen `AgentId`, `SignedUrl` oder `ConversationToken`. * **Die Sitzung kann sich mit einer gültigen Agenten-ID nicht verbinden.** Der Agent erfordert Authentifizierung. Deaktivieren Sie die Authentifizierung oder verbinden Sie sich mit einer signierten URL. * **Eine Überschreibung hat keine Wirkung.** Aktivieren Sie die entsprechende Überschreibung in den **Security**-Einstellungen des Agenten. * **Der Spieler hört in WebGL nichts.** Browser halten Audio angehalten, bis der Spieler mit der Seite interagiert. Starten Sie die Sitzung nach einem Klick oder Tastendruck. * **Das Mikrofon ist in WebGL nicht verfügbar.** Browser gewähren Mikrofonzugriff nur für Seiten, die über HTTPS oder von `localhost` bereitgestellt werden. Melden Sie Fehler und fordern Sie Funktionen auf [GitHub](https://github.com/elevenlabs/unity/issues) an.