The ticket said the documentation was wrong. A developer on the client's team was following a Microsoft quickstart for the Foundry Agent Service, and the option in step three didn't exist in their portal. He'd checked twice, cleared the cache, tried a different browser, and written a fairly pointed message about docs quality. He wasn't wrong about what he was seeing. He was wrong about why.
Their project was a hub-based project. The quickstart was written for a Foundry project. Same product name on the tin, two different Azure resource architectures underneath, and the feature he wanted only exists on one of them. Not a setting, not a preview flag, not a region — a different resource type, which meant the fix was a deployment, not a checkbox. That confusion cost his team most of a sprint, and I've since watched it cost other teams more.
So here's the thing to hold onto, and everything below follows from it: Azure AI Foundry is one product name over two resource architectures — the older hub-based shape it inherited from Azure AI Studio, and the newer Foundry resource with Foundry projects — and which one you deployed determines which features you can even see. This article covers what each shape actually is, the capability split as of February 2026, what migrates and what doesn't, how the infrastructure-as-code and networking stories differ, and what I'd deploy today.
Why there are two of everything
The hub-based shape is Azure Machine Learning's family tree showing through. Azure AI Studio was built on top of the Azure ML workspace model, and that model is genuinely good at something specific: a hub is a shared collaboration container that holds connections to data and services, compute quotas, a managed virtual network, and security configuration, and projects are child workspaces that inherit all of it. One platform team configures the hub once; five product teams get projects that already have the right connections and network posture. If you've run Azure ML at scale, you recognize the pattern immediately, and it's the reason large enterprises adopted it.
It's also heavy. A team that wants a model endpoint and an agent gets a workspace-shaped object with compute concepts, a managed network, and a hub dependency they didn't ask for. So Microsoft introduced a second shape at Build 2025: a Foundry resource — an Azure AI Services account — with Foundry projects as lightweight child resources. Self-serve, project-scoped, no hub in the path, and it's where the agent and model work has landed since. The community has started calling the older world "classic," and Microsoft's own docs increasingly split their pages by which shape you're on.
graph TB
subgraph OLD["Hub-based — the 'classic' shape (Azure ML lineage)"]
HUB[("AI hub
Microsoft.MachineLearningServices/workspaces
kind: Hub")]
HP1["hub project
kind: Project"]
HP2["hub project
kind: Project"]
DEP[("dependencies:
Storage · Key Vault
+ optional ACR / App Insights")]
NET["managed VNet
+ hub-level connections"]
HUB --> HP1
HUB --> HP2
HUB --> DEP
HUB --> NET
end
subgraph NEW["Foundry resource — the new shape"]
ACC[("Foundry resource
Microsoft.CognitiveServices/accounts
kind: AIServices")]
FP1["Foundry project"]
FP2["Foundry project"]
BYO[("optional BYO for agents:
Storage · Cosmos DB · AI Search")]
ACC --> FP1
ACC --> FP2
FP1 -.->|"standard agent setup"| BYO
end
The two resource trees, with the detail that matters most for anyone writing Bicep or Terraform: they live in different Azure provider namespaces. A hub is a Machine Learning workspace; a Foundry resource is a Cognitive Services account. That's why the new shape isn't a parameter on your existing module — it's a different module, with different RBAC roles, different networking primitives, and different diagnostic settings.
The capability split, as of February 2026
New agent and model capabilities are shipping to Foundry projects; hub-based projects keep the Azure ML-adjacent features that the new shape hasn't taken on. That's the rule, and it explains almost every "why can't I see this" question.
| Capability | Hub-based project (classic) | Foundry project (new) |
|---|---|---|
| Foundry Agent Service (GA) | Not the path forward | Yes — and this is where agent features land |
| Foundry API / project-scoped endpoint | No | Yes |
| New model families and model-centric features | Lags | First |
| Prompt flow authoring | Yes — only here | No |
| Managed-compute deployments of open-weight models | Yes — only here | No |
| Azure ML integration (jobs, pipelines, registries) | Yes | No |
| Hub-level shared connections + managed VNet | Yes | Different model — account-level, Cognitive Services networking |
| Self-serve project creation by a dev team | Needs a hub, so usually platform-team gated | Yes |
| Serverless / standard model deployments | Yes | Yes |
Two rows carry most of the weight. Prompt flow and managed-compute hosting of open-weight models are the two real reasons to still be on a hub — if you're running either, you're not migrating this quarter, and that's fine. Everything else on the list is an argument for the new shape.
What migrates, and what quietly doesn't
Microsoft ships a migration path from hub-based projects to Foundry projects, and it handles the boring things well. The list that matters is the second one.
| Moves across | Does not move |
|---|---|
| Model deployments | Agent state from the preview agent experience — threads, messages, uploaded files |
| Data files | Managed-compute (open-weight model) deployments — no equivalent to move to |
| Fine-tuned models | Hub project access — RBAC doesn't carry; you re-grant on the new resource |
| Assistants | Prompt flows — there's nowhere for them to land |
| Vector stores | Hub-level connections — you recreate them at the new scope |
The agent-state gap is the one that surprises people, so plan for it explicitly: treat a migration as a cutover where conversation history starts fresh. If your product promises users their history, that's a data-migration project you write yourself, and the estimate belongs in the plan rather than in the retro. It's also a good argument for the general principle I keep repeating — persist the conversation state your application needs in a schema you own, not only in the platform's, which is the same lesson that applies to agent memory design generally.
And a hard date to put in the calendar: the Azure OpenAI Assistants API is retiring on August 26, 2026. Assistants migrate across resource shapes, but they're a dead end either way — anything new should be built on the Agent Service and the Responses API. If you have an Assistants-based system in production, that's a 2026 work item with a real deadline, not a someday.
Infrastructure as code, networking, and identity
This is where the two shapes diverge most and where the migration effort actually sits, because a platform team's investment in a hub is mostly investment in everything around the hub.
Hub-based (classic)
Microsoft.MachineLearningServices/workspaces kind: Hub
Microsoft.MachineLearningServices/workspaces kind: Project (child of hub)
+ Microsoft.Storage/storageAccounts (required dependency)
+ Microsoft.KeyVault/vaults (required dependency)
+ optional: Container Registry, Application Insights
Networking: Azure ML managed VNet, workspace private endpoints
RBAC: Azure ML + Azure AI roles at hub / project scope
Foundry resource (new)
Microsoft.CognitiveServices/accounts kind: AIServices
Microsoft.CognitiveServices/accounts/projects (child)
+ optional BYO for the standard agent setup:
Microsoft.Storage/storageAccounts
Microsoft.DocumentDB/databaseAccounts (Cosmos DB for NoSQL)
Microsoft.Search/searchServices (Azure AI Search)
Networking: Cognitive Services private endpoints + custom subdomain
RBAC: Azure AI roles at account / project scopeThree consequences worth internalizing:
- Your hub module isn't a starting point. Different provider, different child-resource model, different role definitions. Budget for a new IaC module rather than a refactor, and expect your policy assignments and diagnostic settings to need new targets.
- Agent storage is a decision now. The Agent Service offers a basic setup where the platform manages thread and file storage, and a standard setup where you bring your own Azure Storage account, Cosmos DB for NoSQL, and Azure AI Search. For anything with data-residency, customer-managed-key, or auditability requirements, the standard setup is the one that passes review — and it's much easier to start there than to move later. The regulated multi-agent design constraints all land on this choice.
- Don't forget the third resource type. A plain Azure OpenAI resource (a Cognitive Services account of kind
OpenAI) is a fourth thing people conflate with all of this. It still works, and it's still the right minimal choice if all you want is model inference behind your own gateway — the pattern I described in LLM gateway routing and fallback. The Foundry resource is what supersedes it when you want projects, agents, and the wider model catalogue.
# The minimum viable new-shape deployment: a Foundry resource with a custom
# subdomain (required for token auth and private endpoints), system-assigned
# identity, and local key auth switched off so everything goes through Entra ID.
az cognitiveservices account create \
--name fdy-claims-prod \
--resource-group rg-ai-prod \
--location canadacentral \
--kind AIServices \
--sku S0 \
--custom-domain fdy-claims-prod \
--assign-identity \
--yes
# Keys off. If a developer can copy a key into a notebook, someone will.
az resource update \
--resource-group rg-ai-prod \
--name fdy-claims-prod \
--resource-type Microsoft.CognitiveServices/accounts \
--set properties.disableLocalAuth=true
# Then create the project (portal, ARM/Bicep, or the Foundry SDK) and grant
# the app's managed identity the Azure AI project roles it needs — scoped to
# the project, not the account. Project-scoped RBAC is the point of this shape.The trap: two portals, and a quickstart that creates the wrong resource. The portal experience for the two shapes is not the same surface, so "my colleague can see it and I can't" is usually two people looking at two resource types, not a permissions bug — and it burns hours because nobody thinks to check the resource type first. Worse, plenty of tutorials, samples, and one-click templates still provision a hub, so a developer following a blog post in the morning can create the exact architecture you decided against in the afternoon. Two defences that cost nothing: put the resource type in your naming convention so it's visible in the resource list at a glance, and add an Azure Policy that denies creating Microsoft.MachineLearningServices/workspaces of kind Hub outside the subscriptions where you've decided hubs belong. Then the ticket that arrives says "policy blocked me," which is a five-minute conversation instead of a sprint.
So what should you deploy?
New work: Foundry project, without much deliberation. That's where Agent Service GA, the Foundry API, and the newer models are, and starting on the shape that isn't receiving features is choosing a migration you haven't scheduled yet.
Existing hub-based estate — three honest cases:
- You depend on prompt flow or managed-compute open-weight hosting. Stay. Plan, don't panic. Keep an eye on where those capabilities land, and stop adding to the prompt-flow surface — I'd write new pipelines as plain code with a separate evaluation harness, for the reasons in the agent framework comparison.
- You're on a hub but only using models and chat. That's the easy migration and the one worth doing soon: model deployments, data, fine-tuned models, and vector stores move; you re-grant RBAC and recreate connections; a week of work for a team, mostly testing.
- You're running both, deliberately. Completely reasonable, and common in larger organizations — the ML platform team keeps a hub, the product teams get Foundry projects. The failure isn't running both; it's ambiguity about which one a given workload belongs to. Write it down in the platform's architecture decision record, name an owner per shape, and make the naming convention carry the answer. This is exactly the kind of decision that belongs in a durable written record rather than in one architect's memory.
One more piece of guidance that has aged well every time I've given it: keep your application's dependency on Foundry behind an interface. The model client, the agent invocation, the thread persistence — three seams. Teams that called SDKs directly from business logic did the hard version of this migration; teams with a thin adapter did the easy one. The platform will keep changing shape, because it's changed shape twice already.
What to carry away
Azure AI Foundry is one name over two resource architectures, and knowing which one you're on is a prerequisite for reading the documentation correctly. Hub-based projects are Azure ML workspaces with a shared hub: heavier, still the only home for prompt flow, managed-compute open-weight hosting, and deep Azure ML integration. Foundry projects are child resources of an AI Services account: lighter, self-serve, project-scoped RBAC, and the place agent and model features actually ship.
Deploy the new shape for anything new. Migrate the easy hub cases — models and chat — and leave the prompt-flow and managed-compute ones alone until there's somewhere for them to go. When you do migrate, remember that model deployments, data, fine-tuned models, and vector stores come with you while agent threads, managed-compute deployments, and RBAC do not, and put the Assistants API's August 26, 2026 retirement on the roadmap now. Choose the standard agent setup with your own Storage, Cosmos DB, and AI Search if you have any residency or key-management requirement, because retrofitting that is worse than starting with it.
And name your resources so the shape is obvious, block accidental hub creation with policy, and put a thin adapter between your application and whichever Foundry you're on. The product will change again. Your code shouldn't have to.