> 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. # Unity SDK > **Info** > > Zobacz [omówienie ElevenAgents](/docs/pl/eleven-agents/overview), aby dowiedzieć się, jak działa > ElevenAgents. [ElevenAgents Unity SDK](https://github.com/elevenlabs/unity) łą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](https://elevenlabs.io/app/agents) lub skorzystaj z [szybkiego startu](/docs/pl/eleven-agents/quickstart). ### Obsługiwane platformy | Cel | Transport | Status | | ------------------------------------------------------------------------- | ---------------------------------- | -------------------------------- | | Edytor (Play Mode), samodzielne wersje desktopowe (macOS, Windows, Linux) | Natywny WebSocket | Obsługiwane | | WebGL | `@elevenlabs/client` przez most JS | Obsługiwane (WebSocket i WebRTC) | | iOS, Android, XR | Natywny WebSocket | Nieprzetestowane | 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`. > **Note** > > SDK nie prosi o dostęp do mikrofonu. W systemach iOS i Android poproś o niego samodzielnie przed > rozpoczęciem sesji. ## Instalacja W Unity otwórz **Window** > **Package Manager**, wybierz **+** > **Install package from git URL** i wklej adres URL repozytorium: ```text 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. > **Tip** > > Pakiet zawiera dwa przykłady. Zaimportuj je przez **Package Manager** > **ElevenAgents** > > **Samples**. **QuickStart** to pojedynczy MonoBehaviour wyświetlający transkrypcję na żywo. > **GettingStarted** to scena podejdź-i-porozmawiaj z dźwiękiem przestrzennym i zmiennymi dynamicznymi. Zobacz > [instrukcję pierwszych kroków](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md), aby poznać > przewodnik krok po kroku. ## 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. #### Utwórz publicznego agenta Utwórz agenta w [panelu ElevenLabs](https://elevenlabs.io/app/agents). W ustawieniach **Security** agenta wyłącz **Authentication**, aby gra mogła łączyć się wyłącznie za pomocą identyfikatora agenta. Skopiuj identyfikator agenta. W przypadku agentów wymagających uwierzytelniania zobacz [Agenci publiczni i prywatni](#public-and-private-agents). #### Zainstaluj SDK Zainstaluj pakiet z adresu git URL zgodnie z opisem w sekcji [Instalacja](#installation). #### Dodaj skrypt rozmowy Utwórz `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` zwraca wynik po otwarciu połączenia i przygotowaniu urządzeń audio. `EndSession` jest idempotentne, więc wywołanie go z `OnDestroy` jest bezpieczne, nawet jeśli sesja już się zakończyła. #### Uruchom scenę Utwórz pusty GameObject, dodaj komponent `AgentConversation` i wklej identyfikator agenta w polu **Agent Id**. Wejdź w Play Mode i zezwól na dostęp do mikrofonu, jeśli poprosi o to system operacyjny. Agent wypowie pierwszą wiadomość, a transkrypcja pojawi się w Console. ## Agenci publiczni i prywatni #### Agenci publiczni Przekaż identyfikator agenta bezpośrednio. Każdy, kto ma ten identyfikator, może rozpocząć rozmowę z agentem. ```csharp var conversation = await Conversation.StartSessionAsync( new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" } ); ``` #### Agenci prywatni Agenci z włączonym uwierzytelnianiem potrzebują krótkotrwałych poświadczeń wydanych przez twój serwer. Pobierz [podpisany adres URL](/docs/pl/eleven-agents/customization/authentication) z backendu i przekaż go jako `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() } ); ``` W przypadku sesji WebRTC w WebGL przekaż token rozmowy jako `ConversationToken` i ustaw `ConnectionType = ConnectionType.WebRTC`. > **Warning** > > Nigdy nie umieszczaj klucza API ElevenLabs w wersji gry. Generuj podpisane adresy URL i tokeny rozmów na serwerze, który kontrolujesz. 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`: ```csharp [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](/docs/pl/eleven-agents/customization/personalization/dynamic-variables), aby wypełnić placeholdery w prompcie agenta i pierwszej wiadomości, oraz [nadpisań](/docs/pl/eleven-agents/customization/personalization/overrides), aby zastąpić części konfiguracji agenta w jednej sesji: ```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" }, }, }; ``` 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](/docs/pl/eleven-agents/customization/tools/client-tools) pozwalają agentowi uruchamiać działania w twojej grze. Zdefiniuj narzędzie w ustawieniach agenta, a potem zarejestruj handler o tej samej nazwie: ```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."; }); ``` 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`. 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 | Dane | Opis | | ------------------------- | ---------------------- | ----------------------------------------------------------------------------------------- | | `Disconnected` | `DisconnectionDetails` | Sesja została zakończona. `Reason` to `User`, `Agent` lub `Error`. | | `ErrorOccurred` | `string` | Po rozpoczęciu sesji wystąpił błąd. | | `StatusChanged` | `Status` | Status połączenia się zmienił. | | `ModeChanged` | `Mode` | Agent przełączył się między `Speaking` a `Listening`. | | `UserTranscriptReceived` | `UserTranscriptArgs` | Gotowa transkrypcja mowy gracza. | | `AgentResponded` | `AgentResponseArgs` | Tekst odpowiedzi agenta. | | `Interrupted` | `InterruptionArgs` | Gracz przerwał agentowi. | | `AgentToolRequested` | `AgentToolRequestArgs` | Agent rozpoczął wywołanie narzędzia. `AgentToolResponded` jest wywoływane po zakończeniu. | | `UnhandledClientToolCall` | `ClientToolCallArgs` | Agent wywołał narzędzie klienta bez zarejestrowanego handlera. | | `CanSendFeedbackChanged` | `bool` | Opinie stały się dostępne lub niedostępne dla ostatniej odpowiedzi agenta. | 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](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) zawiera pełną listę zdarzeń. ## Metody | Metoda | Opis | | ------------------------------------------------------------- | ------------------------------------------------------------------------ | | `EndSession()` | Zamknij połączenie i zwolnij urządzenia audio. | | `SendUserMessage(string text)` | Wyślij wiadomość tekstową, jakby gracz ją wypowiedział. | | `SendContextualUpdate(string text)` | Udostępnij agentowi stan gry bez przerywania rozmowy. | | `SendUserActivity()` | Zasygnalizuj aktywność gracza, aby agent zachował swoją turę. | | `SendFeedback(bool like)` | Oceń ostatnią odpowiedź agenta, gdy `CanSendFeedback` ma wartość `true`. | | `SetMicMuted(bool isMuted)` | Wycisz lub włącz mikrofon. | | `SetVolume(float volume)` | Ustaw głośność odtwarzania agenta od 0 do 1. | | `GetInputVolume()`, `GetOutputVolume()` | Odczytaj bieżący poziom mikrofonu lub dźwięku agenta od 0 do 1. | | `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | Wypełnij bufor bajtów danymi częstotliwości dla wizualizatorów audio. | | `UploadFileAsync()`, `SendMultimodalMessage()` | Prześlij plik i dołącz go do wiadomości użytkownika. | | `ChangeInputDevice()`, `ChangeOutputDevice()` | Zmień mikrofon lub urządzenie wyjściowe podczas sesji. | Na przykład wyślij agentowi bieżącą lokalizację gracza, gdy wejdzie on do nowego obszaru: ```csharp 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()`. > **Note** > > Play Mode w edytorze nie jest jeszcze obsługiwany, gdy aktywnym celem kompilacji jest WebGL. Przełącz się na > desktopowy cel kompilacji, aby testować w edytorze. Pełną macierz zgodności WebGL znajdziesz w pliku [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/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](https://github.com/elevenlabs/unity/issues).