Overview

The Akumina AI Platform is a comprehensive, enterprise-grade AI platform built on .NET 10 with Microsoft Agent Framework. It provides multi-tenant support, intelligent agent orchestration, extensible plugin architecture, and a Model Context Protocol (MCP) gateway for integrating AI assistants.

 

Key Capabilities

Capability	Description
Multi-Tenant Architecture	Azure AD integration with complete tenant isolation
AI Agent Orchestration	Smart routing across Azure OpenAI, OpenAI, Azure AI Foundry, and Copilot Studio
Tools System	Extensible plugins for weather, document search, image generation, stock data, tools using REST API Configuration and more
Real-Time Chat	Streaming chat responses via Server-Sent Events (SSE) with full session management
Analytics & Reporting	Usage tracking, billing, and comprehensive reporting with 7-year compliance retention
MCP Gateway	Expose Akumina APIs as MCP tools for Claude, GitHub Copilot, and other AI assistants
Content Safety	Azure Content Safety integration for hate, self-harm, sexual, and violent categories
Enterprise Security	JWT bearer tokens, tenant validation, OBO token exchange, and secure API endpoints

 

Architecture Overview

System Components

The platform consists of four primary projects:

Project	Description
Akumina.Ai.Api	RESTful API with multi-tenant JWT authentication, agent orchestration, and plugin management
Akumina.Ai.Core	Shared business logic, agent factories, tools, telemetry, and data access services
Akumina.Ai.McpGateway	MCP server that exposes Akumina APIs as tools for AI assistants

 

Architecture Diagram

End-to-End System Architecture

 

 

Pre-requisites

The prerequisites pertain exclusively to self-hosted and single-tenant customers. JSON templates can serve as generic configuration elements for multi-tenancy, self-hosted, and single-tenant environments alike.

