Core concepts

The vocabulary used across the SDK, the dashboard and the API, on one page.

Term	Meaning
Organisation	The billing and membership boundary. Members sign in to the dashboard with an email code.
Project	One product or customer app. Has its own agents, tools, components, triggers, secrets, keys and end users. Switch between projects from the top of the dashboard rail.
Environment	`development` or `production` inside a project. Each has its own publishable and secret API keys and its own published agent versions.
Agent	A configured assistant: persona, model, tools, knowledge, workflow, UI allowlist, behaviour. Edited as a draft, published as versions.
Version	An immutable snapshot of an agent’s configuration, published to an environment with a note. Rollback re-publishes an older version.
End user	A person using your app. Anonymous by default (a stable `anon_…` id), or signed in when your backend issues a host JWT.
Session	A short-lived credential the SDK obtains with the publishable key. Carries the end user, environment and agent.
Conversation	An ordered log of events between one end user and one agent. Backed by a Durable Object. A user may have several.
Event	A `kletso.events/v1` envelope with a type, a sequence number and a payload, for example `message.delta`, `ui.render`, `app.notify`.
Surface	A `kletso.ui/v1` document: a tree of components the agent asked the app to render inside the chat.
Component (block)	A typed node in a surface, such as `card`, `form`, `map` or your own `acme.productCard`. Built-in blocks ship with the SDK; custom blocks are registered by your app and synced to the dashboard.
Action	What happens when the user interacts with a component: `local` (your app handles it), `agent` (sent to the model), `submit` (form), `confirm` (approve a tool), `url`, `workflow`.
Tool	An HTTP endpoint the model may call, described with a JSON-schema for its arguments. Can require confirmation and can act as the signed-in user. Built-in tools handle UI, notifications, app commands and handoff.
Trigger (rule)	A rule that matches silent app events (`track`, `screen`) and reacts with a notification, a prepared chat turn or a workflow.
Notification	An `app.notify` event: banner, toast, alert, OS system notification or silent. Delivered live over the socket, or by push when the user is offline.
Workflow	A directed graph of steps (tool calls, conditions, model steps, notifications) built visually and run by the runtime.
Handoff	Escalation to a human: the assistant marks the conversation and stops answering until it is handed back.
Publishable key	`kl_pub_…`, safe to ship in an app. Only opens sessions.
Secret key	`kl_sec_…`, server side only. Sends notifications to users and calls the management endpoints.

How the pieces relate

Organisation ─┬─ Members
              └─ Project ─┬─ Environments (development, production) ─ API keys
                          ├─ Agents ─ Versions (published per environment)
                          ├─ Tools · Components · Triggers · Workflows · Secrets
                          └─ End users ─ Conversations ─ Events

Read on: Agents and versions, Surfaces and components, Tools, Triggers and notifications, Users, sessions and identity.