Azure AI Foundry New vs Classic: 2026 Migration Map

There are now two Microsoft Foundry portals, and the toggle between them is a single banner switch labeled “New Foundry.” That switch hides a real architecture decision: the new portal shows only Foundry projects, while a whole class of resources (Azure OpenAI, hub-based projects, managed-compute model hosting) lives exclusively on the classic side. The question every architect has to answer in 2026 is not “which portal looks nicer.” It is “which of my resources are stranded on classic, and what work it takes to move them.”

This article is the migration map. It separates what reached the new portal from what is still classic-only, lists exactly what transfers during a hub-to-Foundry migration and what you have to rebuild by hand, and flags the two hard dates that actually force your hand. It is current as of mid-2026 and grounded in Microsoft Learn. Where the docs hedge, I hedge too, because some of the most important questions (when does the classic portal retire?) do not have an answer in the current documentation.

A note on naming first, because Microsoft has changed it twice. The brand evolved from Azure AI Studio to Azure AI Foundry to Microsoft Foundry, and the AI services portfolio went from Azure Cognitive Services to Azure AI Services to Foundry Tools. Through all of it the underlying Azure resource type stayed Microsoft.CognitiveServices/accounts, as Microsoft documents in the navigate-from-classic guide. This article uses “new portal” and “current portal” interchangeably for the New-Foundry-on experience, and “classic portal” for New-Foundry-off.

What “New” Actually Means: A Resource Model, Not a Skin

The portal toggle is the visible part. The change underneath is the resource model.

In the classic model, a typical deployment managed multiple Azure resources at once: a Hub, an Azure OpenAI account, and Azure AI Services, spread across five or more endpoints. The new model collapses that into a single Foundry resource with child projects, accessed through one project endpoint, under one Azure resource provider namespace with unified RBAC, networking, and policies. Microsoft describes this consolidation in the what-is-Foundry overview. The resource type did not change. The number of things you have to wire together did.

This is why the new portal “shows only Foundry projects.” It is not hiding your other resources to be annoying. The new portal is the surface for the new single-resource model, and everything that predates it (Azure OpenAI standalone resources, hub-based projects, the Hub resource type itself) is reached through the classic portal, per the classic what-is-Foundry page.

So before you compare features, get the vocabulary straight, because three terms do most of the confusing work.

Two Project Types, and the One Microsoft Tells You to Pick

The most consequential choice in this whole migration is not portal-level. It is project-level. There are two project types, and they are not interchangeable.

A Foundry project is managed directly under a Microsoft Foundry resource and requires no extra Azure resources. A hub-based project is hosted by a Foundry/AI hub, which in turn requires dependent Azure Storage and Key Vault resources. Microsoft’s own guidance, stated plainly in the classic what-is-Foundry page, is: “In most cases, you want to use a Foundry project.”

That recommendation is not marketing. It reflects where the feature investment is going. Microsoft notes that in June 2025 it began moving most of the Azure AI Hub’s capabilities under the Foundry resource type, with new features primarily landing on Foundry, while select use cases such as open-source model deployments still require a hub resource, per the resource-types concept page. New generative-AI and model-centric features (the Foundry API and the Foundry Agent Service, both in general availability) are available only through the Foundry resource and its Foundry projects, as the migrate-project guide states.

But “most cases” is not “all cases,” and the exceptions are sharp. Here is the capability split between the two project types.

Read that table the way the docs ask you to: as a snapshot, not a contract. Microsoft says feature parity between the two project types is explicitly not achieved yet (“Foundry projects feature set aren’t yet on full parity”) and points to a live support matrix rather than a parity-completion date. There is no stated date for when the gaps close. Treat the per-tool GA/Preview labels in the catalog as the source of truth and verify at the tool level, because some entries (agents being one) are described differently in different places in the documentation.

The two rows that should drive your decision are the bottom two. Prompt flow and managed compute (open-source model hosting) are exclusive to hub-based projects. If your workload depends on either, you are on classic for that workload, full stop, until the docs say otherwise. Everything else points toward a Foundry project.

The Portal Feature Map: New, Classic, or Both

Project type is one axis. The other is where a given capability is reachable. Microsoft’s navigate-from-classic guide groups features into three buckets, and that grouping is the cleanest way to plan a migration.

New portal only, generally available: the Responses API, Agents v2 (which is the Responses API), a large and growing tool catalog (each entry carrying its own GA or Preview label, which you check per tool), and agent publishing to Microsoft 365 and Teams.

New portal only, Preview: multi-agent workflows, agent memory, Foundry IQ, hosted agents, the A2A protocol, and the Foundry Control Plane. Every item in this list is Preview. None of it should sit unguarded in a production path.

Both portals: Foundry projects themselves, chat completions, fine-tuning, evaluations (enhanced in the current portal), and the model catalog (expanded in the current portal).

