Concepts
Core ideas behind the Liforma platform.
The mental model
Experience
↓
Session Manifest
↓
SDK You configure an Experience. Each launch receives a Session Manifest. The SDK runs the session.
You integrate at the Experience level — not at tokens, HTTP routes, or player endpoints.
Experience
An Experience is your reusable product configuration, identified by exp_…. It
defines who appears, how they behave, and what they can do.
- Characters — who appears (agent + avatar + voice)
- World — rules and context for the session
- Location — where the scene takes place
- State — structured facts that update during the session
- Tools — controlled capabilities the character can invoke
Session
A Session is one live runtime instance — one user opening your experience, one conversation, one playthrough. Sessions are short-lived and scoped.
Session Manifest
When a session starts, the API returns a Session Manifest: JSON that tells the SDK how to run this launch — characters, transport, assets, integration rules, and a session token.
Most developers never inspect the manifest. The SDK consumes it automatically. See Session Manifests.
Character
A Character is an entity inside an experience — the combination of conversational agent, visual avatar, and voice. A simple tutor has one character; richer experiences can have several.
Transport
Transport is how the SDK connects to the Liforma runtime. It is declared in the manifest and hidden from integrators. You never configure HTTP routes, WebSockets, or LiveKit rooms.
Public vs authenticated
| Mode | When | Backend required? |
|---|---|---|
| Public experience | Embeds on allowlisted origins | No |
| Authenticated experience | Private apps, per-user sessions, API-key billing | Yes — your server mints the manifest |
Tool
A Tool is a controlled external capability — look up a score, advance a quest, fetch account data. Tools are declared on the experience and invoked by the character. Your app observes results via events and state updates, not by calling tool HTTP endpoints directly.
Event
Events are the SDK's way of reporting what happened — new messages, mode changes (listening /
speaking), state updates, and character lifecycle. Subscribe with experience.on(…).
See Listen to Events.
IDs are public
Experience IDs (exp_…) are public identifiers, like YouTube video IDs. Security
comes from origin allowlists, session tokens, quotas, and API keys — not ID secrecy.