Smart Agent Setup
This is the one-time configuration page for Smart Agents.
Merged manual: This file covers two tightly coupled pages — the main setup card and the Default Tier Images fact box that is embedded in it.
Smart Agent Setup (main card)
Page type: Card Source table:
Smart Agent SetupObject:Page 72778304 "Smart Agents Setup QUA"—Page.72778304.SmartAgentsSetup.al
This is the one-time configuration page for Smart Agents. It shows the tenant registration status, billing information, model preferences, global instructions, and — for administrators — diagnostic and email integration settings.
In plain terms
Think of this page as the Company Information card for Smart Agents — you fill it in once when you first install the app, and it sets the rules every agent in this company will inherit.
Two concepts here may be unfamiliar if you are new to AI:
Provisioning / registering the tenant. Before any agent can work, Smart Agents must introduce your Business Central company to the QUALIA backend — the external service that actually runs the AI models. "Registering" is that handshake. It is like activating an AppSource extension with a license key: nothing works until it is done, and you only do it once. The Register Tenant action handles this automatically via Single Sign-On.
The backend. Smart Agents does not run AI models inside Business Central itself. It calls a QUALIA-hosted service (the "backend") that hosts the models and manages credits. You can think of it as an external web service BC connects to — similar to a currency-rate service or a document-capture service — except this one powers your agents' intelligence.
Default AI Model / Default tier. Every new agent you create needs a brain — an AI model. The Default AI Model here is like the default posting group on the Customer Posting Group setup: it is the tier automatically assigned when you create an agent unless you deliberately choose a different one on the Agent Card. See AI Models for the full list of available tiers and their costs.
Credits threshold. The Low Credit Warning field works like a reorder-point on an item card — when your credit balance falls below this number, the app warns you before you run out completely.
Worked example. You install Smart Agents in the CRONUS company, click Register Tenant, and the Tenant Registered indicator turns green. You set Default AI Model to Smart (a mid-range tier) so all new agents start at a reasonable cost/quality balance. You set Low Credit Warning to 100 so you get a heads-up before the balance hits zero. After that you rarely need to return here unless you add email integration or change the global rules.
How to open it
- Role Center Smart Agents group → Setup.
- Tell Me (Alt+Q) → search "Smart Agent Setup".
Fields
Getting Started
| Field | Type | Description |
|---|---|---|
| Tenant Registered | Boolean | Whether this tenant has been registered with the QUALIA backend. Read-only. |
| Setup Complete | Boolean | Whether the guided setup wizard has been completed. Read-only. |
| Last Balance Sync | DateTime | When the credit balance was last synchronized. Read-only. |
Billing
| Field | Type | Description |
|---|---|---|
| Billing Mode | Enum | Prepaid = buy credits via Stripe before using. Subscription = usage billed through Microsoft AppSource SaaS offer. Values: Prepaid (Stripe), Subscription (Microsoft). |
Prepaid Credits (shown only in Prepaid mode)
| Field | Type | Description |
|---|---|---|
| Credits Available | Decimal | Your current credit balance. Buy more credits via Stripe to top up. Read-only. |
Microsoft Subscription (shown only in Subscription mode)
| Field | Type | Description |
|---|---|---|
| Subscription Status | Text | The status of your Microsoft SaaS subscription (Active, Suspended, etc.). Read-only. |
| Usage This Month | Decimal | Total credit usage reported to Microsoft for the current billing period. Read-only. |
| Last Billing Sync | DateTime | When billing information was last synchronized with the backend. Read-only. |
Preferences
| Field | Type | Description |
|---|---|---|
| Default AI Model | Text | The default AI model assigned to newly created agents. |
| Low Credit Warning | Decimal | Show a warning when credits fall below this number. |
| Show Usage in Chat | Boolean | Show the token count and credits consumed under each agent reply in the chat window. Turn off to hide these usage details. |
| Response Language | Text | The language all agents should respond in. Injected into system prompt automatically. Leave blank to not enforce a language. |
| Planning Model | Text | The AI model used for initial planning on the first message of a conversation. When set, this model creates the goal and plan before the agent's own model takes over for execution. Leave blank to skip the planning step. |
Global Instructions
| Field | Type | Description |
|---|---|---|
| Global Instructions (rich text editor) | Rich text | Company-level instructions that ALL agents must follow. These form the second layer of the instruction hierarchy (System > Global > Agent). Use headings, bullets, and bold to structure your rules clearly. |
| Validate Agent Instructions | Boolean | When enabled, activating or updating an agent checks its instructions against the system and Global Instructions. Turn off to skip this comparison. |
Connection Context
This group is visible in non-production environments only.
| Field | Type | Description |
|---|---|---|
| BC Environment | Text | The current Business Central environment. Agents created here are tagged with this environment name. Read-only. |
| BC Company | Text | The current Business Central company. Each company has its own agent setup and configuration. Read-only. |
| Tenant Key | Text | The backend tenant key for this environment/company. Assigned during registration. Read-only (masked). |
On-Prem Authentication
This group is visible only when the deployment mode is configured for an on-premises backend.
| Field | Type | Description |
|---|---|---|
| Backend Base URL | Text | The on-prem Smart Agents backend base URL (e.g. https://smartagents.contoso.local). |
| API Key Configured | Boolean | Indicates whether an on-prem API key is currently stored in secure storage. Read-only. |
Administration
This group is visible to administrators in non-production environments only.
| Field | Type | Description |
|---|---|---|
| Show Advanced Options | Boolean | Show advanced diagnostic information to all users. |
| Backend Base URL | Text | The QUALIA backend API base URL. |
| Backend Environment | Text | The active backend environment (e.g. Production, Sandbox). Determines which backend data scope is used. Use the lookup to see available environments. |
Email Integration (Microsoft Graph)
Azure AD App Registration
| Field | Type | Description |
|---|---|---|
| Azure AD Tenant ID | Text | Your Microsoft 365 tenant directory ID (GUID). Find it in Azure Portal > Azure Active Directory > Overview. |
| App Client ID | Text | The Application (client) ID from your Azure AD app registration. |
| App Client Secret | Text (masked) | The client secret from your Azure AD app registration. Stored securely in isolated storage. |
Email Polling
| Field | Type | Description |
|---|---|---|
| Job Queue Status | Text | Whether the email polling Job Queue Entry is active. Read-only. |
Default Tier Images (fact box)
Page type: CardPart Source table:
Smart Agent SetupObject:Page 72778310 "SA Setup Tier Images QUA"—Page.72778310.SASetupTierImages.al
This fact box appears on the right side of the Smart Agent Setup page. It lets you upload and manage the default avatar images that are automatically assigned to new agents based on their AI tier.
In plain terms
This is purely cosmetic housekeeping. When you create a new agent and assign it a model tier — Fast, Smart, Expert, or Premium — the app automatically gives it the matching avatar image you upload here. It works like the default logo on a document layout: set it once centrally and every new record inherits it. You can always change an individual agent's image on its own Agent Card later.
Fast
| Field | Type | Description |
|---|---|---|
| Fast Tier Image | Media | Default image for Fast tier agents. |
Smart
| Field | Type | Description |
|---|---|---|
| Smart Tier Image | Media | Default image for Smart tier agents. |
Expert
| Field | Type | Description |
|---|---|---|
| Expert Tier Image | Media | Default image for Expert tier agents. |
Premium
| Field | Type | Description |
|---|---|---|
| Premium Tier Image | Media | Default image for Premium tier agents. |
Actions
Smart Agent Setup actions
| Action | What it does |
|---|---|
| Save Global Instructions | Validate and save the Global Instructions. All active agents will be updated on the backend with the new composed instructions. Only enabled when you have made unsaved changes. |
| Register Tenant | Register or re-verify this tenant with the Smart Agents backend using Single Sign-On. |
| Tool Configurations | Open the list of agent tool configurations (API pages and web services). |
| My Dashboard | Open your tenant dashboard to view agents, credits, chat history, and more. |
| Reset to Defaults | Restore default settings (Global Instructions, preferences, built-in agent). Only fills in values that are currently empty — never overwrites your customizations. |
| Download Diagnostic Report | Download a diagnostic text file with the current status of Smart Agents configuration, backend connectivity, agents, and credits. |
| Set OAuth Credentials | Manually enter the publisher OAuth2 Client ID and Client Secret. Required for dev extensions where App Key Vault is not available. |
| Set API Key | Enter or replace the on-prem Smart Agents API key. Stored securely in isolated storage. (Visible in on-prem mode only.) |
| Clear API Key | Remove the stored on-prem API key. Backend calls will fail until a new key is set. (Visible in on-prem mode only.) |
| Setup Email Job Queue | Create or update the recurring Job Queue Entry that polls email-enabled agents for incoming messages. |
| Process Emails Now | Immediately poll all email-enabled agents for new emails and process them. Use this to test without waiting for the job queue schedule. |
| Test Graph Connection | Verify that the Azure AD credentials allow Smart Agents to connect to Microsoft Graph API and access the configured mailboxes. |
| Email Log | View all emails processed by Smart Agents. |
| Remove Email Job Queue | Remove the email polling Job Queue Entry. Email integration will stop working. |
| Backend Administration | Open the Smart Agents admin dashboard. |
| Test Key Vault | Test whether the App Key Vault Secret Provider can be initialized. Key Vault only works for Marketplace (AppSource) apps — not for dev or per-tenant extensions. |
| Test $metadata Discovery | Calls BC OData V4 $metadata endpoint and lists discovered bound actions. For development testing only. |
| View AI Models | Open the cached AI model list. Use Update on the page to refresh all available models from the backend. |
Default Tier Images actions
| Action | What it does |
|---|---|
| Import Fast | Upload a default image for Fast tier agents. |
| Import Smart | Upload a default image for Smart tier agents. |
| Import Expert | Upload a default image for Expert tier agents. |
| Import Premium | Upload a default image for Premium tier agents. |
| Clear All | Remove all tier images. |
Related pages
Notes
- The Tenant Registered and Setup Complete indicators are colour-coded: green when true, red when false.
- The Billing Mode field is read-only on the setup record; it is set by the backend when you register.
- The Global Instructions editor is a rich text (formatted) field. Use the Save Global Instructions action to commit your changes — the button is only enabled once you have made an edit.
- Saving Global Instructions triggers an update on every active agent in the backend. If any agent's instructions conflict, you will be prompted to confirm before proceeding.
- Default Tier Images are PNG/JPG files uploaded here and copied automatically when a new agent is created with the matching AI tier. Supported formats: PNG, JPG, JPEG, BMP.
- Several actions (diagnostic tools, email integration, backend administration) are hidden in production environments and are intended for administrators during setup and troubleshooting.