Classic only, requiring migration: standalone Azure OpenAI resources (which you upgrade to a Foundry resource) and hub-based projects (which are not visible in the current portal at all, so you either switch to the classic portal or migrate them to Foundry projects).

The shape here is worth sitting with. The genuinely new generative-AI surface (agents v2, multi-agent, memory, Foundry IQ, A2A, Control Plane) is new-portal-only by design. The boring, load-bearing primitives (chat completions, fine-tuning, evaluations, the model catalog) work in both. And the two things that strand you on classic are an older resource type (standalone Azure OpenAI) and an older project type (hub-based). That is a healthy pattern: the consolidation is additive on the new side and migration-gated on the old side, not a forced rip-and-replace.

For the deeper “should I even be on Foundry versus standalone Azure OpenAI” question, that is a separate decision with its own tree. I worked through it in Azure AI Foundry vs Azure OpenAI: The 2026 Decision, and this article assumes you have already decided Foundry is your platform.

The API and SDK Rename You Cannot Ignore

If the resource model is the structural change, the API and SDK renames are the change that breaks your code. They are mechanical, well-documented, and unavoidable if you move to the new portal.

The terminology shifted across the board, per the navigate-from-classic guide:

Classic	New
Assistants API (Agents v0.5 / v1)	Responses API (Agents v2)
Monthly api-version params	v1 stable routes (/openai/v1/)
Threads	Conversations
Messages	Items
Runs	Responses
Assistants / Agents	Agent Versions
create_agent()	create_version()

On the SDK side, the classic packages and the Azure-specific client collapse into the unified azure-ai-projects 2.x project client together with the standard openai OpenAI() client pointed at one project endpoint, per the same navigate-from-classic guide. The mapping:

Classic	New
azure-ai-inference (model inference)	openai package
AzureOpenAI() client	OpenAI() client with base_url
azure-ai-generative	azure-ai-projects 2.x project client
azure-ai-ml (hub-to-project scenarios)	azure-ai-projects 2.x project client
azure-ai-projects 1.x (classic portal)	azure-ai-projects 2.x (new portal)

The most common rewrite is the smallest one: drop the Azure-specific AzureOpenAI client and its azure_endpoint plus api_version for the standard OpenAI() client pointed at the single /openai/v1 project endpoint, authenticated with DefaultAzureCredential rather than an API key. This pattern follows the before/after example in the navigate-from-classic guide.

# Classic: azure-ai-projects 1.x era; Azure-specific client + monthly api-version
from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://my-resource.openai.azure.com",
    api_key="my-key",
    api_version="2024-12-01-preview",
)

# New: pin azure-ai-projects 2.x; standard OpenAI client on the one project endpoint
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient(
    endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
)
client = project.get_openai_client()  # OpenAI() bound to the ".../openai/v1/" base URL

The version split is the part that bites: azure-ai-projects 1.x targets the classic portal and 2.x targets the new portal, and mixing versions across portals causes errors. In my own experience this is the single most common stumbling block, more than any strategy question, and it is easy to miss because the symptom (a ModuleNotFoundError or an unexpected API response) reads like a code bug rather than a portal mismatch. Microsoft lists exactly that symptom and its “SDK version doesn’t match your portal target” cause in the troubleshooting table of the navigate-from-classic guide. If you have ever debugged a “works on my machine” SDK mismatch, this is the same trap wearing a Foundry badge.

RBAC roles changed too. The old Cognitive Services OpenAI User and similar roles are replaced by Foundry User, Foundry Project Manager, Foundry Owner, and Foundry Account Owner, with control-plane and data-plane separation. One reassurance from the docs: these were recently renamed from Azure AI User/Owner/Account Owner/Project Manager, and the rename left role IDs and core permissions unchanged. So if you wrote Bicep or Terraform against the role IDs rather than the display names, the rename did not break you. If you hardcoded display names in scripts or documentation, update them.

What Are the Azure AI Foundry Migration Deadlines in 2026?

Two component-level deadlines are firm. The azure-ai-inference package retires May 30, 2026, and the Assistants API sunsets August 26, 2026. Everything else in the transition is soft: you can toggle portals freely, hub-based projects remain accessible on classic, and the docs announce no shutdown date for the classic portal itself.

Read these carefully, because they are narrower than the rumors. Neither date retires the classic portal. Neither date retires hub-based projects or the AI Hub resource type. They retire two specific components: an SDK package and an API. If your codebase imports azure-ai-inference, you have a hard deadline. If you run the Assistants API in production, you have a hard deadline. If you do neither, these dates do not touch you, regardless of which portal you use day to day.

This distinction is, in my own analysis, where planning most often goes wrong. Teams read “classic” and “retiring” in the same paragraph and conclude the portal is sunsetting. It is not, at least not on any date Microsoft has published. The honest statement is: the only firm dates are component-level, and you should plan to them specifically rather than to a vague “classic is going away” anxiety.

