SDK de Unity

El SDK de Unity de ElevenAgents conecta una escena de Unity con un agente de ElevenLabs. Captura el micrófono del jugador, transmite la voz del agente de vuelta mediante un AudioSource y expone la sesión a través de una única API Conversation que se comporta igual en el Editor, los reproductores independientes de escritorio y las compilaciones WebGL.

Requisitos

• Unity 6.3 LTS (6000.3.0f1) o posterior. El SDK utiliza las API de audio programable introducidas en Unity 6.3.
• Api Compatibility Level configurado en .NET Standard 2.1, el valor predeterminado de Unity 2023.1 y versiones posteriores.
• Una cuenta de ElevenLabs y un agente. Crea uno en el panel o sigue la guía de inicio rápido.

Compatibilidad de plataformas

El SDK selecciona automáticamente el transporte para el destino de compilación activo. WebRTC solo está disponible en WebGL; en cualquier otro destino, ConnectionType.WebRTC genera una NotSupportedException.

Instalación

En Unity, abre Window > Package Manager, selecciona + > Install package from git URL y pega la URL del repositorio:

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

El Package Manager instala el paquete como ElevenAgents (io.elevenlabs.agents), junto con sus dependencias: Input System y Newtonsoft Json.

Inicio rápido

Esta sección añade un agente de voz a una escena vacía. El agente empieza a hablar al entrar en el modo Play y la sesión termina al salir de él.

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 y privados

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

Configura exactamente uno de AgentId, SignedUrl o ConversationToken. Configura UserId para asociar la conversación con un jugador en tus propios sistemas.

Audio espacial

De forma predeterminada, el SDK reproduce la voz del agente mediante un AudioSource oculto que crea él mismo. Para situar la voz en la escena, pasa tu propio 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,
    }
);

El SDK conserva la mezcla espacial, la atenuación, el enrutamiento del mezclador y la posición de la fuente. Restaura la configuración de clip, bucle y volumen de la fuente cuando termina la sesión.

Para controlar un efecto visual con la voz del agente, como una animación de boca, lee conversation.GetOutputVolume() en cada fotograma. Devuelve un valor entre 0 y 1 en todas las plataformas.

Personalización

Usa variables dinámicas para rellenar marcadores de posición en el prompt y el primer mensaje del agente, y anulaciones para sustituir partes de la configuración del agente durante una sesión:

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

Los valores de las variables dinámicas deben ser cadenas, números o valores booleanos. Cada anulación debe estar activada en la configuración de Security del agente antes de que el servidor la acepte.

Herramientas de cliente

Las herramientas de cliente permiten al agente activar acciones en tu juego. Define la herramienta en la configuración del agente y, después, registra un controlador con el mismo nombre:

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

El SDK deserializa los parámetros de la herramienta en TParams con Newtonsoft Json, así que usa [JsonProperty] cuando el nombre de un parámetro difiera del nombre de la propiedad. El valor de retorno se serializa como resultado de la herramienta. Devuelve un Awaitable<TResult> para controladores asíncronos. Genera una ClientToolException con un errorType para informar de un fallo específico al agente; cualquier otra excepción se informa como un error genérico.

Las llamadas a herramientas sin un controlador registrado generan ErrorOccurred, o UnhandledClientToolCall si estás suscrito a este evento.

Eventos

Suscríbete a los eventos de la Conversation que devuelve StartSessionAsync. El SDK los genera en el hilo principal de Unity.

El evento Connected se activa antes de que StartSessionAsync devuelva el control, así que lee ConversationId y Status directamente cuando termine la llamada. El registro de cambios del paquete enumera todos los eventos disponibles.

Métodos

Por ejemplo, envía la ubicación actual del jugador al agente cuando entre en una zona nueva:

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

Compilaciones WebGL

Las compilaciones WebGL necesitan una configuración adicional del reproductor. En Player Settings > WebGL > Publishing Settings, activa Use WebAssembly.Table. El SDK hace que la compilación falle con instrucciones si esta opción está desactivada.

Unity no dispone de una canalización de audio programable en WebGL, por lo que el SDK reproduce la voz del agente mediante la API Web Audio del navegador y refleja el volumen, la posición y la configuración espacial de tu OutputAudioSource. Como resultado, AudioSource.GetOutputData y OnAudioFilterRead devuelven silencio en WebGL. Usa GetOutputVolume() y GetOutputByteFrequencyData() en su lugar.

Consulta COMPATIBILITY.md para ver la matriz completa de compatibilidad con WebGL.

Resolución de problemas

• StartSessionAsync genera ArgumentException. Configura exactamente uno de AgentId, SignedUrl o ConversationToken.
• La sesión no logra conectarse con un ID de agente válido. El agente requiere autenticación. Desactiva la autenticación o conéctate con una URL firmada.
• Una anulación no tiene efecto. Activa la anulación correspondiente en la configuración de Security del agente.
• El jugador no oye nada en WebGL. Los navegadores mantienen el audio suspendido hasta que el jugador interactúa con la página. Inicia la sesión después de un clic o de pulsar una tecla.
• El micrófono no está disponible en WebGL. Los navegadores solo conceden acceso al micrófono a páginas servidas mediante HTTPS o desde localhost.

Informa de errores y solicita funcionalidades en GitHub.