Agents Overview

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

They need two things present: app.auth (agents are stored as auth users) and AI_PROVIDER (they need a model).

app.yaml

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 materialised at runtime as an auth.user row with type: 'agent' and a synthetic address ({name}@agents.sovrium.local). This is not bookkeeping — it is the whole security design.

The agent inherits every table and field permission of its role, exactly as a human would. There is no separate AI permission system to keep in sync, and no way for an agent to exceed a role you have already reasoned about.
Agents cannot authenticate. No login endpoint accepts them: not email and password, not magic link, not OTP. The identity exists to be authorised, never to be logged into.
Agent actions appear in the activity log with actor.type = 'agent', so an audit reads uniformly across humans and machines.
Agent users are excluded from the user list unless you pass ?includeAgents=true.

The records are managed for you: created on first startup, updated when the role changes, soft-deleted when the agent leaves the config.

Give an agent its own role, not a human one. Reusing member means every capability you later grant members, you have also silently granted the agent. A dedicated role — support-bot, analyst-bot — keeps the blast radius reviewable and makes the permission diff meaningful when it changes.

Definition Properties

The identity fields sit at the top level of each entry.

Property	Description
`name`	Unique kebab-case identifier (`support-agent`). Lowercase letters, digits, single hyphens.
`role`	The auth role the agent operates as. Must exist in `auth.roles`.
`systemPrompt`	Required. Defines the agent's personality, remit and rules.
`instructions`	Optional array, appended to the system prompt as numbered rules.
`model`	Model override. Defaults to `AI_MODEL`.
`temperature`	Override between `0` and `1` inclusive. Defaults to `AI_TEMPERATURE`.
`maxTokens`	Output-token override, a positive integer. Defaults to `AI_MAX_TOKENS`.
`enabled`	Defaults to `true`. A disabled agent skips scheduled runs and cannot execute.

systemPrompt and instructions divide cleanly in practice: the prompt says who the agent is, and each instruction is one rule you would otherwise have buried in a paragraph. Rules stated as separate numbered lines are followed more reliably, and they diff better in review.

Tools & Double-Gate Security

Moved to Tools — the tools allowlist, the available actions, and the two gates every call passes.

Permissions: Who Can Invoke the Agent

Moved to Permissions & Approval — the permissions block and its trigger rule.

Human-in-the-Loop Approval

Moved to Permissions & Approval — approval modes, timeouts and escalation.

Scheduled Execution

Moved to Scheduling & Limits — cron expressions, timezones and task prompts.

Operational Limits

Moved to Scheduling & Limits — action, token and concurrency caps.

Memory, Knowledge, and MCP

Three further blocks compose onto an agent:

Block	Purpose	Docs
`memory`	Conversation history and persistent learned facts.	AI Memory
`knowledge`	Tables and documents embedded as the agent's RAG base.	AI RAG
`mcp`	External MCP tools the agent may invoke.	Client Mode

Multi-Agent & Invocation

An agent can be reached from the AI chat component, over the API at POST /api/agents/{name}/chat, on its own schedule, and from an automation through the ai:agent action.

Because each agent is a distinct virtual user with its own role and allowlist, several can coexist at different privilege levels — a read-only analyst beside a write-capable triage agent — without either inheriting the other's reach.

Full Example

app.yaml

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.

Read it as a security statement rather than a feature list: this agent can read two tables and nothing else, writes nothing, needs no approval because it cannot cause harm, and wakes once a day.

Tools — the capability allowlist and its double gate.
Permissions & Approval — who invokes, and what waits.
Scheduling & Limits — cron and resource caps.
AI Providers — the model defaults agents inherit.
AI Chat — embedding an agent as a panel.
Roles & RBAC — the permissions an agent inherits.

Last updated August 11, 2026

← PreviousAI Chat Next →Tools

Edit this page Report an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.