Assistant basics

Assistant is the bot-facing API. It combines your name, prompt, greeting, preparation, and tools with one reviewed VAANI profile.

For a small library-only bot:

from vaani import Assistant, BASIC_MONOLINGUAL


assistant = Assistant(
    name="Reception",
    preset=BASIC_MONOLINGUAL,
    prompt="Help the caller briefly. Ask one question at a time.",
    greeting="Hello. How can I help?",
)

The Starter pins vaani==1.0.0rc43 and uses the environment-bound form:

from vaani import Assistant, bootstrap_environment


environment = bootstrap_environment()
assistant = Assistant(
    name="Reception",
    prompt="Help the caller briefly.",
    greeting="Hello. How can I help?",
    environment=environment,
)

Resolve the environment once at backend or worker startup. Set VAANI_ENVIRONMENT to exactly development or production; the core API does not infer a default.

Add caller preparation and tools

from vaani import Call


@assistant.prepare
async def prepare_call(call: Call) -> object:
    return {"caller": call.caller, "customer_id": "safe-test-id"}


@assistant.tool
async def account_status(call: Call) -> str:
    """Return the verified customer's current account status."""

    return await accounts.status(call.state["customer_id"])

Preparation runs once before the greeting. It normally returns immutable call state, which tools use to perform authorized business work. It can instead return a typed terminal outcome when the call must end or transfer without starting greeting, STT, LLM, conversational TTS, tools, or Judge work:

from vaani import (
    EndRequest,
    EndRequestSource,
    TerminalMedia,
    TerminalOutcome,
)


not_eligible = assistant.add_prerecorded_audio(
    "not-eligible",
    load_not_eligible_audio_frames,
)


@assistant.prepare
async def prepare_call(call: Call) -> object:
    customer = await customers.find(call.caller)
    if customer is None:
        return TerminalOutcome(
            action=EndRequest(
                EndRequestSource.ASSISTANT_PREPARATION,
                "caller is not eligible",
            ),
            media=TerminalMedia(
                prerecorded_audio=not_eligible,
                tts_fallback="I cannot continue this call.",
            ),
        )
    return {"customer_id": customer.id}

The prerecorded source must be registered before the Assistant freezes and return a non-empty tuple of output audio frames. VAANI tries the configured TTS text only if that source or playout fails. TerminalOutcome also accepts an optional no-argument side_effect; its finite timeout defaults to five seconds and cannot exceed 30 seconds. Timeout or failure is retained as evidence and never starts the conversation.

See prompts, caller data, and tools for dynamic wording, error results, destructive-tool safety, silence handling, named prompts, languages, transfer, and ending.

Check before running

assistant.check() validates the complete definition before it reaches a provider. The generated command is:

./scripts/check

After a successful check or call start, the Assistant is frozen. Register all prompts, business tools, transfer routes, prerecorded terminal media, Judge configuration, tool disables, and startup choices first.

When a reviewed preset enables optional or required recording, pass its approved deployment-owned Adapter as recording= before checking. A disabled preset accepts no recording Adapter. See recording and GCS for consent, storage, lock, and result boundaries.

The generated worker passes only the Assistant to VAANI. Your bot imports no LiveKit SDK type and constructs no provider client. VAANI handles worker registration, audio, STT/LLM/TTS, transcripts, turn taking, ending, and cleanup.

Next: configure environments.