Dai voce agli NPC di Unity con ElevenAgents

Ora i giocatori possono avvicinarsi a un personaggio nel tuo gioco Unity e parlargli ad alta voce. Il nuovo SDK Unity di ElevenAgents collega una scena a un agente vocale ElevenLabs. Ascolta tramite il microfono del giocatore, riproduce la voce dell'agente tramite un AudioSource e gestisce la sessione attraverso l'API Conversation.

Lo stesso codice funziona nell'Editor, nelle build desktop e in WebGL; iOS, Android e XR sono in beta.

Avvia una conversazione

Una sessione richiede l'ID di un agente creato nella dashboard di ElevenLabs, che contiene il prompt e la voce. Nel nostro sample GettingStarted, incluso nell'SDK, un trigger collider attorno al personaggio apre la sessione quando il giocatore entra e la chiude quando esce:

private Conversation activeConversation;

private void OnTriggerEnter(Collider other) => _ = StartTalkingAsync();
private void OnTriggerExit(Collider other) => _ = StopTalkingAsync();

private async Awaitable StartTalkingAsync()
{
    var options = new ConversationOptions { AgentId = agentId };
    activeConversation = await Conversation.StartSessionAsync(options);
}

private async Awaitable StopTalkingAsync()
{
    if (activeConversation == null)
        return;
    await activeConversation.EndSession();
    activeConversation = null;
}

StartSessionAsync restituisce il risultato quando la connessione è aperta e i dispositivi audio sono pronti, e seleziona il trasporto corretto per il target di build. EndSession non fa nulla se la sessione è già terminata.

Cosa include l'SDK

Voci che provengono dal personaggio

Per impostazione predefinita, la voce dell'agente viene riprodotta in 2D. Passa il tuo AudioSource come OutputAudioSource e la voce proverrà invece dal personaggio.

GetOutputVolume() restituisce il livello attuale dell'agente, da 0 a 1, su ogni piattaforma. Il sample lo usa per far oscillare il cubo mentre parla e, allo stesso modo, può controllare un'animazione della bocca.

Un agente, molti personaggi

Le variabili dinamiche compilano segnaposto come {{mood}} nel prompt e nel primo messaggio dell'agente, così ogni personaggio può inviare i propri valori all'avvio della sessione. I valori possono essere stringhe, numeri o booleani. Nel sample, un cubo giallo felice e uno rosso arrabbiato condividono un unico agente:

var options = new ConversationOptions
{
    AgentId = agentId,
    OutputAudioSource = audioSource,
    DynamicVariables = new Dictionary<string, object>
    {
        ["color"] = "red",
        ["mood"] = "angry",
    },
};

Per modifiche più ampie, Overrides sostituiscono parte della configurazione dell'agente per una singola sessione, ad esempio il primo messaggio o la voce. Devi prima attivare ogni override nelle impostazioni di Security dell'agente.

Personaggi che sanno cosa sta succedendo

SendContextualUpdate informa l'agente sugli eventi di gioco durante la conversazione, senza interromperlo né aggiungere un turno che il giocatore non ha pronunciato:

activeConversation.SendContextualUpdate("The player picked up the cellar key.");

Personaggi che agiscono nel gioco

I client tool consentono all'agente di attivare il codice di gioco. Definisci il tool nelle impostazioni dell'agente, quindi registra un handler con lo stesso nome:

activeConversation.RegisterTool<OpenDoorParams, string>("open_door", parameters =>
{
    DoorRegistry.Open(parameters.DoorId);
    return $"Door {parameters.DoorId} is open.";
});

L'SDK deserializza i parametri del tool con Newtonsoft Json e invia all'agente tutto ciò che restituisce l'handler. Gli handler possono restituire un Awaitable per operazioni che richiedono tempo e generare un'eccezione ClientToolException per spiegare all'agente perché qualcosa non è riuscito.

Eventi e controlli

Eventi come UserTranscriptReceived, AgentResponded, ModeChanged e Interrupted vengono attivati sul main thread di Unity, quindi puoi aggiornare l'interfaccia utente direttamente da lì. I metodi includono l'input di testo con SendUserMessage, il silenziamento con SetMicMuted, SetVolume, i dati di frequenza per i visualizzatori e il cambio dei dispositivi di input o output durante la sessione. La documentazione dell'SDK Unity li elenca tutti.

Supporto delle piattaforme

L'SDK seleziona il trasporto per ogni target.

• iOS e Android: richiedi l'autorizzazione per il microfono prima di avviare una sessione.
• WebGL: attiva Use WebAssembly.Table in Publishing Settings. Se è disattivata, l'SDK interrompe la build fornendo istruzioni. La modalità Play non funziona quando WebGL è il target di build attivo, quindi esegui i test su un target desktop.
• Audio WebGL: la voce viene riprodotta tramite la Web Audio API, quindi alcune impostazioni di AudioSource, come il routing del mixer e il doppler, non vengono mantenute. Le sessioni WebRTC ignorano OutputAudioSource.

Le note sulla compatibilità contengono l'elenco completo.

Inizia

1. Crea un agente nella dashboard di ElevenLabs. Per un primo test, disattiva Authentication nelle impostazioni di Security, così il gioco potrà connettersi usando soltanto l'ID dell'agente.
2. In Unity, apri Window > Package Manager > + > Install package from git URL e fissa la release: https://github.com/elevenlabs/unity.git#v0.1.0
3. Importa il sample GettingStarted, incolla l'ID del tuo agente e premi Play.

Avvertenza: prima della pubblicazione, riattiva Authentication. Il tuo server richiederà quindi un signed URL a breve durata e il gioco lo passerà come SignedUrl anziché come AgentId. Non inserire mai la tua chiave API ElevenLabs in una build di gioco.

La guida introduttiva richiede circa 10 minuti e termina con un cubo che ti saluta quando ti avvicini. Per tutto il resto, leggi la documentazione dell'SDK Unity e invia bug e richieste di funzionalità nelle issue di GitHub.