AI Agents

An agent is an autonomous AI actor that operates as a virtual user inside your app. Each agent binds to an auth role, is restricted to an explicit allowlist of tables and actions, and can be gated by human approval, run on a schedule, and bounded by operational limits. Agents are declared under the top-level app.agents[] array.

Agents require app.auth to be configured (they are stored as auth users) and AI_PROVIDER to be set.

agents:
  - name: support-agent
    role: support
    systemPrompt: You are a courteous support assistant. Resolve tickets accurately.
    tools:
      tables: [tickets, customers]
      actions: [record.read, record.update, email.send]
    approval:
      mode: selective
      required: [email.send]
    limits:
      maxActionsPerMinute: 20
      maxTokensPerDay: 100000

Agent-as-User Model

Each agent is materialized at runtime as an auth.user record with type: 'agent' and a synthetic email ({name}@agents.sovrium.local). This is the foundation of agent security:

The agent inherits every table and field permission of its assigned role, exactly like a human user.
Agents cannot authenticate via any login endpoint (email/password, magic link, OTP).
Agent actions appear in the activity log with actor.type = 'agent'.
Agent users are excluded from the user list by default, and included only when ?includeAgents=true is passed.

Agent user records are managed automatically: created on first startup, updated when the role changes, and soft-deleted when the agent is removed from config.

Definition Properties

The core identity fields are inlined at the top level of each agent entry.

Property	Description
`name`	Unique kebab-case identifier (e.g. `support-agent`). Lowercase letters, digits, single hyphens.
`role`	Auth role the agent operates as. Must reference a role in `auth.roles`.
`systemPrompt`	System prompt defining the agent's personality, role, and rules.
`instructions`	Optional array of behavioral instructions, appended as numbered rules to the system prompt.
`model`	LLM model override (defaults to `AI_MODEL`).
`temperature`	Temperature override, `0`–`1` inclusive (defaults to `AI_TEMPERATURE`).
`maxTokens`	Max output tokens override (defaults to `AI_MAX_TOKENS`).
`enabled`	Whether the agent can execute. Defaults to `true`. Disabled agents skip scheduled runs.

Tools & Double-Gate Security

The tools block is the agent's capability allowlist. Sovrium enforces a double-gate security model — both gates must pass:

RBAC gate — does the agent's role have permission for this table/action?
Allowlist gate — is this table/action listed in the agent's tools?

An agent with no tools has no access (secure by default).

Property	Description
`tools.tables`	Table names the agent can access (at least one; must exist in `tables`).
`tools.actions`	Action types the agent can perform (at least one; see below).

Available Actions

Actions follow the type.operator pattern used by the automation engine.

Category	Actions
Record	`record.read`, `record.create`, `record.update`, `record.delete`
State	`state.get`, `state.set`, `state.increment`, `state.delete`, `state.list` (cross-run KV)
HTTP	`http.request`
AI	`ai.generate`, `ai.classify`, `ai.extract` (chain LLM sub-tasks)
Code	`code.runTypescript` (sandboxed)
Email	`email.send`
Auth	`auth.createUser`, `auth.assignRole`, `auth.banUser`, `auth.unbanUser`
File	`file.upload`, `file.download`, `file.delete`, `file.list`, `file.getMetadata`

Permissions: Who Can Invoke the Agent

The optional permissions block describes the agent's RBAC integration and who may trigger it.

Property	Description
`permissions.type`	User-type discriminator — always `agent`.
`permissions.trigger`	Who may invoke this agent: `all`, `authenticated`, or a role array like `[admin, member]`.
`permissions.emailDomain`	Domain for the synthetic agent email (defaults to `agents.sovrium.local`).

Human-in-the-Loop Approval

The approval block gates agent actions behind human review.

Property	Description
`approval.mode`	`none` (execute immediately), `all` (every action needs approval), or `selective`.
`approval.required`	Actions requiring approval (a subset of `tools.actions`). Required when `mode: selective`.
`approval.timeout`	Seconds before a pending approval expires (default `3600`).
`approval.escalation`	Escalation when an approval stays pending — `{ after: <seconds>, to: <role> }`.

approval:
  mode: selective
  required: [record.delete, email.send]
  timeout: 1800
  escalation:
    after: 600
    to: admin

Escalation after must be less than timeout. An approval that is not actioned within after seconds escalates to the to role; if still unactioned by timeout, it expires.

Scheduled Execution

The schedule block makes an agent run automatically at a cron interval. The taskPrompt is sent to the LLM as the user message on each run.

Property	Description
`schedule.cron`	Standard 5-field cron expression (e.g. `/15 * * `, `0 9 * MON`).
`schedule.timezone`	IANA timezone identifier (defaults to `UTC`).
`schedule.taskPrompt`	Prompt sent to the LLM on each scheduled execution.

schedule:
  cron: '0 9 * * MON'
  timezone: Europe/Paris
  taskPrompt: Summarize last week's new tickets and post the digest.

Scheduled runs respect enabled (disabled agents skip them) and approval (e.g. mode: all pauses the scheduled run for human sign-off).

Operational Limits

The limits block caps resource consumption to prevent runaway agents. All fields are optional and fall back to system defaults.

Property	Default	Description
`limits.maxActionsPerMinute`	`30`	Maximum DB/email actions per minute.
`limits.maxTokensPerDay`	`200000`	Maximum LLM tokens per 24h. Resets at midnight UTC.
`limits.maxConcurrentTasks`	`5`	Maximum simultaneous task executions.

Memory, Knowledge, and MCP

Agents compose with three further capabilities, each documented in its own page:

Block	Purpose	Docs
`memory`	Conversation history, RAG knowledge retrieval, and persistent learned facts.	AI Memory
`knowledge`	Tables and documents to embed as the agent's RAG knowledge base.	AI RAG
`mcp`	Allowlist of external MCP tools the agent may invoke.	MCP Integration

Multi-Agent & Invocation

Agents can be invoked from the AI chat interface (a named ai-chat component), via API, on a schedule, and from automations through the ai:agent action. Because each agent is a distinct virtual user with its own role and tool allowlist, multiple agents can coexist with different privilege boundaries — a read-only analyst agent and a write-capable triage agent, for example.

Full Example

agents:
  - name: data-analyst
    role: analyst
    systemPrompt: You are an expert data analyst. Be precise and cite the records you used.
    instructions:
      - Never expose customer PII in summaries.
      - Prefer aggregates over row-level dumps.
    tools:
      tables: [orders, customers]
      actions: [record.read]
    approval:
      mode: none
    limits:
      maxActionsPerMinute: 20
      maxTokensPerDay: 150000
    schedule:
      cron: '0 7 * * *'
      timezone: UTC
      taskPrompt: Produce the daily orders summary.

AI Overview — the full AI ecosystem.
AI Providers — model, temperature, and token defaults agents inherit.
AI Chat — embed an agent as a conversational panel.
AI Memory — agent conversation, knowledge, and facts.
AI RAG — knowledge sources agents embed.
MCP Integration — agents as MCP clients.
AI Actions — the ai:agent automation action and AI action vocabulary.
Roles & RBAC — the role permissions agents inherit.

← PreviousAI Chat Next →AI RAG