> 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** > > Consulte a [visão geral do ElevenAgents](/docs/pt/eleven-agents/overview) para entender como o > ElevenAgents funciona. O [SDK Unity do ElevenAgents](https://github.com/elevenlabs/unity) conecta uma cena Unity a um agente da ElevenLabs. Ele captura o microfone do jogador, transmite a voz do agente de volta por um `AudioSource` e expõe a sessão por uma única API `Conversation` que se comporta da mesma forma no Editor, em players independentes para desktop e em builds WebGL. ## Requisitos * Unity 6.3 LTS (`6000.3.0f1`) ou posterior. O SDK usa APIs de áudio programável introduzidas no Unity 6.3. * **Api Compatibility Level** definido como **.NET Standard 2.1**, o padrão para Unity 2023.1 e versões posteriores. * Uma conta ElevenLabs e um agente. Crie um no [painel](https://elevenlabs.io/app/agents) ou siga o [guia de início rápido](/docs/pt/eleven-agents/quickstart). ### Suporte a plataformas | Destino | Transporte | Status | | ------------------------------------------------------------------------- | ------------------------------------- | ------------------------------- | | Editor (Modo de reprodução), desktop independente (macOS, Windows, Linux) | WebSocket nativo | Compatível | | WebGL | `@elevenlabs/client` por uma ponte JS | Compatível (WebSocket e WebRTC) | | iOS, Android, XR | WebSocket nativo | Não testado | O SDK seleciona automaticamente o transporte para o destino de build ativo. O WebRTC está disponível apenas no WebGL; em todos os outros destinos, `ConnectionType.WebRTC` gera uma `NotSupportedException`. > **Note** > > O SDK não solicita permissão para usar o microfone. No iOS e Android, solicite-a antes de > iniciar uma sessão. ## Instalação No Unity, abra **Window** > **Package Manager**, selecione **+** > **Install package from git URL** e cole a URL do repositório: ```text https://github.com/elevenlabs/unity.git ``` O Package Manager instala o pacote como **ElevenAgents** (`io.elevenlabs.agents`), junto com suas dependências: Input System e Newtonsoft Json. > **Tip** > > O pacote inclui dois exemplos. Importe-os em **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** é um único MonoBehaviour que renderiza a transcrição ao vivo. > **GettingStarted** é uma cena de aproximação e conversa com áudio espacial e variáveis dinâmicas. Consulte o > [guia de introdução passo a passo](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) para um > tutorial detalhado. ## Início rápido Esta seção adiciona um agente de voz a uma cena vazia. O agente começa a falar quando você entra no Modo de reprodução, e a sessão termina quando você sai dele. #### Crie um agente público Crie um agente no [painel da ElevenLabs](https://elevenlabs.io/app/agents). Nas configurações de **Security** do agente, desative **Authentication** para que o jogo possa se conectar somente com o ID do agente. Copie o ID do agente. Para agentes que exigem autenticação, consulte [Agentes públicos e privados](#public-and-private-agents). #### Instale o SDK Instale o pacote pela URL do git conforme descrito em [Instalação](#installation). #### Adicione um script de conversa Crie `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` retorna assim que a conexão é aberta e os dispositivos de áudio estão prontos. `EndSession` é idempotente, portanto chamá-lo de `OnDestroy` é seguro mesmo que a sessão já tenha terminado. #### Execute a cena Crie um GameObject vazio, adicione o componente `AgentConversation` e cole o ID do seu agente no campo **Agent Id**. Entre no Modo de reprodução e permita o acesso ao microfone se o sistema operacional solicitar. O agente fala sua primeira mensagem e a transcrição aparece no Console. ## Agentes públicos e privados #### Agentes públicos Passe o ID do agente diretamente. Qualquer pessoa com o ID pode iniciar uma conversa com o agente. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Agentes privados Agentes com autenticação ativada precisam de uma credencial de curta duração emitida pelo seu próprio servidor. Solicite uma [URL assinada](/docs/pt/eleven-agents/customization/authentication) ao seu backend e passe-a como `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() } ); ``` Para sessões WebRTC no WebGL, passe um token de conversa como `ConversationToken` e defina `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > Nunca inclua sua chave de API da ElevenLabs em uma build de jogo. Gere URLs assinadas e tokens de conversa em um servidor que você controla. Defina exatamente um entre `AgentId`, `SignedUrl` ou `ConversationToken`. Defina `UserId` para associar a conversa a um jogador nos seus próprios sistemas. ## Áudio espacial Por padrão, o SDK reproduz a voz do agente por um `AudioSource` oculto que ele cria. Para posicionar a voz na cena, passe seu próprio `AudioSource` como `OutputAudioSource`: ```csharp [SerializeField] private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6", OutputAudioSource = voiceSource, } ); ``` O SDK mantém a combinação espacial, o rolloff, o roteamento do mixer e a posição da fonte. Ele restaura as configurações de clipe, loop e volume da fonte quando a sessão termina. Para controlar um efeito visual com a voz do agente, como uma animação de boca, leia `conversation.GetOutputVolume()` a cada quadro. Ele retorna um valor entre 0 e 1 em todas as plataformas. ## Personalização Use [variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables) para preencher marcadores no prompt e na primeira mensagem do agente, e [substituições](/docs/pt/eleven-agents/customization/personalization/overrides) para substituir partes da configuração do agente em uma sessão: ```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" }, }, }; ``` Os valores das variáveis dinâmicas devem ser strings, números ou booleanos. Cada substituição deve ser ativada nas configurações de **Security** do agente antes de o servidor aceitá-la. ## Ferramentas do cliente As [ferramentas do cliente](/docs/pt/eleven-agents/customization/tools/client-tools) permitem que o agente acione ações no seu jogo. Defina a ferramenta nas configurações do agente e registre um manipulador com o mesmo 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."; }); ``` O SDK desserializa os parâmetros da ferramenta em `TParams` com Newtonsoft Json, então use `[JsonProperty]` quando o nome de um parâmetro for diferente do nome da propriedade. O valor de retorno é serializado como o resultado da ferramenta. Retorne um `Awaitable` para manipuladores assíncronos. Gere uma `ClientToolException` com um `errorType` para informar uma falha específica ao agente; qualquer outra exceção é informada como um erro genérico. Chamadas a ferramentas sem um manipulador registrado geram `ErrorOccurred` ou `UnhandledClientToolCall` caso você assine esse evento. ## Eventos Assine os eventos da `Conversation` retornada por `StartSessionAsync`. O SDK os dispara na thread principal do Unity. | Evento | Carga útil | Descrição | | ------------------------- | ---------------------- | ----------------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | A sessão terminou. `Reason` é `User`, `Agent` ou `Error`. | | `ErrorOccurred` | `string` | Ocorreu um erro após o início da sessão. | | `StatusChanged` | `Status` | O status da conexão foi alterado. | | `ModeChanged` | `Mode` | O agente alternou entre `Speaking` e `Listening`. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Uma transcrição finalizada da fala do jogador. | | `AgentResponded` | `AgentResponseArgs` | O texto da resposta do agente. | | `Interrupted` | `InterruptionArgs` | O jogador interrompeu o agente. | | `AgentToolRequested` | `AgentToolRequestArgs` | O agente iniciou uma chamada de ferramenta. `AgentToolResponded` é disparado ao concluir. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | O agente chamou uma ferramenta do cliente sem manipulador registrado. | | `CanSendFeedbackChanged` | `bool` | O feedback ficou disponível ou indisponível para a resposta mais recente do agente. | O evento `Connected` é disparado antes de `StartSessionAsync` retornar, portanto leia `ConversationId` e `Status` diretamente assim que a chamada for concluída. O [changelog do pacote](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) lista todos os eventos disponíveis. ## Métodos | Método | Descrição | | ------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `EndSession()` | Fecha a conexão e libera os dispositivos de áudio. | | `SendUserMessage(string text)` | Envia uma mensagem de texto como se o jogador a tivesse falado. | | `SendContextualUpdate(string text)` | Compartilha o estado do jogo com o agente sem interromper a conversa. | | `SendUserActivity()` | Sinaliza que o jogador está ativo para que o agente mantenha seu turno. | | `SendFeedback(bool like)` | Avalia a resposta mais recente do agente quando `CanSendFeedback` é `true`. | | `SetMicMuted(bool isMuted)` | Silencia ou reativa o microfone. | | `SetVolume(float volume)` | Define o volume de reprodução do agente entre 0 e 1. | | `GetInputVolume()`, `GetOutputVolume()` | Lê o nível atual de áudio do microfone ou do agente entre 0 e 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Preenche um buffer de bytes com dados de frequência para visualizadores de áudio. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Envia um arquivo e o anexa a uma mensagem do usuário. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Altera o microfone ou dispositivo de saída durante uma sessão. | Por exemplo, envie a localização atual do jogador ao agente quando ele entrar em uma nova área: ```csharp conversation.SendContextualUpdate("The player entered the abandoned lighthouse."); ``` ## Builds WebGL As builds WebGL precisam de uma configuração adicional do Player. Em **Player Settings** > **WebGL** > **Publishing Settings**, ative **Use WebAssembly.Table**. O SDK falha a build com instruções se essa configuração estiver desativada. O Unity não tem um pipeline de áudio programável no WebGL, então o SDK reproduz a voz do agente pela API Web Audio do navegador e espelha o volume, a posição e as configurações espaciais do seu `OutputAudioSource`. Como resultado, `AudioSource.GetOutputData` e `OnAudioFilterRead` retornam silêncio no WebGL. Use `GetOutputVolume()` e `GetOutputByteFrequencyData()` em vez disso. > **Note** > > O Modo de reprodução no Editor ainda não é compatível quando o destino de build ativo é WebGL. Mude para um > destino de build desktop para testar no Editor. Consulte [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/COMPATIBILITY.md) para ver a matriz completa de compatibilidade com WebGL. ## Solução de problemas * **`StartSessionAsync` gera `ArgumentException`.** Defina exatamente um entre `AgentId`, `SignedUrl` ou `ConversationToken`. * **A sessão não consegue se conectar com um ID de agente válido.** O agente exige autenticação. Desative a autenticação ou conecte-se com uma URL assinada. * **Uma substituição não tem efeito.** Ative a substituição correspondente nas configurações de **Security** do agente. * **O jogador não ouve nada no WebGL.** Os navegadores mantêm o áudio suspenso até que o jogador interaja com a página. Inicie a sessão após um clique ou pressionamento de tecla. * **O microfone não está disponível no WebGL.** Os navegadores só concedem acesso ao microfone para páginas servidas por HTTPS ou a partir de `localhost`. Relate bugs e solicite recursos no [GitHub](https://github.com/elevenlabs/unity/issues).