Unity SDK

De ElevenAgents Unity SDK 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 of volg de quickstart.

Platformondersteuning

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.

Installatie

Open in Unity Window > Package Manager, selecteer + > Install package from git URL en plak de repository-URL:

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.

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.

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

Openbare en privéagenten

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

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:

[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 om placeholders in de prompt en het eerste bericht van de agent in te vullen, en overschrijvingen om delen van de agentconfiguratie voor één sessie te vervangen:

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

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

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

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

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 bevat de volledige lijst met events.

Methoden

Stuur bijvoorbeeld de huidige locatie van de speler naar de agent wanneer deze een nieuw gebied betreedt:

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

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