Skip to main content

Getting Started

Set up the Estuary Unity SDK and run your first AI conversation in under 10 minutes.

Prerequisites​

RequirementDetails
Unity2022.3 LTS or newer (2021.3 minimum)
Estuary AccountSign up at app.estuary-ai.com
API KeyGenerated from your Estuary dashboard (est_... format)
Character IDUUID of the AI character you want to use

Installation​

The SDK is distributed as a Unity Package Manager (UPM) package.

Via Git URL​

Unity Package Manager does not resolve transitive Git URL dependencies, so you must add the LiveKit SDK before adding the Estuary SDK.

  1. Open your Unity project
  2. Go to Window > Package Manager
  3. Click the + button > Add package from git URL...
  4. Add the LiveKit SDK first:
https://github.com/livekit/client-sdk-unity.git#v1.3.3
  1. Click Add, then click + > Add package from git URL... again
  2. Add the Estuary SDK:
https://github.com/estuary-ai/estuary-unity-sdk.git
  1. Click Add

Dependencies​

The following dependencies are installed automatically by UPM:

PackageVersionPurpose
com.unity.nuget.newtonsoft-json3.2.1JSON serialization
com.unity.textmeshpro3.0.6Text rendering (for samples)

The following dependency must be installed manually (see step 4 above):

PackageVersionPurpose
io.livekit.livekit-sdk1.3.3WebRTC voice and video (required)

Auto-installer fallback: If you forget to add LiveKit first, the SDK includes an Editor script that detects the missing dependency on domain reload and offers a one-click install dialog. Adding LiveKit manually before the Estuary SDK (as shown above) is still the recommended approach.

Scene Setup​

1. Create the EstuaryConfig Asset​

  1. In the Project panel, right-click > Create > Estuary > Config
  2. Name it EstuaryConfig
  3. Select the asset and fill in the Inspector:
FieldValue
Server Urlhttps://api.estuary-ai.com (or your self-hosted URL)
Api KeyYour est_... API key
Voice ModeLiveKit (recommended) or WebSocket

2. Add EstuaryManager​

  1. Create an empty GameObject in your scene, name it EstuaryManager
  2. Add the Estuary Manager component (Add Component > Estuary > Estuary Manager)
  3. Drag your EstuaryConfig asset into the Config field

The manager is a singleton that persists across scene loads. It coordinates the connection and routes events to characters.

3. Add EstuaryCharacter​

  1. Select the GameObject that represents your AI character (or create a new one)
  2. Add the Estuary Character component
  3. Configure the fields:
FieldValue
Character IdYour character's UUID from the dashboard
Player IdA unique ID for the end user (or leave blank for auto-generated)
Auto Connecttrue to connect when the scene starts
Auto Start Voice Sessiontrue if you want voice immediately

Quick Test: Send Text​

Create a test script to send a text message and see the response in the console:

using UnityEngine;
using Estuary;
using Estuary.Models;

public class QuickTest : MonoBehaviour
{
    private EstuaryCharacter _character;

    void Start()
    {
        _character = GetComponent<EstuaryCharacter>();

        // Listen for responses
        _character.OnBotResponse += HandleResponse;
        _character.OnConnected += HandleConnected;
    }

    void HandleConnected(SessionInfo session)
    {
        Debug.Log($"Connected! Session: {session.SessionId}");

        // Send a test message (text-only, no voice)
        _character.SendText("Hello! Tell me a fun fact.", textOnly: true);
    }

    void HandleResponse(BotResponse response)
    {
        if (response.IsFinal)
        {
            Debug.Log($"Character said: {response.Text}");
        }
    }
}

Attach this script to the same GameObject as your EstuaryCharacter, press Play, and watch the Console for the response.

Adding Voice​

To enable voice conversations, add the audio components:

EstuaryAudioSource (TTS Playback)​

  1. On your character GameObject, add Estuary Audio Source (Add Component > Estuary > Estuary Audio Source)
  2. An AudioSource component is added automatically
  3. Drag the EstuaryAudioSource into the character's Audio Source field

EstuaryMicrophone (STT Input)​

  1. On the same or a separate GameObject, add Estuary Microphone
  2. Drag your EstuaryCharacter into the Target Character field
  3. Drag the EstuaryMicrophone into the character's Microphone field

Enable Auto-Start Voice​

On the EstuaryCharacter component, check Auto Start Voice Session. This will:

  1. Connect to the server
  2. In LiveKit mode: request a token, join the WebRTC room, and start native mic capture with AEC
  3. In WebSocket mode: start Unity microphone capture and stream audio

Verify It Works​

Press Play. You should see console logs like:

[EstuaryManager] EstuaryManager initialized
[EstuaryCharacter] Connected: SessionInfo(SessionId=sid_abc, ...)
[EstuaryCharacter] Voice session started for <character-id>
[EstuaryMicrophone] LiveKit microphone active (AEC enabled)

Speak into your microphone and listen for the AI character's response through your speakers.

Next Steps​

Last updated