Skip to content

Documentation / Getting started / Quickstart

Build your first offline voicebot

This credential-free example is a complete call through public APIs. The participant asks for help, the scripted reasoning route invokes the bot's end_call tool, and VAANI publishes one terminal result.

The current quickstart is intentionally explicit: it teaches the runtime contract, not a turnkey live worker. VAANI 1.0 does not bundle a high-level LiveKit worker bridge that turns one prompt into a deployed telephone bot.

Run it

After installing VAANI:

python examples/minimal_offline.py

Expected output includes:

outcome=COMPLETED
closed_events=1
end_reason=quickstart_complete
open_resources=0

The executable source is examples/minimal_offline.py in the source repository. It is designated offline: its provider behavior is a deterministic script and does not prove a real provider or telephone call.

What the example assembles

  1. The consumer defines a prompt and end_call tool.
  2. Three profile values choose a fake STT, reasoning, and TTS route.
  3. A LanguageBinding joins the language-specific instructions, profile, and tools.
  4. CallSetup combines those choices with lifecycle and business policies.
  5. RuntimeTestKit creates a runtime with deterministic time and identifiers.
  6. VoiceRuntime.run() owns the call until it returns one CallResult.

The essential handoff is:

result = await kit.runtime(price_book=price_book).run(
    kit.invocation(telephony=telephony, consumer_state=business_state),
    setup,
)

business_state remains consumer-owned. The tool receives it through VoiceToolContext.consumer_state; VAANI does not define its schema.

Change the bot, not VAANI

Try these edits in the example:

  • replace PROMPT to change behavior;
  • change the RuntimeTool handler to call your domain service;
  • change profile route_id, model/profile IDs, language, or voice;
  • change the printed fields or build a web frontend around the returned result.

None requires an edit to src/vaani.

Move toward a real call

Keep the same CallSetup, then replace the test composition:

  • use LiveKitTransportAdapter for an already-routed LiveKit call;
  • use public provider factories where available;
  • inject explicit credential sources and scopes;
  • run credentialed validation separately from offline tests.

If you want a generated project instead of wiring those layers by hand, the privately published create-vaani-app==0.1.2 companion Starter CLI supplies consumer-owned LiveKit worker, bridge, backend, and frontend scaffolding. Version 0.1.3 is in progress; the credentialed live path is not tested.

Next: use the companion Starter CLI, organize a consumer project by hand, or read the example line by line.