What Transfers in a Hub-to-Foundry Migration (and What Does Not)

If you decide to move a hub-based project to a Foundry project, the mechanics are documented and reasonably quick, but the “what does not transfer” list is the part that will hurt if you skip it.

From a hub-based project, you create a new Foundry project on the existing Foundry resource. This requires the Owner role and takes roughly 5 to 10 minutes, per the migrate-project guide.

What transfers: model deployments, data files, fine-tuned models, assistants, and vector stores.

What does not transfer: preview agent state (messages, threads, and files), open-source and managed-compute model deployments (which are unsupported on Foundry projects), and hub-project access itself.

Two of those “no” rows deserve a flag. First, preview agent state does not move. If you have agents mid-flight with live conversations, threads, and uploaded files, migrating loses that state. Plan the cutover for a quiet window and recreate, rather than treating it as a hot-path operation.

Second, open-source and managed-compute deployments are unsupported on Foundry projects. This is the same exclusion as the prompt-flow and managed-compute rows in the capability matrix earlier. If your hub-based project exists specifically to host an open-source model on managed compute, migration to a Foundry project is not a move, it is a deletion of the one thing that workload does. Keep it on a hub.

One more constraint that lives in the documentation and is easy to miss. The hub-to-Foundry migration article, along with the other hub-focused articles (hub RBAC, hub quickstart, hub resources overview), is labeled “Applies only to: Foundry (classic) portal” and explicitly states the steps do not work for Foundry projects in the new portal. So when you follow migration guidance, confirm which portal the doc is written for, because hub-focused and Foundry-project-focused docs are not interchangeable even when they describe the same conceptual task.

A Decision Framework You Can Defend in a Review

Here is how I would structure the classic-to-new decision for an enterprise platform plan. It is built from the decision dimensions Microsoft surfaces, ordered by how often each one is the actual deciding factor.

1. Do you need prompt flow or managed-compute (open-source) model hosting? If yes, you stay on a hub-based project in the classic portal for that workload. These two capabilities have no Foundry-project equivalent in the current docs. This is the first question because it is the only true blocker.

2. Do you have an azure-ai-inference or Assistants API dependency? If yes, you have a hard deadline (May 30, 2026 for the package, August 26, 2026 for the API). Migrate the dependency regardless of your broader portal strategy. These dates do not wait for your platform roadmap.

3. Are the new-portal features you want GA or Preview? Responses API, Agents v2, the tool catalog, and M365/Teams publishing are GA. Multi-agent workflows, agent memory, Foundry IQ, hosted agents, A2A, and the Control Plane are Preview. Gate every Preview capability out of production paths and design a fallback. Building production agent orchestration on Preview multi-agent workflows is a bet on a date Microsoft has not given you. Preview features are also typically excluded from SLAs and may fall outside Online Services Terms protections (verify the supplemental Preview terms against your current agreement), so gating Preview out of production is a contractual control, not just a stability precaution.

4. Is your target region supported? The Responses API and Foundry Agent Service are not available in every Azure region. Microsoft warns that if a Foundry resource sits in an unsupported region, agents and other Responses API features will not work in the current portal, and you must create a new Foundry resource in a supported region. Region-strand is not a theoretical edge case: Microsoft lists “Foundry resource is in a region that doesn’t support the Responses API” as one of the documented common migration issues in the navigate-from-classic guide, which points at a dedicated feature availability across cloud regions reference (verify the exact supported-region list against current docs, since it moves). Verify region support before you migrate, not after.

5. Do your SDK versions match your portal? azure-ai-projects 1.x for classic, 2.x for new. Mismatched versions error out. This is a code-hygiene check, not a strategy question, but in my experience it strands more migrations than the strategy questions do, and Microsoft documents the mismatch symptom and fix in its troubleshooting table.

6. Do you still depend on standalone Azure OpenAI resources or hub-based projects? These are classic-only and require an explicit upgrade (Azure OpenAI resource to Foundry resource) or migration (hub-based project to Foundry project). They are not blockers, but they are work you have to schedule.

If the answers point you toward a Foundry project (and for most workloads they will, because Microsoft says so and the feature investment confirms it), the migration itself is the 5-to-10-minute operation described above. The framework exists so that the 5-to-10-minute operation is the last step, not the first.

Where It Breaks: Caveats and Open Questions

I would be misrepresenting the documentation if I gave you cleaner answers than the docs actually contain. Several important questions do not have published answers as of mid-2026, and you should plan around the uncertainty rather than around a guess.

There is no announced retirement date for the classic portal. The docs say new investment focuses on the new portal and that you can toggle freely, but they give no classic-portal shutdown date. Anyone telling you the classic portal dies on a specific date is reading something the current documentation does not say. Plan your migration on the value of consolidation and on the two real component dates, not on a phantom portal-retirement deadline.

