Agentic Gathering Host

A speaking AI companion that joins Sponic Agentic Gatherings as the host's wing-friend — listens, replies in the speaker's language, and runs the conversational glue. Production now uses LiveKit Agents + Gemini Live native audio, orchestrated by the self-hosted Phoenix worker.

What it is & what it does

The Agentic Gathering Host is a real-time voice agent designed to sit at the head of a Sponic Gardens gathering and play the role of warm, curious, slightly playful host. It joins a LiveKit room, receives participant audio, sends it through Gemini Live native audio, and publishes spoken responses back into the same room. Optional Simli renders the host as a live avatar on the venue display.

It is not a generic assistant. The persona is constrained to the Agentic Gathering register: 1–2 sentence replies, no medical/legal/financial advice, no politics or religion unless the table clearly invites it, no pretending to eat or drink.

The active production worker is apps/ai-host/agent.py on Oracle Phoenix, registered as the named LiveKit worker sponic-dinner-host. The historical dev task still documents how the stack evolved, but current cost/model planning should use Gemini Live.

How it works (Phase 1 architecture)

┌──────────────────────────────────────────────────────────────────┐
│                       LiveKit Cloud (SFU)                         │
│       wss://sponic-XXXX.livekit.cloud  ·  WebRTC transport        │
└──────┬──────────────────────────────────────────────┬─────────────┘
       │  guest mic audio                              │  agent voice
       ▼                                               │
┌──────────────────────┐                               │
│  Browser / phone     │  (LiveKit Playground for       │
│  in the LiveKit room │   testing; later a venue tab    │
│                      │   or a Sponic intranet page)    │
└──────────────────────┘                               │
                                                       │
                                          ┌────────────▼──────────────┐
                                          │  Python agent worker       │
                                          │  apps/ai-host/agent.py     │
                                          │                            │
                                          │  Gemini Live native audio  │  speech ↔ speech
                                          │  gemini-3.1-flash-live-    │  RealtimeModel
                                          │  preview · voice "Puck"    │
                                          │      │                     │
                                          │      ├─ transcript capture │  for Supabase
                                          │      │                     │
                                          │      └─ optional Simli     │  avatar track
                                          └────────────────────────────┘

The agent worker is a long-lived Python process that registers with LiveKit Cloud as a named worker and gets dispatched into a room when one is created. It attaches an AgentSession backed by Gemini Live native audio. The session handles speech input, reasoning, and spoken output in one realtime model call; the worker captures transcript metadata for Supabase and can attach a Simli avatar session that subscribes to the generated audio.

Component choices & why

File map

First-time setup

Do this once per machine. After it's done, you never repeat any of these steps — the day-to-day workflow in the next section is just a single command.

Step 1 — Install runtime

You need Python 3.12 and uv (the package manager). On macOS:

# Python 3.12
pyenv install 3.12          # if you use pyenv (recommended)
# or: brew install [email protected]

# uv (manages venv + lockfile)
brew install uv             # macOS
# Linux/Ubuntu: curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
python3 --version           # → Python 3.12.x
uv --version                # → uv 0.x.y

Step 2 — Provision four service accounts

