SDK Unity

O SDK Unity do ElevenAgents 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 ou siga o guia de início rápido.

Suporte a plataformas

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.

Instalação

No Unity, abra Window > Package Manager, selecione + > Install package from git URL e cole a URL do repositório:

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.

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.

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

Agentes públicos e privados

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

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:

[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 para preencher marcadores no prompt e na primeira mensagem do agente, e substituições para substituir partes da configuração do agente em uma sessão:

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

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

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

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

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 lista todos os eventos disponíveis.

Métodos

Por exemplo, envie a localização atual do jogador ao agente quando ele entrar em uma nova área:

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.

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