There is no announced retirement date for hub-based projects or the AI Hub resource type. They remain accessible in the classic portal with no announced sunset. Given that prompt flow and managed-compute hosting are hub-only and have no new-portal equivalent, this is consistent: Microsoft cannot retire the hub while the hub is the only home for those capabilities.

The old brand names have no stated naming-retirement date. “Azure AI Studio” and “Azure AI Foundry” are described as superseded brands, but the docs give no date on which the names stop being used. This is cosmetic, but it matters for documentation and onboarding material that references the old names.

Feature parity between project types is not complete, and no completion date is stated. Microsoft explicitly says Foundry projects “aren’t yet on full parity” and points to a live support matrix. Do not assume a capability you saw on a hub-based project is available on a Foundry project. Check the matrix.

Individual tool GA/Preview states should be verified at the tool level. The classic capability table lists agents as “Preview only” on hub-based projects, while agents are described as GA on Foundry projects elsewhere. The catalog carries per-tool labels, and the docs tell you to trust those over any summary table, including the ones in this article. When the stakes are production, read the live label.

Some new-portal availability is hedged in the docs themselves. For example, whether the Content Understanding GA API (2025-11-01) is yet available in the new portal is described as “will soon support,” with no exact date. When the official docs hedge, do not firm it up in your architecture decision record. Carry the hedge forward.

API key authentication does not cover every surface in the new portal. Per Microsoft’s new-portal GA overview, Foundry supports API key authentication for most areas, but agents, evaluations, the datasets tab, Content Understanding, and workflows require Microsoft Entra ID authentication (point-in-time as of the GA overview; verify against current docs). A team that scripted against API keys on classic will hit auth failures on exactly these surfaces. Plan an Entra ID with managed-identity path for them before you cut over, not after the first 401.

The pattern across all of these: the consolidation is real and directional, but the calendar is mostly empty except for two component dates. Build your plan on the firm dates and the GA/Preview gates, treat everything else as directional, and re-check the live matrix before you commit production load. The governance wrapper around all of this (who can create what, which Preview features are allowed where) is the same discipline I described in the AI governance framework for the Microsoft stack, and it applies cleanly to the new resource model because RBAC, networking, and policy are now unified under one resource.

Foundry New vs Classic: The 2026 Bottom Line

Three takeaways for the architect writing the 2026 platform plan.

First, default to a Foundry project, and document the exceptions. Microsoft says “in most cases, you want to use a Foundry project,” the feature investment backs it up, and the new single-resource model is genuinely simpler than the old Hub-plus-OpenAI-plus-AI-Services sprawl. The only durable reasons to stay on a hub-based project are prompt flow and managed-compute model hosting. If neither applies, your default is a Foundry project, and the exceptions should be written down as exceptions.

Second, plan to the two real dates and ignore the phantom one. May 30, 2026 (the azure-ai-inference package) and August 26, 2026 (the Assistants API) are firm and component-level. The classic portal retirement is not a date, because there is no date. Most migration anxiety I see conflates the two. Separate them in your plan.

Third, the new-portal Preview list is long, and that is the real production gate. Multi-agent workflows, agent memory, Foundry IQ, hosted agents, A2A, and the Control Plane are the capabilities people get excited about, and every one of them is Preview right now. The GA surface (Responses API, Agents v2, tool catalog, M365/Teams publishing) is what you can build on today. Design for the GA line and treat the Preview features as roadmap, not foundation. If you are mapping how those agent patterns fit a broader architecture, the Microsoft agentic patterns playbook is the companion read.

The migration is happening either way. The question is whether you move proactively on the workloads that benefit and the dependencies that have deadlines, while leaving the genuinely classic-only workloads where they belong. Pick the project type per workload, document the choice as an ADR, verify region support before you cut over, and re-read the live capability matrix the week you migrate.

Read Next

• Azure AI Foundry vs Azure OpenAI: The 2026 Decision - the upstream decision: Foundry as a platform versus standalone Azure OpenAI, with the eight scenarios and the resource-upgrade mechanics
• The Microsoft Agentic Patterns Playbook, Decoded - how the new-portal agent capabilities map to actual orchestration patterns
• Six Rules for LLM-Agnostic AI Agents on Microsoft Foundry - designing agents that survive the SDK and model-catalog churn this article describes
• AI Governance Framework for the Microsoft Stack - the RBAC, policy, and Preview-gating discipline that the unified Foundry resource model makes easier to enforce
• Azure AI Landing Zone: The 2026 Reference Architecture - the platform-level architecture that hosts Foundry resources, networking, and policy from day one

---

If you are mapping a classic-to-Foundry migration for an enterprise platform and want a second-opinion read on which workloads to move and which to leave on the hub, reach out.