Unity SDK

Das ElevenAgents Unity SDK 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 oder folgen Sie dem Schnellstart.

Plattformunterstützung

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.

Installation

Öffnen Sie in Unity Window > Package Manager, wählen Sie + > Install package from git URL und fügen Sie die Repository-URL ein:

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.

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.

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();
    }
}

Öffentliche und private Agenten

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

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:

[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, um Platzhalter im Prompt und in der ersten Nachricht des Agenten zu füllen, und Überschreibungen, um Teile der Agentenkonfiguration für eine Sitzung zu ersetzen:

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" },
    },
};

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 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:

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.";
});

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<TResult> 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.

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 listet alle Ereignisse auf.

Methoden

Senden Sie dem Agenten beispielsweise den aktuellen Standort des Spielers, wenn dieser einen neuen Bereich betritt:

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().

Die vollständige WebGL-Kompatibilitätsmatrix finden Sie in 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 an.