Microsoft Foundry for people who learned Azure OpenAI: what changed and what to migrate

If you learned Azure OpenAI a year or two ago, almost every name has changed since: the portal, the resource type, the SDK packages, the API for agents, even the roles. The models and your existing calls still work, but three retirements have dates attached, and the new portal only shows the new kind of resource. This page is the map from the names you know to the ones Microsoft Foundry uses now, with the dates and a checklist of what actually needs changing.

The names, old and new

The dates that matter

The first two dates have passed. Code that still uses either is already past Microsoft's date for it, so treat it as the first thing to change rather than a plan for later. Jobs created earlier from stored-completion datasets keep working after the third date; only new use stops.

The migration checklist

1. Upgrade the Azure OpenAI resource to a Foundry resource. It keeps its name, endpoint, API keys, tags, network settings, identity settings and existing state, including fine-tuning jobs. You need Owner on the subscription or resource group and a system-assigned managed identity on the resource. In the Azure portal, open the resource and select Get started on the "Want to try the latest industry models and Agents?" banner; in Bicep, change kind from OpenAI to AIServices, set allowProjectManagement: true and add the identity. Resources with private endpoints can't be upgraded in either portal: delete the endpoints and recreate them after, or do it in Bicep or Terraform (AzureRM 4.56.0 or later for a non-destructive change). Customer-managed keys need a request to Microsoft first. You can roll back after deleting projects, connections and non-OpenAI deployments. previousKind: "OpenAI" on the resource tells you an upgrade happened.
2. Fix private DNS after the upgrade. A Foundry resource answers on three host names: {name}.openai.azure.com, {name}.services.ai.azure.com and {name}.cognitiveservices.azure.com. Private networking needs a DNS zone, or a conditional forwarder, for each, and the private endpoint recreated so the new addresses get IPs.
3. Replace the SDK packages. AzureOpenAI(azure_endpoint=…, api_version=…) becomes OpenAI(base_url="https://<project>.services.ai.azure.com/openai/v1", …) with an Entra bearer token; azure-ai-inference goes; azure-ai-projects moves to 2.x. The SDK major version must match the portal you use.
4. Move agents off the Assistants API. Assistants become agent versions, threads become conversations, runs become responses. Microsoft's migration tool converts the code constructs; it doesn't move old threads or runs, which stay readable through the old API until it's gone. Check that the resource's region supports the Responses API first; if not, agents don't appear in the new portal at all. Our guide Foundry Agent Service, and moving off the Assistants API walks through it.
5. Replace stored completions before 15 October 2026 with the Responses API, or with Agent Traces (connect the project to Application Insights) if you used them to inspect agent runs or build evaluation datasets.
6. Review access. After the upgrade, users with Cognitive Services User get every Foundry feature, while Cognitive Services OpenAI User stays limited to OpenAI features. Wildcard role assignments and Azure Policy definitions that don't name a resource kind widen in the same way. Owners and Contributors still can't create agents; building needs Foundry User (or Project Manager or Foundry Owner). An Azure Policy for model deployments keeps the model catalogue to what you allow.

What you do not have to do

• You don't need a new resource or a new endpoint. Existing Azure OpenAI calls, keys and customisations keep working on the upgraded resource, and existing use costs the same. Only the new features you adopt add cost.
• Chat completions aren't going away. The Responses API is the new default and the only API for agents, but chat completions remain available in both portals.
• Hub-based projects aren't lost. They're hidden in the new portal; switch to the classic portal to reach them, or migrate them to Foundry projects. Microsoft's new investment goes to Foundry projects.
• Your knowledge transfers. Quota, deployments, content filtering (now called guardrails) and fine-tuning work as before, under new menus.

Finding things in the new portal

If your SDK call fails with ModuleNotFoundError or odd behaviour, the SDK version doesn't match the portal. If agent code gets 404 or MethodNotAllowed, it's sending Assistants API calls to a Responses API endpoint. If projects are missing, they're hub-based: switch portals.

Sources

• Migrate from the Foundry (classic) portal, Microsoft Learn (the mappings, dates and navigation)
• Upgrade from Azure OpenAI to Microsoft Foundry, Microsoft Learn
• What is Microsoft Foundry?, Microsoft Learn
• Migrate to the new agents developer experience, Microsoft Learn
• Migrate from stored completions to Responses API and Agent Traces, Microsoft Learn
• Role-based access control for Microsoft Foundry, Microsoft Learn