Skip to content

Architecture

The rule is simple: business behavior belongs to the bot; reusable voice behavior belongs to VAANI.

flowchart LR CALLER["Caller"] <--> LK["LiveKit / SIP"] LK <--> VAANI["VAANI<br/>media, streaming, turns,<br/>providers, transcripts"] VAANI <--> BOT["Bot<br/>prompt, state, tools"] VAANI --> RESULT["CallResult"]

Text equivalent: the caller exchanges audio with LiveKit/SIP; VAANI connects that media to the bot's prompts, state, and tools, then produces one result.

VAANI owns the live path

For an accepted LiveKit job, VAANI:

  1. reads normalized caller and call metadata;
  2. runs the bot's preparation hook, then selects its terminal or conversational path;
  3. subscribes to participant audio and applies the preset's noise/VAD policy;
  4. streams speech through STT, the reasoning model, and TTS;
  5. publishes assistant audio and live transcripts;
  6. handles interruptions, deadlines, standard tools, and cleanup;
  7. returns one immutable CallResult.

When preparation returns a TerminalOutcome, VAANI waits for the primary participant, plays the approved prerecorded media (or its configured TTS fallback), runs any bounded consumer side effect, and deterministically ends or transfers. Greeting, STT, LLM, ordinary tools, conversational prompting, and Judge execution are never started on that path. Lifecycle deadlines, teardown, usage accounting, and exactly-once result publication still apply.

Provider clients, LiveKit media streams, turn buffers, and transcript publishing stay inside VAANI. A bot should not recreate them.

The bot owns business meaning

The bot supplies:

  • the assistant name, greeting, and prompt;
  • customer/API lookup through @assistant.prepare;
  • business actions through @assistant.tool;
  • credential values and named transfer destinations;
  • telephony provisioning, frontend, deployment, and business reporting.

Presets make shared improvements reusable

A preset is one reviewed operational configuration. It selects providers, models, voices, languages, VAD, endpointing, noise cancellation, streaming behavior, fallbacks, Judge, metrics, deadlines, and standard tools.

If all bots need improved endpointing or noise cancellation, change the VAANI implementation or preset once. Consumer applications receive the change by upgrading their pinned VAANI version and reviewed production lock.

If only one bot needs a different prompt or customer API, change that bot.

Telephony remains deployment-owned

VAANI runs inside an already-routed LiveKit job. The deployment still owns phone numbers, trunks, carrier credentials, SIP routing, LiveKit dispatch, and transfer destinations. VAANI owns the shared worker and media behavior after the job is accepted.

Next: presets and configuration.