Requirement	Details
Operating System	Linux, Windows or Containers - AMD64
.NET 10 ; For IIS Install .NET Hosting (https://builds.dotnet.microsoft.com/dotnet/aspnetcore/Runtime/10.0.3/dotnet-hosting-10.0.3-win.exe)	Required for running Akumina.Ai.Api and Akumina.Ai.McpGateway
Azure Subscription	Required for Azure OpenAI, Cosmos DB, Azure AI Search, and other Azure services
Azure Active Directory	Configured tenant with application registration
Azure CLI	Required for infrastructure deployment scripts
AI Server binaries (.zip)	AI binary files (Self Hosted)
kv-template.json (https://akuminadownloads.blob.core.windows.net/interchange/ai/kv-template.json)	Azure Key Vault configuration template
ai-config-template.json (https://akuminadownloads.blob.core.windows.net/interchange/ai/ai-config-template.json)	API Server tenant configuration template
ai-mcp-config-template.json (https://akuminadownloads.blob.core.windows.net/interchange/ai/ai-mcp-config-template.json)	MCP Server configuration template
deploy-cosmos-db.ps1 (https://akuminadownloads.blob.core.windows.net/interchange/ai/deploy-cosmos-db.ps1)	PowerShell script for Cosmos DB setup

 

Configuring Key Vault Settings

Fill in all values in kv-template.json and store them in keyvault. For development or testing, copy these values directly into appsettings.json or appsettings.<ENV>.json. Refer to the following table for section details, or continue to the next section if not needed.

Application Insights

Setting	Description
ConnectionString	Full Application Insights connection string

 

Azure AI Search

Setting	Description
Endpoint	Search service URL
ApiKey	Admin or query key
DocumentIndexName	Index name for documents
PeopleIndexName	Index name for people
ApiVersion	API version (e.g., 2023-11-01)
DefaultTopResults	Default number of results to return
MaxTopResults	Maximum allowed results
DocumentIndexSemanticConfigName	Semantic configuration for document index
PeopleIndexSemanticConfigName	Semantic configuration for people index

 

Cache

Setting	Description
Enabled	Enable/disable caching (true/false)
Provider	"Redis" or "InMemory"
DefaultTtl	Default expiration (format: HH:MM:SS)
MaxCacheEntries	Max entries for InMemory provider
CleanupInterval	Cleanup interval for expired entries

 

Redis Sub-Settings:

Setting	Description
ConnectionString	Redis connection string
InstanceName	Key prefix for all Redis keys (e.g., AkuminaAI:)
ConnectTimeout	Connection timeout in milliseconds

 

SyncTimeout	Sync operation timeout in milliseconds
AbortOnConnectFail	Continue without caching if Redis fails (false recommended)
UseSsl	Enable SSL/TLS (true for Azure Redis, false for local)

 

Tenant Cache

Setting	Description
Enabled	Enable/disable tenant caching
CacheTtl	Tenant cache expiration (format: HH:MM:SS)
MaxCacheEntries	Maximum cached tenants
CacheAllActiveTenantsResult	Cache the full active tenants result set

 

Cosmos DB

Setting	Description
ConnectionString	Primary Cosmos DB connection string
DatabaseName	Database name (e.g., akcontainers)
SessionsContainerName	Container for chat sessions (default: chatsessions)
MessagesContainerName	Container for messages (default: chatmessages)
ReportsContainerName	Container for usage and billing (default: chatusage)
TenantsContainerName	Container for tenant config (default: settings)
SettingsEntityType	Prefix for tenant settings IDs (e.g., AKAI-)
MaxThroughput	RU/s throughput
DefaultMessageTtl	Message TTL in seconds (default: 31536000 = 1 year)
DefaultSessionTtl	Session TTL in seconds (default: 31536000 = 1 year)
DefaultReportTtl	Usage report TTL in seconds (default: 7776000 = 90 days)
BillingTtl	Billing record TTL in seconds (default: 220752000 = 7 years)
CreateIfNotExists	Auto-create containers on startup
PreferredRegion	Preferred Azure region
EnableDiagnostics	Enable Cosmos DB diagnostics

 

HTTP Client

Setting	Description
DefaultTimeoutSeconds	Default HTTP request timeout
LongRunningTimeoutSeconds	Timeout for long-running operations

 

Configuring Cosmos DB Container

Prerequisites:

· Azure CLI installed and authenticated (az login)

· Cosmos DB account and database already exist

· Appropriate Azure permissions to create containers

 

The platform uses existing AppManager configured CosmosDB server with the following database and containers:

The platform uses Azure Cosmos DB with the following database and containers:

· Database: akcontainers

· Partition Key: /PartitionKey (all containers)

Container Specifications

Container	Content	Default TTL	Partition Key Pattern
chatsessions	Chat session metadata	1 year (31,536,000s)	user_{userId}
chatmessages	Individual chat messages	1 year (31,536,000s)	session_{sessionId}
chatusage	Usage reports & billing records	90 days (7,776,000s)	reports_{reportType} / billing_{tenantId}

 

Container Script

Use the provided PowerShell script to automate Cosmos DB container creation:

.\deploy-cosmos-db.ps1 `
    -ResourceGroup "your-resource-group" `
    -CosmosAccountName "your-cosmos-account" `
    -DatabaseName "akcontainers" `
    -TenantId "your-tenant-id"

 

Parameters:

Parameter	Description	Default
ResourceGroup	Azure resource group name	rg-udai
Location	Azure region	East US 2
CosmosAccountName	Cosmos DB account name	cosmos-udaidemo
DatabaseName	Database name	akcontainers
TenantId	Azure AD tenant ID for sample config	—

 

The script performs:

1. Creates all four containers (inheriting database-level throughput)

2. Applies composite indexes to chatmessages:

· MessageIndex (ASC) + Timestamp (ASC) — chronological ordering

· Timestamp (DESC) + MessageIndex (DESC) — reverse chronological ordering

Configuring Akumina AI App Service

When utilizing Virtual Machines or Azure App Services, transfer the binary downloads to the webroot and confirm that your runtime is configured to support .NET 10. For containerized environments, deployment can be executed directly from the hub, if available. Please note: This step is only required if you are a self-hosted customer or a single tenancy customer. Multi-tenancy customers do not need to perform these steps.

 

Open the appsettings.json file and update the Key Vault Secret URI accordingly. If you did not create a Key Vault, insert the JSON content provided in the Key Vault Section into appsettings.json.

1. For App services add an Environment Variable KEYVAULT_URI and AZURE_CLIENT_ID; set the secret value that you created at Key Vault setup step

2. Update appsettings.json with

{

"KeyVault": {

"Uri": "https://kv-udaidemo1.vault.azure.net/secrets/ai",

"ManagedIdentityClientId": ""

}

}

3. Save the Environment settings or file

 

Configuring Agents and Settings

Prerequisites from Microsoft Foundry

To configure agents and settings, please access the Microsoft Azure Portal to create Microsoft Foundry. Once Foundry has been established, you may retrieve the necessary values from the provided ai-config-template.json file. It is essential to complete this step prior to proceeding further. Once Microsoft Foundry is provisioned, deploy a base model Azure OpenAI GPT-4.1 or later and text-embedding-3-large at a minimum.

 

Agents and Settings

Go to AppManager → Central Site → Settings → AI Settings to configure agents and settings. Use the JSON template ai-config-template.json to update values; after saving and reloading, the configured tools will appear. The template includes all supported agents, but you only need the generic agent and its configurations to start—many elements in the file are optional.

 

Copilot Studio Integration (Optional)

If you plean to use Microsoft Copilot Studio agents, additional configuration Is required.  Please note this also needs user to have copilot license, If you do not have copilot license this feature will fail.

 

Step 1: Enable Power Platform API

Run the following PowerShell commands to enable the Power Platform API service principal:

 

# Connect to Microsoft Graph
Connect-MgGraph

# Create the Power Platform API service principal
New-MgServicePrincipal -AppId "8578e004-a5c6-46e7-913e-12f58912df43"

Note: The AppId 8578e004-a5c6-46e7-913e-12f58912df43 is the well-known application ID for the Power Platform API.

 

Step 2: Add API Permission

1. Navigate to Azure Portal → Microsoft Entra ID → App registrations

2. Select your application

3. Go to API permissions → Add a permission

 

1. Select APIs my organization uses

2. Search for Power Platform API

3. Select Delegated permissions

4. Check CopilotStudio.Copilots.Invoke

5. Click Add permissions

6. Click Grant admin consent (if required by your organization)

 

Step 3: Get the DirectConnectUrl

1. Open Copilot Studio (https://copilotstudio.microsoft.com)

2. Select your copilot/agent

3. Go to Settings → Channels → Web app

4. Copy the Direct Connect URL

 

Step 4: Enable Power Platform API

In your ai-config-template.json, add or update the Copilot Studio agent configuration:

{
  "Id": "copilot-studio-agent",
  "Name": "Copilot Studio Agent",
  "Type": "CopilotStudio",
  "ConnectionSettings": {
    "DirectConnectUrl": "<YOUR_DIRECT_CONNECT_URL>"
  }
}

Important: Ensure AzureAd.ClientSecret is configured in your tenant settings for the OBO (On-Behalf-Of) token exchange to work.

 

Built-in Tools

You can integrate these optional built-in tools with AzureAI or OpenAI-based Akumina Agents. Since they connect to third-party APIs, you'll need accounts from those providers. These tools are built-in code solutions, but you can replace them or add your own tools to connect to any REST API. For setup, see the MCP REST API configuration section.

 

Parameter	Description	Default
Weather	Retrieve Current Weather Conditions. Obtain an API key from OpenWeatherMap.	Url: https://api.openweathermap.org/data/2.5
Stock	Retrieve stock price with ticker; obtain AlphaVantage key.	Url: https://www.alphavantage.co/query
BingGrounding	Searches online for up-to-date information. Builds a Microsoft Foundry Agent using Bing Grounding.	Include the BingGrounding Agent within the Agent section, and then configure BingGrounding to reference the designated Agent Name.
Email	Dispatches Email	Provide SMTP settings for supported providers.

 

MCP Server Configuration (Optional)

The MCP (Model Context Protocol) Server enables extensible tool integration for your AI agents.

Configure MCP Tools via REST API  (Optional)

In your tenant configuration (ai-config-template.json), add the MCP Gateway settings:

1. {
  "McpGateways": [
    {
      "Name": "default",
      "Enabled": true,
      "BaseUrl": "",
      "TimeoutSeconds": 30,
      "ForwardAuthorization": true
    }
  ]
}

2. After saving the main configuration, a secondary text box will appear

3. Open the ai-mcp-config-template.json file

4. Customize the tools for your requirements

5. Paste the configuration and save

 

Configure MCP Tools via Remote MCP Server  (Optional)

Add your MCP server under McpGateways, then save.

{
  "McpGateways": [
    {
      "Name": "default",
      "Enabled": true,
      "BaseUrl": "<Your MCP Server URL>",
      "TimeoutSeconds": 30,
      "ForwardAuthorization": true
    }
  ]
}

 

Troubleshooting

Check if <APPURL>/health returns 200, then look for additional errors.

Common Issues

 

Issue	Possible Cause	Resolution
401 Unauthorized	Invalid or Exprired token or "aud" mismatch	Verify AzureAD configuration
404 Not found	Incorrect endpint URL	Confirm API Server URL and tenantID
500 Internal Server Error	Configuration error	Check application insights logs
Chat not responding	Azure OpenAI configuration issue or Quota exceeded	Verify OpenAI deployment and quotas and configuration

 

Logging

Application logs are available in Azure Application Insights. Use the following query to view recent errors:

exceptions
| where timestamp > ago(24h)
| project timestamp, type, outerMessage
| order by timestamp desc