Skip to content

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.

01Platform componentsTechnical overview
FrontendWeb interface
User sessions
BackendAPI and workers
APIAgents & business logicPublic 8000 · Internal 8010
RAG-IngestorExtraction & segmentation
RAG-EmbedEmbeddings & indexing
SchedulerBackground tasks
ModelsChat
Embeddings
Project resources
PostgreSQLData & vector indexes
SeaweedFSDocumentsInternal on VMs
Frontend sessions
Dependencies between components

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 Certificates 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.

02Usage, agents and governanceSoftware and functional view
UsersChat & create
Third-party appsCall an agent
AdministratorsGovern & monitor
Usage & creation
ChatMarketplaceStudio
Application integration
SmartAGT APIService accounts

Authenticated agent calls

Governance & oversight
Access & policiesCatalogsQuotasAudit & monitoring
SmartAGT agentsInstructions · Knowledge · Memory · Connectors
SmartAGTFunctions and resources by permission
AI modelsPrivate or provider-hosted
Business toolsActions through connectors
Actors, functions and connected resources

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.
SmartAGT AI GatewayOptional service

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.