Unity SDK

ElevenAgents Unity SDK łączy scenę Unity z agentem ElevenLabs. Przechwytuje mikrofon gracza, przesyła głos agenta przez AudioSource i udostępnia sesję przez jedno API Conversation, które działa tak samo w edytorze, samodzielnych wersjach desktopowych i wersjach WebGL.

Wymagania

• Unity 6.3 LTS (6000.3.0f1) lub nowsze. SDK korzysta z API scriptable audio wprowadzonych w Unity 6.3.
• Api Compatibility Level ustawiony na .NET Standard 2.1, domyślne ustawienie dla Unity 2023.1 i nowszych.
• Konto ElevenLabs i agent. Utwórz go w panelu lub skorzystaj z szybkiego startu.

Obsługiwane platformy

SDK automatycznie wybiera transport dla aktywnego celu kompilacji. WebRTC jest dostępne tylko w WebGL; w każdym innym celu ConnectionType.WebRTC zgłasza NotSupportedException.

Instalacja

W Unity otwórz Window > Package Manager, wybierz + > Install package from git URL i wklej adres URL repozytorium:

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

Package Manager instaluje pakiet jako ElevenAgents (io.elevenlabs.agents) wraz z zależnościami: Input System i Newtonsoft Json.

Szybki start

W tej sekcji dodasz agenta głosowego do pustej sceny. Agent zacznie mówić po wejściu w Play Mode, a sesja zakończy się po jego opuszczeniu.

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

Agenci publiczni i prywatni

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

Ustaw dokładnie jedno z: AgentId, SignedUrl lub ConversationToken. Ustaw UserId, aby powiązać rozmowę z graczem w swoich systemach.

Dźwięk przestrzenny

Domyślnie SDK odtwarza głos agenta przez ukryty AudioSource, który tworzy. Aby umieścić głos w scenie, przekaż własny AudioSource jako OutputAudioSource:

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

SDK zachowuje ustawienia spatial blend, rolloff, routing miksera i pozycję źródła. Po zakończeniu sesji przywraca ustawienia clipu, pętli i głośności źródła.

Aby sterować efektem wizualnym na podstawie głosu agenta, na przykład animacją ust, odczytuj conversation.GetOutputVolume() w każdej klatce. Zwraca wartość od 0 do 1 na każdej platformie.

Personalizacja

Użyj zmiennych dynamicznych, aby wypełnić placeholdery w prompcie agenta i pierwszej wiadomości, oraz nadpisań, aby zastąpić części konfiguracji agenta w jednej sesji:

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

Wartości zmiennych dynamicznych muszą być ciągami znaków, liczbami lub wartościami logicznymi. Każde nadpisanie musi zostać włączone w ustawieniach Security agenta, zanim serwer je zaakceptuje.

Narzędzia klienta

Narzędzia klienta pozwalają agentowi uruchamiać działania w twojej grze. Zdefiniuj narzędzie w ustawieniach agenta, a potem zarejestruj handler o tej samej nazwie:

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 deserializuje parametry narzędzia do TParams za pomocą Newtonsoft Json, więc użyj [JsonProperty], gdy nazwa parametru różni się od nazwy właściwości. Wartość zwracana jest serializowana jako wynik narzędzia. Dla asynchronicznych handlerów zwracaj Awaitable<TResult>. Zgłoś ClientToolException z errorType, aby przekazać agentowi konkretny błąd; każdy inny wyjątek jest zgłaszany jako błąd ogólny.

Wywołania narzędzi bez zarejestrowanego handlera wywołują ErrorOccurred albo UnhandledClientToolCall, jeśli subskrybujesz to zdarzenie.

Zdarzenia

Subskrybuj zdarzenia w obiekcie Conversation zwróconym przez StartSessionAsync. SDK wywołuje je w głównym wątku Unity.

Zdarzenie Connected jest wywoływane przed zwróceniem wyniku przez StartSessionAsync, więc po zakończeniu wywołania odczytaj bezpośrednio ConversationId i Status. Dziennik zmian pakietu zawiera pełną listę zdarzeń.

Metody

Na przykład wyślij agentowi bieżącą lokalizację gracza, gdy wejdzie on do nowego obszaru:

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

Wersje WebGL

Wersje WebGL wymagają jednego dodatkowego ustawienia Player. W Player Settings > WebGL > Publishing Settings włącz Use WebAssembly.Table. Jeśli to ustawienie jest wyłączone, SDK zatrzyma kompilację i wyświetli instrukcje.

Unity nie ma pipeline’u scriptable audio w WebGL, więc SDK odtwarza głos agenta przez Web Audio API przeglądarki i odzwierciedla ustawienia głośności, pozycji oraz przestrzenne twojego OutputAudioSource. W rezultacie AudioSource.GetOutputData i OnAudioFilterRead zwracają ciszę w WebGL. Zamiast tego użyj GetOutputVolume() i GetOutputByteFrequencyData().

Pełną macierz zgodności WebGL znajdziesz w pliku COMPATIBILITY.md.

Rozwiązywanie problemów

• StartSessionAsync zgłasza ArgumentException. Ustaw dokładnie jedno z: AgentId, SignedUrl lub ConversationToken.
• Sesja nie może się połączyć mimo prawidłowego identyfikatora agenta. Agent wymaga uwierzytelniania. Wyłącz uwierzytelnianie lub połącz się przez podpisany adres URL.
• Nadpisanie nie działa. Włącz odpowiadające mu nadpisanie w ustawieniach Security agenta.
• Gracz nic nie słyszy w WebGL. Przeglądarki wstrzymują dźwięk, dopóki gracz nie wejdzie w interakcję ze stroną. Rozpocznij sesję po kliknięciu lub naciśnięciu klawisza.
• Mikrofon jest niedostępny w WebGL. Przeglądarki przyznają dostęp do mikrofonu tylko stronom obsługiwanym przez HTTPS lub z localhost.

Zgłaszaj błędy i proś o funkcje na GitHubie.