Concepts
The ideas behind Baseera: organizations, agents, versions, knowledge, tools, approvals, sessions, tokens, keys and evals.
Organizations
An organization is your workspace. Agents, provider keys, knowledge, tests, members and the audit log all belong to it. There are four roles: owner, admin, developer and viewer. Owners and admins manage provider keys, keys and publishing, developers edit drafts, knowledge and tests, and viewers have limited read-only access.
Agents
An agent is one assistant. It has a system prompt, a model (chosen from one of your provider keys), a tone, the modes it supports, the knowledge it uses, and a theme for how the chat looks in your app. You can run several agents in one organization, for example one per product area.
Versions: draft and production
Saving an agent writes a draft. Publishing turns the draft into a new, immutable version, and that version becomes production. The runtime serves production only. A turn that is already running finishes on the version it started with.
Creating an agent publishes version 1 immediately, so you can chat with it right away. Only later edits go to the draft. Owners and admins publish, and can roll back to an earlier version in one step.
Knowledge
A knowledge base is a set of documents the agent reads and cites. Add sources by uploading files, crawling a website, or pushing items from your server with a server token. Baseera parses, splits and embeds them with the knowledge base's own provider key. Search combines meaning and text, and each agent can use up to 10 knowledge bases.
- Search mode. The agent either decides when to search (
tool), or every turn searches first (auto). - Tenants. A source can belong to one of your customers (a tenant) or be shared by all. A user never sees another tenant's documents.
- Access rules. A source can require a role or a claim from the user token. A user without it never sees the document or learns it exists.
- Citations. Answers mark sources as
[S1]. Users see the title and section, and can open the original only if you allow it.
Tools
A tool is a function in your app that the agent may call. You define it with useBaseeraTool, with a name, a description, a Zod schema and a kind:
| Kind | Behavior |
|---|---|
read | Runs at once. The user is not asked. |
draft | Waits for the user to approve. |
write | Waits for the user to approve. |
Tools run in your app with the user's own session. Baseera lists the tools it has seen on the Tools page and never stores or runs them.
Approvals
An approval is the user's decision on a draft or write call. The SDK shows a card with a sentence you wrote (describe) and the call's values, with Approve and Reject. Only an approved call runs. A rejection, with an optional reason, goes back to the model as the result.
Sessions
A session is one conversation between one user and one agent. It records the agent, the version it started on, and the user id, tenant id and locale from the token. Names and roles from the token are used per turn and never stored. Session ids start with ses_. In the dashboard, a session shows every turn, tool call, approval and timing.
User tokens
A user token tells Baseera who the user is and which tenant they belong to. Your server signs it with signUserToken from @baseera/node, using a secret key. It is a short-lived EdDSA token: 15 minutes by default, at most one hour. Other algorithms are refused.
Keys
| Key | Prefix | Use |
|---|---|---|
| Publishable | pk_ | Identifies the agent in the browser. Works only from allowed domains. |
| Secret | sk_ | Signs user tokens and server calls. Server only. Shown once. |
| Provider | none | Your model key (Anthropic, OpenAI, Google, OpenRouter). Stored encrypted, never shown again. |
Evals
Evals are your tests. A test case is a saved conversation turn with the tool results mocked, so it replays the same way each time. Checks are typed and deterministic, for example "this tool was called", "approval was required" or "the reply is in Arabic". A model judge with rubrics can grade what rules cannot. Owners and admins can require suites to reach a pass rate before a draft publishes.
Immersive mode
Besides chat, an agent can work on one record the user is editing, such as an invoice form. It flags problems, proposes field values the user approves in place, and can block a finish until blocking flags are fixed or overridden. Each finish is recorded with a single-use receipt your server can verify, and every step is kept as a per-record trail. It is optional and can be on together with chat. See Immersive mode.