Setting Up an Azure AI Foundry Project

#ai #machinelearning #tutorial #llm

There are two things called a Foundry project, they live in different Azure resource providers, and the tutorial you followed was probably about the other one. That is the whole difficulty here.

The name changed; the resources changed too

Microsoft has renamed this product more than once — Azure AI Studio, then Azure AI Foundry, and now Microsoft Foundry, with the previous portal preserved as “Foundry (classic)”. The documentation moved with it, so a link to an ai-foundry or ai-studio path may now redirect somewhere with different content.

This matters more than branding usually does, because the rename accompanied a change of underlying Azure resource. Following a guide written for the older shape produces a working environment that is not the one the current guides describe, and the difference shows up as missing features rather than as an error.

Two kinds of project

Microsoft documents both and recommends the first for almost all new work:

Foundry project. Lives under a Foundry resource — Microsoft.CognitiveServices/accounts with kind: AIServices. This is the same resource provider as an Azure OpenAI account, with a different kind. Microsoft states that new agent and model-centric capabilities are available only here, including the Foundry API and the generally available Foundry Agent Service.
Hub-based project. Lives under a Foundry hub, and both are machine learning workspaces: Microsoft.MachineLearningServices/workspaces with kind: hub and kind: project. This is the older shape, accessible through the classic portal, and Microsoft states new investment is going into Foundry projects instead.

The single most useful diagnostic when a feature is missing: look at the resource type in the Azure portal. If it says Machine learning workspace, you have a hub-based project and the feature you are looking for may only exist on the other kind.

What each object owns

Four objects, and knowing which owns what is what makes permissions and billing legible.

The Foundry resource owns the region, the endpoint, the model deployments and the quota consumption. This is the billing boundary for tokens. It is the object an Azure OpenAI account is a narrower version of.
The project is the unit of isolation — Microsoft describes it as a container for access management, data upload and integration, and monitoring, letting you separate use cases without creating extra Azure resources. Several projects share one resource’s deployments.
Connections are how a project reaches anything outside itself: a search service, a storage account, another model endpoint. They belong to the project, not to the resource.
The managed key vault. Microsoft documents that Foundry stores connection details in a managed Azure Key Vault and that all Foundry projects use one. It exists whether or not you asked for it, and it is where connection secrets actually live.

The practical consequence: a per-team split at project level shares quota, because quota belongs to the resource. If teams must not be able to exhaust each other’s throughput, the split has to be at resource level, or a policy layer has to enforce it — which is what API Management is usually doing in this position.

Create one

Create the Foundry resource with the right kind. The kind is not editable afterwards, so this is the decision to get right:

az cognitiveservices account create \
  --name mg-foundry-weu \
  --resource-group rg-inference \
  --location westeurope \
  --kind AIServices \
  --sku S0 \
  --custom-subdomain-name mg-foundry-weu \
  --yes

Create the project under it. A project is a child resource of the account; in the portal it is the first thing offered after the resource exists, and it can also be created from the Foundry portal by selecting the project name in the upper-left corner and choosing Create new project.
Deploy at least one model to the resource, otherwise the project has nothing to call. This is the same deployment object described on the catalog deployment page.
Add the connections the project needs — a search index, a storage account — and verify each one resolves before building anything on top.
Assign roles on the resource, not on the project, for anything that calls a model. Inference permission is a resource-scoped role.

The portal click-path is the volatile part of this page and it has been reorganised at least twice during the renames. The resource kinds, resource providers and CLI commands are stable; prefer them, and treat any screenshot-based guide including this description as provisional.

The decisions you cannot undo

Three properties of that account are fixed at creation, and all three are set by a form most people click through in under a minute.

Kind. An account created as OpenAI is not a Foundry resource and cannot be converted into one. If you want the Foundry surface — the catalog, agents, projects — you need kind: AIServices from the start.
Region. Resources do not move. A region chosen because it was the default in the dropdown becomes the region your quota lives in, your model availability is determined by, and your latency is measured from. Choose it against the model availability question rather than against proximity alone.
Custom subdomain. Immutable, and reusing the name requires deleting the resource holding it. This is also the property that Entra ID authentication and private endpoints depend on.

There is a fourth trap in the undo path itself. Deleting the account does not immediately release everything: a soft-deleted Foundry or Azure OpenAI resource continues to hold its name and, if it was deleted programmatically while deployments still existed, its quota allocation for up to 48 hours until it is purged. A pipeline that tears down and recreates an environment under the same name will fail on the second run for a reason that has nothing to do with the template.

Name accordingly. A resource name that encodes the region, and a project name that does not, is the arrangement that survives adding a second region — the projects stay conceptually the same and the accounts multiply.

Choosing between them

Choose a Foundry project unless something specific forces the other. Microsoft’s own guidance is that a Foundry project is what you want if you are building agents or working with models, and that hub-based projects are the legacy shape with a documented migration path.

The reasons to still be on a hub are real but narrow, and they cluster around Azure Machine Learning: shared compute, managed online endpoints for custom models, and prompt flow, which is a workspace feature and has a published retirement date. If your reason for a hub is prompt flow, read that page before building anything long-lived on it.

If you are already on a hub-based project, migration is a supported path rather than a rebuild, but it is not automatic and the connections do not move themselves. Do it deliberately, with the connection inventory in hand, rather than discovering halfway through that the managed key vault on the old workspace held a secret nobody has a copy of.