Core concepts

Six nouns carry almost everything you build on Saaya: agent, knowledge base, channel, session, prompt version, and deployment. Get these right and the rest of the platform is just configuration.

Agents

An agent is the unit of behaviour. It bundles a prompt (or a conversation flow), an LLM choice, a voice, optional knowledge bases, and a set of tools. Agents live inside an organization and never leak across workspaces, every API call is scoped by an `X-Organization-Id` header.

Saaya supports two shapes today: single-prompt agents (one system prompt, freeform conversation) and conversation-flow agents (a state machine with branches and fallbacks). You can start with single-prompt and graduate to a flow without losing history.

Knowledge bases

A knowledge base is a versioned, indexed corpus the agent can ground answers in. You upload PDFs, HTML, Markdown, or structured JSON; Saaya chunks, embeds, and stores vectors in a Qdrant collection prefixed `kb_`. At runtime the agent retrieves the most relevant passages and either cites them inline or escalates if confidence is low.

Channels

A channel is the surface the conversation runs on: voice (SIP / Twilio), video (WebRTC over LiveKit), WhatsApp Business API, or web chat. One agent can be attached to many channels, the prompt is the same, but Saaya adapts turn-taking, tool availability, and TTS output per surface.

Sessions

A session is a single conversation. It has an id, a transcript, a sentiment timeline, tool-call records, latency breakdowns, and (on voice / video) a media recording. Sessions are append-only, you observe, replay, and export them, but you do not edit them.

const session = await saaya.sessions.get("ses_8f1c…");

console.log(session.transcript);          // [{ role, text, ts }]
console.log(session.toolCalls);           // recorded function calls
console.log(session.latency.p50TtsMs);    // first-byte TTS latency

Prompt versions

Every change to an agent, prompt edit, voice swap, tool change, creates a new version. Versions are draft until you publish them. Two versions can run side-by-side via A/B routing, and a bad release can be reverted with a single `agents.rollback` call.

Deployments

A deployment binds a published agent version to a real-world surface, a phone number, a chat widget origin, a WhatsApp sender. Saaya routes inbound traffic on that surface to the bound version. Cold-start config is cached in Redis with a 30-minute TTL, so the worker boots in under a second.