Architecture

This page describes the internal architecture of the Smart Agents BC extension, including the key components, data flow, and extensibility points.

High-Level Architecture

The Smart Agents extension consists of three main layers:

1. UI Layer — Pages and page extensions that provide the chat interface and administration screens
2. Business Logic Layer — Codeunits that handle agent selection, message processing, data scoping, and API communication
3. Data Layer — Tables that store agent configurations, conversation history, user registrations, and usage records

Component Diagram

Business Central Client
    |
    v
+---------------------------+
|  Smart Agents UI Layer    |
|  - Chat Page              |
|  - Agent Setup Page       |
|  - Template Library Page  |
|  - Administration Pages   |
+---------------------------+
    |
    v
+---------------------------+
|  Business Logic Layer     |
|  - Agent Router Codeunit  |
|  - Data Scope Manager     |
|  - API Client Codeunit    |
|  - Credit Tracker         |
|  - Auth Manager           |
+---------------------------+
    |             |
    v             v
+----------+ +------------------+
| Data     | | Smart Agents API |
| Layer    | | (External)       |
| (Tables) | | api.smart-agents |
+----------+ +------------------+

Key Codeunits

SA Agent Router

The Agent Router is the central orchestrator. When a user sends a message, the router:

1. Identifies the selected agent and its configuration
2. Resolves the data scope for the current user
3. Collects relevant Business Central data based on the query
4. Sends the query and data context to the Smart Agents API
5. Receives the response and formats it for display

The Agent Router publishes events at each step, allowing extensions to intercept and modify behavior.

SA Data Scope Manager

The Data Scope Manager determines which Business Central data an agent can access for a given user. It combines:

• The agent's configured data scope (table allowlist)
• The user's Business Central permissions
• Any administrative data access policies
• Custom data scope extensions registered by third-party apps

SA API Client

The API Client handles all HTTP communication with the Smart Agents API. It manages:

• Authentication (API key retrieval from setup or Azure Key Vault)
• Request construction and serialization
• Response deserialization and error handling
• Retry logic with exponential backoff

SA Credit Tracker

The Credit Tracker records credit consumption for each query and enforces user-level credit limits. It fires events when credits are consumed, allowing extensions to implement custom billing logic.

SA Auth Manager

The Auth Manager handles user authentication and session management. It verifies that the current BC user is registered with Smart Agents and manages token lifecycle.

Key Tables

Key Pages

Data Flow: Processing a Query

The following describes the complete data flow when a user sends a message:

1. User input — The user types a message in the SA Chat page and clicks Send
2. Agent resolution — The Agent Router loads the selected agent's configuration from the SA Agent table
3. Data scope resolution — The Data Scope Manager computes the effective data scope by intersecting the agent scope, user permissions, and data access policies
4. Data collection — The Agent Router queries Business Central tables within the resolved scope to gather context data relevant to the user's question
5. API request — The API Client sends the message, data context, and agent configuration to the Smart Agents API
6. API response — The Smart Agents API returns the AI-generated response
7. Credit recording — The Credit Tracker records the credit cost in the SA Credit Ledger Entry table
8. Response display — The response is formatted and displayed in the SA Chat page
9. Persistence — The message and response are saved to the SA Conversation and SA Message tables

Extensibility Points

The architecture provides extensibility at each stage of the data flow:

• Before data collection — Add custom data sources or modify the data scope
• Before API request — Modify the request payload or add custom headers
• After API response — Process or transform the response before display
• On credit consumption — Implement custom billing or usage tracking
• On agent selection — Override agent routing logic

See Extending Agents for details on implementing extensions at each point.

Security Model

The extension follows a defense-in-depth security approach:

1. BC Permissions — The user must have BC permissions to access data. The extension does not bypass BC security
2. Data Access Policies — Additional restrictions can be applied at the table and field level
3. API Authentication — All API communication uses TLS and bearer token authentication
4. Credential Storage — API keys are stored in the SA Setup table (encrypted) or Azure Key Vault
5. Audit Trail — Every query and data access event is logged