Migrate from the Foundry (classic) portal

Microsoft Foundry evolved through several naming and architectural changes. If you're moving from the classic portal experience, this article helps you plan and execute the transition with reference mappings for terminology, capabilities, SDKs, and portal navigation.

Prerequisites

• An Azure account with an active subscription. Create one for free.
• A Foundry project.
• For SDK migration: Python 3.9+ or .NET 8+, with azure-ai-projects 2.x and openai packages installed.
• For resource upgrade: Owner or Contributor role on the Azure OpenAI resource you plan to upgrade.

Plan your migration

Follow these steps to move from the classic portal experience to the current Foundry portal:

1. Review terminology changes. Scan the terminology mapping to understand renamed concepts and new resource types.
2. Check the feature comparison. Use the feature comparison table to identify capabilities that are new, enhanced, or classic-only.
3. Update your SDK packages. Replace deprecated packages using the SDK mapping table.
4. Migrate agents to the Responses API. Rewrite agents that use the Assistants API to use the Responses API before the August 2026 sunset.
5. Verify your Foundry resource region supports the Responses API. The Responses API and Foundry Agent Service aren't available in every Azure region. If your Foundry resource is in an unsupported region, agents and other Responses API features don't work in the current portal. Check the Responses API region availability list before migrating.
6. Validate in the new portal. Use the portal navigation reference to verify your workflows in the current experience.

Terminology mapping

The following table maps classic concepts to their current equivalents.

SDK mapping

Use the following table to identify which SDK packages map to the current Foundry experience and which ones they replace.

The following example shows the most common SDK migration — replacing the Azure-specific AzureOpenAI client with the standard OpenAI client.

Classic (before):

from openai import AzureOpenAI

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

Current (after):

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

client = OpenAI(
    base_url="https://my-project.services.ai.azure.com/openai/v1",
    default_headers={"Authorization": f"Bearer {get_bearer_token_provider(DefaultAzureCredential(), 'https://cognitiveservices.azure.com/.default')()}"}
)

Feature comparison

The following tables compare feature availability between the classic and current portal experiences.

Available in both portals

New in the current portal

These features are available only in the current Foundry portal:

Classic-only (migration required)

Navigate the portal

The classic portal uses a single customizable left pane for all navigation, with Management center at the bottom. The current portal splits features across five top-level sections, each with its own left pane.

The following table maps frequently used classic portal locations to their current equivalents.

Switch between portal experiences

You can switch between the classic and current portal experiences at any time. The toggle preserves your current context, such as the project you're working in.

1. Look for the New Foundry toggle in the top banner.
2. Select the toggle to switch between the classic and current experiences.
3. The page reloads with the selected portal interface.

Troubleshoot common migration issues

Related content

• What is Microsoft Foundry?
• Get started with Foundry Agent Service
• Develop with the Responses API
• Deploy models from the model catalog
• Use a screen reader with Microsoft Foundry