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
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​

The Estuary SDK works for text-only chat without any extra packages. To enable voice, add the optional LiveKit Unity SDK.

  1. Open your Unity project
  2. Go to Window > Package Manager
  3. Click the + button > Add package from git URL...
  4. Add the Estuary SDK:
https://github.com/estuary-ai/estuary-unity-sdk.git
  1. Click Add.
  2. (Optional, for voice) Add the LiveKit Unity SDK:
https://github.com/livekit/client-sdk-unity.git#v2.1.0

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 is optional -- only required for WebRTC voice:

PackageVersionPurpose
io.livekit.livekit-sdk2.1.0+WebRTC voice (optional)

If your project already has an older LiveKit version, update its Git URL in Package Manager to the v2.1.0 tag above.

Auto-installer: On the first domain reload after adding the Estuary SDK, an Editor script (EstuaryDependencyInstaller) checks whether the LiveKit Unity SDK is installed and shows a dialog offering a one-click install. The script uses Unity's SessionState so it only runs once per Editor session. You can decline -- the SDK still compiles and works for text-only chat. Without LiveKit, the optional Estuary.LiveKit assembly is skipped (gated by the ESTUARY_LIVEKIT define), and EstuaryManager.IsLiveKitEnabled will be false.

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.", 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