AI Platform: Architecture¶

This page is the high-level design of the AI Platform. It is the reference design from the Terraform modules: your deployment may differ in names, SKUs and which optional parts exist.

Layers¶

The solution has three layers. Each layer is deployed on top of the previous one.

flowchart TB
    subgraph shared["1. Shared platform (platform team)"]
        acct["Foundry account<br/>(AIServices)"]
        cae["Container Apps<br/>environment"]
        acr["Container Registry"]
        cosmos["Cosmos DB<br/>(agent threads)"]
        search["AI Search<br/>(vector store)"]
        kv["Key Vault"]
        law["Log Analytics"]
    end
    subgraph proj["2. Foundry project per workload"]
        p["Foundry project<br/>+ Agents capability host"]
        pid["Project identity"]
        st["Storage account"]
        ai["Application Insights"]
    end
    subgraph wl["3. Workload (workload team)"]
        app["Application / agent client"]
        wid["Workload identity"]
    end
    acct --> p
    p --> pid
    p --- st
    p --- ai
    p -. connection .-> cosmos
    p -. connection .-> search
    ai --> law
    app --> p
    app --> wid
    app --> cae
    cae --> acr

Layer	Contains	Created by
Shared platform	Foundry account, Container Apps environment, registry, Cosmos DB, AI Search, platform storage, Key Vault, Log Analytics, network	Platform team
Foundry project	Project, project identity, storage account, Application Insights, connections, capability host, role assignments	Platform team, on request
Workload	Application, workload identity, role assignments for that identity	Workload team (with the platform team where roles on shared resources are needed)

Foundry account¶

One account per platform. From the Terraform:

Setting	Value
Resource type	`Microsoft.CognitiveServices/accounts`, kind `AIServices`, SKU `S0`
Project management	Enabled (`allowProjectManagement`)
Local (key) authentication	Disabled (`disableLocalAuth`), so access uses Entra ID
Custom subdomain	Equal to the account name
Identity	A user-assigned managed identity created with the account
Network injection	Scenario `agent` into an integration subnet you supply (`useMicrosoftManagedNetwork` is `false`, so your own subnet is used)
Private endpoint	Created only when an endpoint subnet is supplied, sub-resource `account`
Public network access	`Enabled` in the module, see Known issues

The module is deployed with the azapi provider, because the resource is not fully supported by azurerm. The module outputs the account ID, name, endpoint, an OpenAI endpoint of the form https://<account>.openai.azure.com and the client and principal ID of the identity.

Foundry project¶

Each workload gets its own project in the shared account. The project module creates:

Resource	Details
Resource group	One per project, named with the naming module and the suffix `-project`
Project	`Microsoft.CognitiveServices/accounts/projects`, with a user-assigned managed identity
Storage account	Standard, LRS, TLS 1.2 minimum, public network access disabled, with a private endpoint for `blob`
Application Insights	Workspace-based, linked to the Log Analytics workspace you supply
Connections	Storage, Cosmos DB and AI Search with Entra ID authentication; Application Insights with its connection string
Capability host	Kind `Agents`, with the vector store, storage and thread storage connections
Role assignments	For the project identity and for the owner, contributor and reader groups (Access and RBAC)

All connections have isSharedToAll set to false: they belong to the project.

The module can also create the Foundry account itself ("standalone mode", when no account_id is passed). With the shared account of the platform you use "decoupled mode", where only the project is created. See Platform modules.

Where agent data lives¶

The capability host points the agent service at the connected stores:

Data	Store
Threads, messages, agent definitions, run state	Cosmos DB, database `enterprise_memory`, collections with the project's internal ID as prefix (thread message store, system thread message store, agent entity store, agent definitions, run state)
Files	The project storage account (blob)
Vectors	The Azure AI Search service connected to the project

Cosmos DB and AI Search are shared, so isolation between projects is done with the per-project collections and role assignments, not with separate services.

Network¶

The Foundry account, and in the project module also the project storage account, are reached through private endpoints in the endpoint subnet of the spoke.
Agents run with network injection into the integration subnet of the spoke.
The private DNS zones listed in the project module for full functionality are: privatelink.vaultcore.azure.net, privatelink.openai.azure.com, privatelink.cognitiveservices.azure.com, privatelink.aiservices.azure.com, privatelink.blob.core.windows.net, privatelink.documents.azure.com and privatelink.search.windows.net.
The modules ignore changes to the DNS zone group of their private endpoints, so the DNS records are expected to be registered outside the module. How that is done on the platform is in DNS design.

Naming¶

The project module uses the community naming module with the project name as suffix. The Foundry account name is derived from the naming module's cognitive account name, with cog replaced by aif. The project identity is named id-<project>-foundry-project, and the lookup module relies on that name. The resource suffix pattern in the source is <workload>-<environment>-<region> with shorthands (prd, acc, tst, dev, np; weu, sec). Your platform's naming may differ: Naming and tags.

Observability¶

The project's Application Insights writes to the Log Analytics workspace of the spoke.
In standalone mode the module also sets diagnostic settings on the account for the log categories Audit, RequestResponse and AzureOpenAIRequestUsage. The standalone setting is not created in decoupled mode. Diagnostic settings for the shared account are not part of the account module (see Known issues).