Sign up for four services and grab keys from each. Save every credential to the Bitwarden collection DevOps-sponicgarden (in the ALPU.CA org — it's a collection, not a personal folder; bw create item requires organizationId + collectionIds). The project never reads keys from .env alone — BW is the source of truth.

BW items already provisioned as of 2026-05-06:

• LiveKit Cloud — BW item 64d75f73-474a-4312-89e4-b442015302d8
• Google AI (Gemini) — BW item c4b16931-335b-457a-9910-b416006d3b8c ("Google Gemini — SponicGardens") (key is in login.password, not in custom fields)

Step 3 — Install dependencies

cd apps/ai-host
uv sync          # creates .venv/, installs livekit-agents 1.x + all plugins
                 # takes ~30 s on a warm cache, ~3 min from scratch

Step 4 — Configure .env

cp .env.example .env
# Open .env in your editor and paste these from the BW items above:
#   LIVEKIT_URL=wss://sponic-XXXX.livekit.cloud
#   LIVEKIT_API_KEY=API...
#   LIVEKIT_API_SECRET=...
#   GOOGLE_AI_API_KEY=AIza...
#   GEMINI_MODEL=gemini-3.1-flash-live-preview
#   GEMINI_VOICE=Puck

Step 5 — First-run smoke test

Confirm the install worked without going near a microphone:

cd apps/ai-host
uv run python -c "from persona import DINNER_HOST_PROMPT, build_prompt; print(f'Persona loaded: {len(build_prompt())} chars')"
# → Persona loaded: 1234 chars

uv run python -c "import ast; ast.parse(open('agent.py').read()); print('agent.py syntax OK')"
# → agent.py syntax OK

If both lines succeed, you're set up. Move to Normal operation.

Normal operation (day-to-day)

Once setup is done, every working session collapses to this:

Start the agent

cd apps/ai-host
uv run python agent.py dev

You should see:

[INFO] connecting to wss://sponic-XXXX.livekit.cloud
[INFO] registered worker: dinner-host-1
[INFO] waiting for room dispatch...

The dev subcommand runs in foreground with hot-reload on file changes — edit persona.py and the worker restarts itself. Use this for everything except production.

The worker is now idle, waiting for someone to join a LiveKit room. It costs nothing while idle (no API calls, no tokens).

Test in the LiveKit Playground

The official Playground is the day-to-day way to talk to your agent — no client code, just a browser tab.

Stopping

Just Ctrl-C the uv run terminal. There's no state to clean up — the worker is stateless between rooms.

Iterating on the persona

Edit apps/ai-host/persona.py while the worker runs in dev mode. The worker auto-reloads. Reconnect from the Playground (or refresh the page) to test the new prompt — existing rooms keep the old persona until you reconnect.

Updating dependencies

cd apps/ai-host
uv sync --upgrade        # pull latest livekit-agents, plugins, etc.
uv run python -c "from livekit.agents import Agent; print('still works')"

Testing checklist

When validating a build (yours or after a pull), check these in order. They're listed cheapest-to-most-expensive in time, so a failure at any step short-circuits the rest.

Static checks (no creds, no mic)

• uv run python -c "import ast; ast.parse(open('agent.py').read())" — syntax
• uv run python -c "import ast; ast.parse(open('persona.py').read())" — syntax
• uv run python -c "from persona import DINNER_HOST_PROMPT, build_prompt" — imports + exports

Live checks (Playground)

• Connection: worker logs registered worker within ~3 s of starting
• Dispatch: worker logs agent joined room within ~1 s of clicking Connect in Playground
• Greeting plays: hearing the smoke-test sentence proves LiveKit + Gemini Live are wired
• Latency is acceptable on a short reply. Higher? Check Google AI Studio status and the Phoenix worker logs.
• Multilingual works: Polish in → Polish out. Spanish in → Spanish out. If everything comes back English, the persona prompt got mangled.
• Tone is right: 1–2 sentence replies, warm/curious. If it's lecturing, tighten persona.py.
• No crashes through 20+ consecutive turns. Memory should stay flat.

Production operation (deploy targets, monitoring)

Everything above assumes you're running locally during dev. To leave the agent running for an Agentic Gathering (or for hands-off staging), you need a host that stays up.

Phase 1 only needs a way to keep one Python worker process running — no public ingress, no DNS, no scaling story. Three reasonable hosts depending on stage:

Production-ish run (Phoenix)

Once the agent is stable enough to leave running:

# On Phoenix:
sudo apt install -y python3.12 python3.12-venv     # 22.04 needs the deadsnakes PPA
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone <repo> ~/sponic         # or scp the apps/ai-host subdir
cd ~/sponic/apps/ai-host
uv sync
cp .env.example .env && nano .env                  # paste creds

# systemd unit (mirror the pattern from prompt-runner.service):
sudo nano /etc/systemd/system/sponic-ai-host.service
# [Service]
# WorkingDirectory=/home/ubuntu/sponic/apps/ai-host
# ExecStart=/home/ubuntu/.local/bin/uv run python agent.py start
# Restart=always
# EnvironmentFile=/home/ubuntu/sponic/apps/ai-host/.env

sudo systemctl daemon-reload
sudo systemctl enable --now sponic-ai-host
sudo journalctl -fu sponic-ai-host                  # tail logs

Monitoring

• LiveKit Cloud dashboard — rooms, participants, connection minutes used. cloud.livekit.io
• Google AI Studio dashboard — Gemini Live usage and quota. Same key as live translation, so usage is shared. aistudio.google.com
• Simli dashboard — avatar session minutes, if avatar display is enabled.
• journalctl if running under systemd. Worker logs to stdout.

Cost

Current production costs are session-based: Gemini Live for the host, LiveKit participant minutes for connected clients, and optional Simli avatar minutes.

Assumptions: Gemini Live $0.005/min audio input + $0.018/min audio output, LiveKit WebRTC $0.0005/participant-min, Simli $0.30/min, and one extra display participant when Simli is enabled. The Phoenix worker is self-hosted, so LiveKit-hosted agent-session minutes are not included.

Troubleshooting

Phase 1 vs the long roadmap

This document tracks the active Gemini Live implementation. The older 8-phase plan remains useful as history, but its cascade model/cost estimates are superseded by this page and the Phoenix runbook.