AI Agents Overview - Business Platform Documentation

AI Agents are configurable conversational assistants that can be embedded into your project's backoffice and end-user applications. Each agent is powered by a large language model (LLM) and can be equipped with tools, a custom persona, and specific access permissions.

What Are AI Agents?

AI Agents allow you to create purpose-built chat assistants tailored to your project's workflows. Common use cases include:

Answering questions about your project's data
Guiding users through complex processes
Summarizing content or generating structured output
Automating routine tasks via configured tools

AI Agents are only available when AI is enabled for your project. See AI Features to enable AI for your project.

Accessing AI Agents

Navigate to Settings → AI Agents within your project to manage agents.

Creating an Agent

Click New Agent to open the creation form. The following fields are available:

Basic Configuration

Field	Required	Description
Name	Yes	Display name shown to users in the chat interface and FAB button tooltip.
Avatar URL	No	URL to an image used as the agent's avatar. If omitted, a default robot icon is shown.
Context	Yes	System prompt that defines the agent's behavior, knowledge scope, and tone.
LLM	Yes	The language model powering the agent (e.g., `mistral/ministral-3b`).
Chat Permission	Yes	Controls which users are allowed to chat with this agent. See Chat Permissions below.
Show as FAB in Backoffice	No	When enabled, the agent appears as a floating action button in the backoffice interface.

Chat Permissions

The Chat Permission field is a required string that determines who can initiate a conversation with the agent. It maps to a permission identifier in your project's access control system.

Accepted values:

Empty string ("") — No additional restriction is applied beyond project membership. Any authenticated project member can chat with the agent.
A specific permission identifier — Only users who hold the named permission are allowed to start a conversation. For example, setting this to "admin" or a custom role key restricts the agent to users with that role or permission assigned.

When to restrict access:

Use an empty string for general-purpose agents intended for all project members or end users.
Use a specific permission identifier for agents that have access to sensitive tools, internal data, or capabilities that should only be available to staff or privileged users.
In end-user applications, agents that the current user does not have permission to access will not be shown at all.

Note: The chatPermission field is required when creating or updating an agent. Omitting it will cause a validation error. If you do not need to restrict access, explicitly set it to an empty string.

Characteristics

Characteristics define the agent's personality and communication style across several categories (e.g., tone, verbosity, formality). Only one characteristic per category can be active at a time. Selecting a new characteristic in a category automatically deselects the previous one.

Tools

Tools extend the agent's capabilities beyond conversation. Assign one or more tools to allow the agent to query data, trigger actions, or interact with external services.

Web & API sources

Two generic tools let an agent ground its answers in content from outside the database. You configure each with a URL and a short description that tells the model what the source contains and when to use it.

API endpoint (api-fetch) — fetches JSON or text from an HTTP(s) endpoint. The URL may be a public address (validated against an SSRF allow-list — private IPs, loopback and cloud-metadata hosts are rejected) or a same-origin internal path that starts with / (e.g. /api/store/modules), in which case the call runs with your session's permissions.
Web page (web-scrape) — fetches a public web page and stores it as clean, readable text (JS-rendered pages are supported).

Caching & refresh. Both tools are cache-based: the content is fetched only when you click Refresh (which first saves the agent), never during a chat. The agent always reads the most recently refreshed copy, so chats stay fast and the source site is not hit on every message. Each source shows when it was last refreshed; click Refresh to pull the latest content, and Show data to preview exactly what was cached (the content the agent will see).

This is a generic capability — point it at any of your own APIs or pages. For example, smallstack's own catalog is exposed at the public GET /api/store/modules (products) and GET /api/store/collections (solutions) endpoints, which an agent can read via an API-endpoint source.

Facts only (anti-hallucination)

Enable Facts only (anti-hallucination) to add a strict instruction to the agent's system prompt: it must answer only from real, verifiable information (its tools, the provided context and documents, and the conversation), never invent facts, names, numbers, or links, and say plainly when it does not have the information. Recommended for agents that answer factual questions about your data, products, or documentation.

Suggested Prompts

Provide a list of pre-written prompts that are surfaced to users at the start of a conversation. These help users discover what the agent can do.

The AI Agent FAB (Floating Action Button)

When Show as FAB in Backoffice is enabled, the agent appears as a circular floating button in the backoffice UI.

Opening an Agent

Clicking an agent's FAB button opens the agent's chat interface in the sidebar panel. The sidebar provides a persistent, non-blocking chat experience that stays open as you navigate within the backoffice.

Note: In earlier versions, clicking a FAB button opened an inline overlay positioned above the navigation bar. This has been replaced with the sidebar panel for a more integrated experience.

Multiple Agents

If more than one agent has the FAB enabled, each agent renders its own FAB button. The buttons are stacked vertically and labeled with the agent's name via a tooltip. Clicking any FAB opens that specific agent in the sidebar.

Editing an Agent

Click the edit icon on any agent in the list to open the edit form. All fields described above are available for modification, including the Chat Permission field.

Deleting an Agent

Click the delete icon on an agent and confirm the action to permanently remove it. This also removes the FAB button from the backoffice if it was enabled.

Agent Availability in Applications

In end-user applications (outside the backoffice), agents are surfaced based on the Chat Permission setting. The application layout fetches project-level details on load and makes agent availability and AI feature flags available throughout the session. Agents that the current user does not have permission to access will not be shown.

AI Features — Enable or disable AI for your project and understand how AI features are gated per project.