Architecture
SmartAGT combines a web application, an API and document processing with data and model services. These two views explain their responsibilities. The PoC and project pages show how to place these components on your infrastructure.
Technical architecture
The Frontend service serves the web interface. The Backend runs the business API and three distinct
workers (rag-ingestor, rag-embed and scheduler). The scheduler handles
RAG indexes, the Microsoft Entra ID directory and email delivery. On VMs, SeaweedFS is internal storage managed by SmartAGT, PostgreSQL holds application
data, vector indexes and storage metadata. Models are connected according to the
resources selected for the project. S3 is required in containers.
User sessions
EmbeddingsProject resources
The Backend groups four processes. Their placement depends on the scenario. Every network connection uses TLS, including local connections and storage.
The Frontend reaches the API through the Internal listener, with mutual TLS under a SmartAGT authority. External API clients use the Public listener, AI applications the Gateway listener. Your certificates serve the user entry point, the Public listener and Gateway, never the internal link.
Roles and dependencies
| Component | Role | Main dependencies |
|---|---|---|
| Frontend service | Serve the web interface and relay requests | Backend API Internal listener, PostgreSQL session database |
| Backend API | Run business functions and agents; serve the Public and Internal listeners | PostgreSQL, documents, models and connectors depending on the request |
| AI Gateway | Expose authorized models to external tools using dedicated keys, on the Gateway listener | Platform PostgreSQL, model providers, no HTTP calls to Platform or Frontend service |
| RAG-Ingestor | Extract and segment documents | PostgreSQL, document storage |
| RAG-Embed | Generate embeddings and populate indexes | PostgreSQL, embedding model, vector index |
| Scheduler | Maintain indexes, synchronize the Entra directory and deliver email | PostgreSQL, Microsoft Graph, storage and mail transport according to the task |
| SeaweedFS | Store document files | Persistent volumes, metadata in the Backend PostgreSQL database in managed mode |
| PostgreSQL | Store data, sessions, indexes and processing state | Database service with pgvector for vector indexes |
Workers coordinate their work through state persisted in PostgreSQL. They do not form a chain of HTTP calls to one another. Launch commands are provided in the Operations page.
Delivery and data
| Resource | Contents or responsibility |
|---|---|
| Backend package | Platform API, three workers, optional AI Gateway and bundled dependencies |
| Frontend service package | Web interface, session management and Backend access |
smartagt database |
Application data, processing state and managed SeaweedFS metadata |
smartagt_vector database |
Vector indexes with pgvector |
smartagt_bff database |
Web sessions |
| Document storage | SeaweedFS volumes or S3 bucket, files used by the platform |
The packages and evaluation licence are supplied privately. The public documentation provides installation procedures. In the PoC, chat and embedding models run on remote services, the VM does not host their inference runtime.
Storage
On single or multiple VMs, SeaweedFS is internal and managed by Platform. Workers connect to the same storage. Provide the persistent volumes and resources. SmartAGT manages SeaweedFS configuration and internal certificates.
In containers, S3 is required. A VM project can also use an S3 service. Storage explains these choices, the project path describes their placement.
Every client verifies its server certificate. The Security page explains these rules, the flow matrix lists the connections.
Software architecture
Users interact with agents, authorized creators configure them, and third-party applications can call them through the SmartAGT API. Administration brings together governance functions. Available functions and resources depend on permissions and platform configuration.
Authenticated agent calls
The API receives requests from third-party applications. Connectors let agents call business tools. These are two distinct directions of integration.
Functional journeys
- Users and creators: chat, discover agents in the Marketplace and use them according to their permissions, configure agents in the Studio when authorized.
- Third-party applications: obtain a token with a service account, then call an authorized agent through the SmartAGT API, with a complete or streamed response.
- Administrators: manage identities, access, catalogs and policies, monitor usage, quotas and logs according to assigned permissions.
- Agents: use the instructions, document knowledge, memory, models and tools configured for their purpose.
A separate HTTP process connects external tools to models through Chat Completions, using JSON or SSE. SmartAGT governs keys, catalogs and policies, tools execute their own functions. Workspace works without this service, which does not replace the agent-call API.
See Enable AI Gateway and its flows. The same Backend artifact contains Platform and Gateway, each process opens its own resources.