> 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 de Unity > **Info** > > Consulta la [visión general de ElevenAgents](/docs/es/eleven-agents/overview) para entender cómo > funciona ElevenAgents. El [SDK de Unity de ElevenAgents](https://github.com/elevenlabs/unity) 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](https://elevenlabs.io/app/agents) o sigue la [guía de inicio rápido](/docs/es/eleven-agents/quickstart). ### Compatibilidad de plataformas | Destino | Transporte | Estado | | ----------------------------------------------------------------------- | ------------------------------------------ | ------------------------------- | | Editor (modo Play), independiente de escritorio (macOS, Windows, Linux) | WebSocket nativo | Compatible | | WebGL | `@elevenlabs/client` mediante un puente JS | Compatible (WebSocket y WebRTC) | | iOS, Android, XR | WebSocket nativo | Sin probar | 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`. > **Note** > > El SDK no solicita permiso para el micrófono. En iOS y Android, solicítalo tú antes de > iniciar una sesión. ## Instalación En Unity, abre **Window** > **Package Manager**, selecciona **+** > **Install package from git URL** y pega la URL del repositorio: ```text 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. > **Tip** > > El paquete incluye dos ejemplos. Impórtalos desde **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** es un único MonoBehaviour que muestra la transcripción en directo. > **GettingStarted** es una escena de acercarse y hablar, con audio espacial y variables dinámicas. Consulta la > [guía paso a paso de introducción](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) para obtener instrucciones > detalladas. ## 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. #### Crea un agente público Crea un agente en el [panel de ElevenLabs](https://elevenlabs.io/app/agents). En la configuración de **Security** del agente, desactiva **Authentication** para que el juego pueda conectarse solo con el ID del agente. Copia el ID del agente. Para los agentes que requieren autenticación, consulta [Agentes públicos y privados](#public-and-private-agents). #### Instala el SDK Instala el paquete desde la URL de git como se describe en [Instalación](#installation). #### Añade un script de conversación 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` devuelve el control cuando la conexión está abierta y los dispositivos de audio están listos. `EndSession` es idempotente, por lo que puedes llamarlo desde `OnDestroy` sin problemas, incluso si la sesión ya ha terminado. #### Ejecuta la escena Crea un GameObject vacío, añade el componente `AgentConversation` y pega el ID de tu agente en el campo **Agent Id**. Entra en el modo Play y permite el acceso al micrófono si el sistema operativo te lo solicita. El agente dice su primer mensaje y la transcripción aparece en la consola. ## Agentes públicos y privados #### Agentes públicos Pasa el ID del agente directamente. Cualquiera que tenga el ID puede iniciar una conversación con el agente. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Agentes privados Los agentes con la autenticación activada necesitan una credencial de corta duración emitida por tu propio servidor. Solicita una [URL firmada](/docs/es/eleven-agents/customization/authentication) a tu backend y pásala 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 sesiones WebRTC en WebGL, pasa un token de conversación como `ConversationToken` y establece `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > Nunca incluyas tu clave de API de ElevenLabs en una compilación del juego. Genera URL firmadas y tokens de conversación en un servidor que controles. 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`: ```csharp [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](/docs/es/eleven-agents/customization/personalization/dynamic-variables) para rellenar marcadores de posición en el prompt y el primer mensaje del agente, y [anulaciones](/docs/es/eleven-agents/customization/personalization/overrides) para sustituir partes de la configuración del agente durante una sesión: ```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" }, }, }; ``` 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](/docs/es/eleven-agents/customization/tools/client-tools) 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: ```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."; }); ``` 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` 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. | Evento | Carga útil | Descripción | | ------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | La sesión ha terminado. `Reason` es `User`, `Agent` o `Error`. | | `ErrorOccurred` | `string` | Se ha producido un error después de iniciar la sesión. | | `StatusChanged` | `Status` | El estado de conexión ha cambiado. | | `ModeChanged` | `Mode` | El agente ha cambiado entre `Speaking` y `Listening`. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Una transcripción finalizada del habla del jugador. | | `AgentResponded` | `AgentResponseArgs` | El texto de la respuesta del agente. | | `Interrupted` | `InterruptionArgs` | El jugador ha interrumpido al agente. | | `AgentToolRequested` | `AgentToolRequestArgs` | El agente ha iniciado una llamada a una herramienta. `AgentToolResponded` se activa al completarse. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | El agente ha llamado a una herramienta de cliente sin un controlador registrado. | | `CanSendFeedbackChanged` | `bool` | Los comentarios han pasado a estar disponibles o no disponibles para la última respuesta del agente. | 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](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) enumera todos los eventos disponibles. ## Métodos | Método | Descripción | | ------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `EndSession()` | Cierra la conexión y libera los dispositivos de audio. | | `SendUserMessage(string text)` | Envía un mensaje de texto como si lo hubiera dicho el jugador. | | `SendContextualUpdate(string text)` | Comparte el estado del juego con el agente sin interrumpir la conversación. | | `SendUserActivity()` | Indica que el jugador está activo para que el agente mantenga su turno. | | `SendFeedback(bool like)` | Valora la última respuesta del agente cuando `CanSendFeedback` es `true`. | | `SetMicMuted(bool isMuted)` | Silencia o activa el micrófono. | | `SetVolume(float volume)` | Establece el volumen de reproducción del agente entre 0 y 1. | | `GetInputVolume()`, `GetOutputVolume()` | Lee el nivel actual de audio del micrófono o del agente entre 0 y 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Rellena un búfer de bytes con datos de frecuencia para visualizadores de audio. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Sube un archivo y lo adjunta a un mensaje de usuario. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Cambia el micrófono o dispositivo de salida durante una sesión. | Por ejemplo, envía la ubicación actual del jugador al agente cuando entre en una zona nueva: ```csharp 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. > **Note** > > El modo Play en el Editor todavía no es compatible mientras el destino de compilación activo sea WebGL. Cambia a un > destino de compilación de escritorio para probarlo en el Editor. Consulta [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/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](https://github.com/elevenlabs/unity/issues).