> 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. # SDK Unity > **Info** > > Consulta la [panoramica di ElevenAgents](/docs/it/eleven-agents/overview) per una spiegazione di come > funziona ElevenAgents. L'[SDK Unity di ElevenAgents](https://github.com/elevenlabs/unity) 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](https://elevenlabs.io/app/agents) o segui la [guida rapida](/docs/it/eleven-agents/quickstart). ### Supporto delle piattaforme | Target | Transport | Stato | | -------------------------------------------------------------- | -------------------------------------- | ------------------------------- | | Editor (Play Mode), standalone desktop (macOS, Windows, Linux) | WebSocket nativo | Supportato | | WebGL | `@elevenlabs/client` tramite bridge JS | Supportato (WebSocket e WebRTC) | | iOS, Android, XR | WebSocket nativo | Non testato | 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`. > **Note** > > L'SDK non richiede l'autorizzazione per il microfono. Su iOS e Android, richiedila tu prima di > avviare una sessione. ## Installazione In Unity, apri **Window** > **Package Manager**, seleziona **+** > **Install package from git URL** e incolla l'URL del repository: ```text 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. > **Tip** > > Il pacchetto include due esempi. Importali da **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** è un singolo MonoBehaviour che visualizza la trascrizione in tempo reale. > **GettingStarted** è una scena in cui puoi avvicinarti e parlare, con audio spaziale e variabili dinamiche. Consulta la > [guida introduttiva dettagliata](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) per una > guida passo passo. ## 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. #### Crea un agente pubblico Crea un agente nella [dashboard di ElevenLabs](https://elevenlabs.io/app/agents). Nelle impostazioni **Security** dell'agente, disattiva **Authentication** affinché il gioco possa connettersi usando solo l'ID dell'agente. Copia l'ID dell'agente. Per gli agenti che richiedono l'autenticazione, consulta [Agenti pubblici e privati](#public-and-private-agents). #### Installa l'SDK Installa il pacchetto dall'URL git come descritto in [Installazione](#installation). #### Aggiungi uno script di conversazione Crea `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` restituisce il controllo quando la connessione è aperta e i dispositivi audio sono pronti. `EndSession` è idempotente, quindi puoi chiamarlo da `OnDestroy` in sicurezza anche se la sessione è già terminata. #### Esegui la scena Crea un GameObject vuoto, aggiungi il componente `AgentConversation` e incolla l'ID dell'agente nel campo **Agent Id**. Entra in Play Mode e consenti l'accesso al microfono se il sistema operativo lo richiede. L'agente pronuncia il suo primo messaggio e la trascrizione appare nella Console. ## Agenti pubblici e privati #### Agenti pubblici Passa direttamente l'ID dell'agente. Chiunque disponga dell'ID può avviare una conversazione con l'agente. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Agenti privati Gli agenti con autenticazione abilitata richiedono una credenziale temporanea emessa dal tuo server. Richiedi un [URL firmato](/docs/it/eleven-agents/customization/authentication) dal tuo backend e passalo come `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() } ); ``` Per le sessioni WebRTC su WebGL, passa un token di conversazione come `ConversationToken` e imposta `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > Non includere mai la chiave API di ElevenLabs in una build del gioco. Genera URL firmati e token di conversazione su un server sotto il tuo controllo. 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`: ```csharp [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](/docs/it/eleven-agents/customization/personalization/dynamic-variables) per compilare i placeholder nel prompt e nel primo messaggio dell'agente, e le [sostituzioni](/docs/it/eleven-agents/customization/personalization/overrides) per sostituire parti della configurazione dell'agente per una sessione: ```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" }, }, }; ``` 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](/docs/it/eleven-agents/customization/tools/client-tools) consentono all'agente di attivare azioni nel tuo gioco. Definisci lo strumento nelle impostazioni dell'agente, quindi registra un handler con lo stesso nome: ```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."; }); ``` 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` 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. | Evento | Payload | Descrizione | | ------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | La sessione è terminata. `Reason` è `User`, `Agent` o `Error`. | | `ErrorOccurred` | `string` | Si è verificato un errore dopo l'avvio della sessione. | | `StatusChanged` | `Status` | Lo stato della connessione è cambiato. | | `ModeChanged` | `Mode` | L'agente è passato da `Speaking` a `Listening` o viceversa. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Una trascrizione finalizzata del parlato del giocatore. | | `AgentResponded` | `AgentResponseArgs` | Il testo della risposta dell'agente. | | `Interrupted` | `InterruptionArgs` | Il giocatore ha interrotto l'agente. | | `AgentToolRequested` | `AgentToolRequestArgs` | L'agente ha avviato una chiamata a uno strumento. `AgentToolResponded` si attiva al completamento. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | L'agente ha chiamato uno strumento client senza handler registrato. | | `CanSendFeedbackChanged` | `bool` | Il feedback è diventato disponibile o non disponibile per l'ultima risposta dell'agente. | 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](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) elenca tutti gli eventi disponibili. ## Metodi | Metodo | Descrizione | | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `EndSession()` | Chiude la connessione e rilascia i dispositivi audio. | | `SendUserMessage(string text)` | Invia un messaggio di testo come se il giocatore lo avesse pronunciato. | | `SendContextualUpdate(string text)` | Condivide lo stato del gioco con l'agente senza interrompere la conversazione. | | `SendUserActivity()` | Segnala che il giocatore è attivo affinché l'agente mantenga il turno. | | `SendFeedback(bool like)` | Valuta l'ultima risposta dell'agente quando `CanSendFeedback` è `true`. | | `SetMicMuted(bool isMuted)` | Disattiva o riattiva il microfono. | | `SetVolume(float volume)` | Imposta il volume di riproduzione dell'agente tra 0 e 1. | | `GetInputVolume()`, `GetOutputVolume()` | Legge il livello audio corrente del microfono o dell'agente tra 0 e 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Riempie un buffer di byte con dati di frequenza per i visualizzatori audio. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Carica un file e lo allega a un messaggio utente. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Cambia il microfono o il dispositivo di output durante una sessione. | Ad esempio, invia all'agente la posizione corrente del giocatore quando entra in una nuova area: ```csharp 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()`. > **Note** > > Il Play Mode nell'Editor non è ancora supportato quando il target di build attivo è WebGL. Passa a un > target di build desktop per eseguire i test nell'Editor. Consulta [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/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](https://github.com/elevenlabs/unity/issues).