Unity SDK

ElevenAgents Unity SDK ansluter en Unity-scen till en ElevenLabs-agent. Det fångar spelarens mikrofonljud, strömmar tillbaka agentens röst via en AudioSource och exponerar sessionen via ett enda Conversation-API som fungerar likadant i editorn, fristående desktop-spelare och WebGL-byggen.

Krav

• Unity 6.3 LTS (6000.3.0f1) eller senare. SDK:t använder scriptable-audio-API:er som introducerades i Unity 6.3.
• Api Compatibility Level inställd på .NET Standard 2.1, standardvärdet för Unity 2023.1 och senare.
• Ett ElevenLabs-konto och en agent. Skapa en i dashboarden eller följ snabbstarten.

Plattformsstöd

SDK:t väljer automatiskt transport för det aktiva byggmålet. WebRTC är endast tillgängligt på WebGL; på alla andra mål ger ConnectionType.WebRTC ett NotSupportedException.

Installation

I Unity öppnar du Window > Package Manager, väljer + > Install package from git URL och klistrar in repository-URL:en:

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

Package Manager installerar paketet som ElevenAgents (io.elevenlabs.agents) tillsammans med dess beroenden: Input System och Newtonsoft Json.

Snabbstart

I det här avsnittet lägger du till en röstagent i en tom scen. Agenten börjar prata när du går in i Play Mode och sessionen avslutas när du lämnar det.

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

Offentliga och privata agenter

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

Ange exakt en av AgentId, SignedUrl eller ConversationToken. Ange UserId för att koppla samtalet till en spelare i dina egna system.

Rumsligt ljud

Som standard spelar SDK:t agentens röst via en dold AudioSource som det skapar. Om du vill placera rösten i scenen skickar du din egen AudioSource som OutputAudioSource:

[SerializeField]
private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio
var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions
    {
        AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6",
        OutputAudioSource = voiceSource,
    }
);

SDK:t behåller källans rumsliga mixning, avståndsdämpning, mixer-routning och position. Det återställer källans inställningar för klipp, loop och volym när sessionen avslutas.

Om du vill styra en visuell effekt med agentens röst, till exempel en munanimation, läser du conversation.GetOutputVolume() varje bildruta. Den returnerar ett värde mellan 0 och 1 på alla plattformar.

Personalisering

Använd dynamiska variabler för att fylla platshållare i agentens prompt och första meddelande, och åsidosättningar för att ersätta delar av agentkonfigurationen för en session:

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

Värden för dynamiska variabler måste vara strängar, tal eller booleska värden. Varje åsidosättning måste aktiveras i agentens Security-inställningar innan servern godkänner den.

Klientverktyg

Klientverktyg låter agenten utlösa åtgärder i ditt spel. Definiera verktyget i agentens inställningar och registrera sedan en hanterare med samma namn:

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

SDK:t deserialiserar verktygsparametrarna till TParams med Newtonsoft Json, så använd [JsonProperty] när ett parameternamn skiljer sig från egenskapsnamnet. Returvärdet serialiseras som verktygsresultatet. Returnera en Awaitable<TResult> för asynkrona hanterare. Kasta ClientToolException med en errorType för att rapportera ett specifikt fel till agenten; alla andra undantag rapporteras som ett generiskt fel.

Anrop till verktyg utan registrerad hanterare utlöser ErrorOccurred, eller UnhandledClientToolCall om du prenumererar på den.

Händelser

Prenumerera på händelser i Conversation som returneras av StartSessionAsync. SDK:t utlöser dem i Unitys huvudtråd.

Händelsen Connected utlöses innan StartSessionAsync returnerar, så läs ConversationId och Status direkt när anropet är klart. Paketets ändringslogg listar alla händelser.

Metoder

Du kan till exempel skicka spelarens aktuella plats till agenten när spelaren går in i ett nytt område:

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

WebGL-byggen

WebGL-byggen behöver ytterligare en Player Setting. I Player Settings > WebGL > Publishing Settings aktiverar du Use WebAssembly.Table. SDK:t misslyckar bygget med instruktioner om den här inställningen är av.

Unity har ingen scriptable audio-pipeline på WebGL, så SDK:t spelar agentens röst via webbläsarens Web Audio API och speglar volym-, positions- och rumsinställningarna för din OutputAudioSource. Därför returnerar AudioSource.GetOutputData och OnAudioFilterRead tystnad på WebGL. Använd i stället GetOutputVolume() och GetOutputByteFrequencyData().

Se COMPATIBILITY.md för hela kompatibilitetsmatrisen för WebGL.

Felsökning

• StartSessionAsync kastar ArgumentException. Ange exakt en av AgentId, SignedUrl eller ConversationToken.
• Sessionen kan inte ansluta med ett giltigt agent-ID. Agenten kräver autentisering. Stäng av autentisering eller anslut med en signerad URL.
• En åsidosättning har ingen effekt. Aktivera motsvarande åsidosättning i agentens Security-inställningar.
• Spelaren hör ingenting på WebGL. Webbläsare håller ljud pausat tills spelaren interagerar med sidan. Starta sessionen efter ett klick eller en tangenttryckning.
• Mikrofonen är inte tillgänglig på WebGL. Webbläsare ger bara mikrofonåtkomst till sidor som levereras över HTTPS eller från localhost.

Rapportera buggar och begär funktioner på GitHub.