--- title: AI Agents Overview feature: true featureGroup: ai featureState: beta --- 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](../ai/overview.md) 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](#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. ### 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. ## Related - [AI Features](../ai/overview.md) — Enable or disable AI for your project and understand how AI features are gated per project.