SDK Unity

L’SDK Unity di ElevenAgents collega una scena Unity a un agente ElevenLabs. Acquisisce il microfono del giocatore, riproduce in streaming la voce dell’agente tramite un AudioSource ed espone la sessione attraverso un’unica API Conversation che si comporta allo stesso modo nell’Editor, nei player desktop standalone e nelle build WebGL.

Requisiti

• Unity 6.3 LTS (6000.3.0f1) o versioni successive. L’SDK usa API audio scriptabili introdotte in Unity 6.3.
• Api Compatibility Level impostato su .NET Standard 2.1, il valore predefinito per Unity 2023.1 e versioni successive.
• Un account ElevenLabs e un agente. Creane uno nella dashboard o segui la guida rapida.

Supporto delle piattaforme

L’SDK seleziona automaticamente il transport per il target di build attivo. WebRTC è disponibile solo su WebGL; su ogni altro target ConnectionType.WebRTC genera una NotSupportedException.

Installazione

In Unity, apri Window > Package Manager, seleziona + > Install package from git URL e incolla l’URL del repository:

https://github.com/elevenlabs/unity.git

Il Package Manager installa il pacchetto come ElevenAgents (io.elevenlabs.agents), insieme alle sue dipendenze: Input System e Newtonsoft Json.

Guida rapida

Questa sezione aggiunge un agente vocale a una scena vuota. L’agente inizia a parlare quando entri in Play Mode e la sessione termina quando ne esci.

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

Agenti pubblici e privati

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

Imposta esattamente uno tra AgentId, SignedUrl e ConversationToken. Imposta UserId per associare la conversazione a un giocatore nei tuoi sistemi.

Audio spaziale

Per impostazione predefinita, l’SDK riproduce la voce dell’agente tramite un AudioSource nascosto che crea automaticamente. Per posizionare la voce nella scena, passa il tuo AudioSource come OutputAudioSource:

[SerializeField]
private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio
var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions
    {
        AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6",
        OutputAudioSource = voiceSource,
    }
);

L’SDK mantiene spatial blend, rolloff, routing del mixer e posizione della sorgente. Ripristina le impostazioni di clip, loop e volume della sorgente al termine della sessione.

Per controllare un effetto visivo con la voce dell’agente, ad esempio l’animazione della bocca, leggi conversation.GetOutputVolume() a ogni frame. Restituisce un valore compreso tra 0 e 1 su ogni piattaforma.

Personalizzazione

Usa le variabili dinamiche per compilare i placeholder nel prompt e nel primo messaggio dell’agente, e le sostituzioni per sostituire parti della configurazione dell’agente per una sessione:

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

I valori delle variabili dinamiche devono essere stringhe, numeri o valori booleani. Ogni sostituzione deve essere abilitata nelle impostazioni Security dell’agente prima che il server la accetti.

Strumenti client

Gli strumenti client consentono all’agente di attivare azioni nel tuo gioco. Definisci lo strumento nelle impostazioni dell’agente, quindi registra un handler con lo stesso nome:

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

L’SDK deserializza i parametri dello strumento in TParams con Newtonsoft Json, quindi usa [JsonProperty] quando il nome di un parametro è diverso dal nome della proprietà. Il valore restituito viene serializzato come risultato dello strumento. Restituisci un Awaitable<TResult> per gli handler asincroni. Genera ClientToolException con un errorType per segnalare all’agente un errore specifico; qualsiasi altra eccezione viene segnalata come errore generico.

Le chiamate a strumenti senza un handler registrato generano ErrorOccurred, oppure UnhandledClientToolCall se vi hai effettuato la sottoscrizione.

Eventi

Sottoscrivi gli eventi su Conversation restituito da StartSessionAsync. L’SDK li genera sul thread principale di Unity.

L’evento Connected si attiva prima che StartSessionAsync restituisca il controllo, quindi leggi direttamente ConversationId e Status al termine della chiamata. Il changelog del pacchetto elenca tutti gli eventi disponibili.

Metodi

Ad esempio, invia all’agente la posizione corrente del giocatore quando entra in una nuova area:

conversation.SendContextualUpdate("The player entered the abandoned lighthouse.");

Build WebGL

Le build WebGL richiedono un’ulteriore Player Setting. In Player Settings > WebGL > Publishing Settings, attiva Use WebAssembly.Table. Se questa impostazione è disattivata, l’SDK interrompe la build con istruzioni.

Unity non dispone di una pipeline audio scriptabile su WebGL, quindi l’SDK riproduce la voce dell’agente tramite la Web Audio API del browser e rispecchia le impostazioni di volume, posizione e spazialità del tuo OutputAudioSource. Di conseguenza, AudioSource.GetOutputData e OnAudioFilterRead restituiscono silenzio su WebGL. Usa invece GetOutputVolume() e GetOutputByteFrequencyData().

Consulta COMPATIBILITY.md per la matrice completa di compatibilità WebGL.

Risoluzione dei problemi

• StartSessionAsync genera ArgumentException. Imposta esattamente uno tra AgentId, SignedUrl e ConversationToken.
• La sessione non riesce a connettersi con un ID agente valido. L’agente richiede l’autenticazione. Disattivala oppure connettiti con un URL firmato.
• Una sostituzione non ha effetto. Abilita la sostituzione corrispondente nelle impostazioni Security dell’agente.
• Il giocatore non sente nulla su WebGL. I browser mantengono l’audio sospeso finché il giocatore non interagisce con la pagina. Avvia la sessione dopo un clic o la pressione di un tasto.
• Il microfono non è disponibile su WebGL. I browser concedono l’accesso al microfono solo alle pagine servite tramite HTTPS o da localhost.

Segnala bug e richiedi funzionalità su GitHub.