How to Fix Microsoft Foundry: Setup, Config & API Errors
Why This Is Happening
I've seen this exact situation play out dozens of times: a developer opens the Azure portal, looks for their Azure AI Studio or Azure OpenAI resource, and suddenly can't find anything where it used to be. Or they try to run a script that worked last month, and now it throws a 404. Or they're a new hire setting up an AI project for the first time and the documentation they're following looks nothing like what they see on screen. Sound familiar?
Microsoft Foundry is a major architectural consolidation. What used to be scattered across Azure AI Studio, Azure AI Foundry (classic), Azure OpenAI, and Azure AI Services has been pulled together into a single unified platform. That's great news for teams managing AI at scale. But it also means a lot of things moved, got renamed, or changed behavior , and the error messages you get when something goes wrong rarely explain why it went wrong.
Here's the core of what changed and why it's tripping people up:
- The portal split. There's now a new Foundry portal and a legacy "Foundry (classic)" portal. If you're in the wrong one, your resources look missing, they're not, they're just in the other view. Hub-based projects from the classic portal aren't visible in the new portal by default.
- The resource model changed. The old setup was a combination of a Hub resource, an Azure OpenAI resource, and an Azure AI Services resource, sometimes three separate things you had to wire together. Microsoft Foundry collapses these into a single Foundry resource with model projects underneath it. If you're still trying to create the old-style architecture, you'll hit permission errors and missing options.
- The Agent API changed. If you built anything on the Assistants API (what Microsoft now calls Agents v0.5 or v1), you're going to hit breaking changes. The new platform uses the Responses API (Agents v2), with entirely different terminology: Conversations instead of Threads, Items instead of Messages, Responses instead of Runs, and Agent Versions instead of Assistants. Your old SDK calls won't map cleanly.
- API versioning changed. The old pattern used monthly
api-versionquery parameters. The new stable routes follow a/openai/v1/path structure. Scripts that hard-coded the old versioning pattern simply stop working without a clear error explaining the versioning model changed. - RBAC requirements shifted. Creating a Foundry resource now requires specific roles, Azure Account AI Owner or Azure AI Owner at the subscription or resource group level. If you or a team member has a role that worked under the old setup, it may not be sufficient now.
None of this is your fault. The platform evolved fast and the migration path isn't always obvious. This guide walks you through every layer, from the portal toggle that fixes 40% of "missing resource" complaints, all the way to enterprise-level RBAC and API versioning troubleshooting.
Before you dig in: Browse all Microsoft fix guides →, if you're dealing with a related Azure permissions or subscription issue, there's likely a dedicated guide there too.
The Quick Fix, Try This First
If you opened the Microsoft Foundry portal and your projects or resources aren't visible, there's a very good chance this is a one-second fix. Look at the top banner of the portal page. You're looking for a toggle labeled "New Foundry". If that toggle is set to off, you're looking at the Foundry (classic) view, which shows the old hub-based architecture. Flip it to on and the new portal experience loads, including your Foundry projects under the new resource model.
Here's what to do, step by step:
- Navigate to ai.azure.com and sign in with your Azure account.
- Look at the top banner. If you see "New Foundry" with a toggle, make sure it's turned on.
- Once the new portal loads, your project name should appear in the upper-left corner of most pages.
- If you see a list of projects instead of landing directly on one, select the project you want to work with, this brings you to the Home page with that project in focus.
- To switch projects, select the project name in the upper-left corner, then choose from recent projects or select "View all projects" to see everything.
That's it for the most common case. If your resource still isn't appearing after switching to the new portal, it's likely a hub-based project that lives in Foundry (classic), not the new Foundry resource model. To find those, select the project name in the upper-left corner, then select "View all resources". A new browser tab opens the Foundry (classic) portal where those hub-based projects live.
One more thing: if you have multiple projects under the same Foundry resource, only the default project shows up in the new Foundry portal. To identify which project is the default, check the Foundry (classic) portal, the default is marked with "(default)" next to its name. You can't change the default project from the new portal; you'd need to manage that through the classic portal.
If you're coming from Azure OpenAI, the best news here is that you don't have to start from scratch. Microsoft Foundry supports upgrading an existing Azure OpenAI resource to a Foundry resource, and critically, your existing endpoint URL, API keys, and current resource state are all preserved through the upgrade. You don't need to update your application's connection strings.
To upgrade an existing Azure OpenAI resource:
- Sign in to the Azure portal (portal.azure.com).
- Navigate to your existing Azure OpenAI resource.
- In the resource blade, look for the "Upgrade to Foundry" option, it appears in the overview or the notification banner at the top of the resource page.
- Follow the guided upgrade wizard. It will confirm that your endpoint, API keys, and deployments carry over.
- After the upgrade, your resource will appear in the new Foundry portal under its associated project.
If you're creating a brand new Foundry resource instead of upgrading:
- In the Foundry portal, select "+ New project" or use the "Create a project" quickstart.
- You'll be prompted to create or attach a Foundry resource. The new resource model is a single Foundry resource, not the old Hub + Azure OpenAI + Azure AI Services triple-resource setup.
- Select your Azure subscription and resource group. Make sure your account has the Azure Account AI Owner or Azure AI Owner role on the subscription or resource group. Without this, the resource creation will fail at the permissions check.
- Name your project and deploy a model to make it operational.
If the upgrade option isn't visible on your Azure OpenAI resource, check whether the resource is in a region where Foundry is available, not all regions have full Foundry support yet. The official region support page for Microsoft Foundry lists current availability.
You know it worked when: Your project appears in the new Foundry portal with the project name showing in the upper-left corner, and your existing deployments are visible under the "Models" section without requiring redeployment.
This is the issue I see most often in enterprise scenarios, and it's the one that generates the most confused support tickets. A developer tries to create a Foundry resource or add a deployment, gets a generic "permission denied" or "insufficient privileges" error, and assumes something is wrong with their account. Usually the problem is a specific role gap.
Microsoft Foundry uses a centralized role-based access control model. All networking, policies, and access are managed under a single Azure resource provider namespace, which is different from the old model where you might have had separate role assignments across the Hub, Azure OpenAI, and AI Services resources.
Here's what role you need for each scenario:
- Creating a Foundry resource (for yourself): You need Azure Account AI Owner or Azure AI Owner at the subscription or resource group level.
- Creating a project for a team (with role assignments): You need Owner role, specifically a role that allows you to complete role assignments. The AI Owner role alone isn't enough for this because creating role assignments requires additional permissions.
- Building and deploying models: Contributor-level access to the Foundry project is typically sufficient after initial setup.
To check and assign roles:
- Go to the Azure portal and open your subscription or resource group.
- Select "Access control (IAM)" from the left menu.
- Click "+ Add" → "Add role assignment".
- Search for "Azure AI Owner" or "Owner" depending on what the team member needs.
- Assign it to the user's Azure account principal.
Role propagation in Azure can take up to 10 minutes. If the user still can't create resources after the assignment, have them sign out and back in to force a token refresh.
You know it worked when: The team member can open the Foundry portal, see the project list, and complete resource creation without an authorization error.
If you have existing Python or JavaScript code that uses the old suite of Azure AI packages, things like azure-ai-inference, azure-ai-generative, azure-ai-ml, or the AzureOpenAI() constructor pointed at five different endpoints, you're going to need to update your SDK approach. The new pattern is significantly cleaner: one package, one endpoint.
The new SDK is azure-ai-projects 2.x. It exposes a unified project client that you initialize with your single Foundry project endpoint. You also use the standard OpenAI() client pointed at that same project endpoint, no more wiring separate clients to separate Azure service URLs.
Install the new package:
pip install azure-ai-projects>=2.0.0 openaiBasic client initialization in Python now looks like this:
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
client = AIProjectClient(
endpoint="https://<your-project-name>.services.ai.azure.com/api/projects/<project-id>",
credential=DefaultAzureCredential()
)
And to use the OpenAI-compatible interface through the same project endpoint:
from openai import OpenAI
openai_client = OpenAI(
base_url="https://<your-project-name>.services.ai.azure.com/openai/v1/",
api_key="<your-api-key>"
)
Notice the new stable route format: /openai/v1/. This replaces the old monthly api-version query parameter pattern like ?api-version=2024-02-01. If your existing code appends those date-based version strings to a different base URL, that's almost certainly why you're getting 404s or "route not found" errors.
For JavaScript/TypeScript, the equivalent package is currently in preview, check the official Microsoft Foundry SDK docs for the latest package name before installing.
You know it worked when: Your project client initializes without an authentication error, and a simple chat completion call returns a valid response through the /openai/v1/ route.
This step is for anyone who built agents on top of the Assistants API, which Microsoft now labels as Agents v0.5 or v1 in the evolution table. The Responses API (Agents v2) is the current standard in Microsoft Foundry, and the terminology has changed completely. If you're sending API calls that reference Threads, Runs, or Assistants objects, you're hitting the old agent model.
Here's the direct mapping of old concepts to new ones:
| Old (Assistants API) | New (Responses API) |
|---|---|
| Threads | Conversations |
| Messages | Items |
| Runs | Responses |
| Assistants | Agent Versions |
The Responses API endpoint follows the new stable route format. Where you previously might have called:
POST /openai/deployments/{deployment-id}/assistants/threads
?api-version=2024-05-01-previewYou now work with the Responses API through the unified project endpoint. The exact routes are documented in the Microsoft Foundry API reference. The key behavioral difference: the Responses API is stateless by design in a way that maps more cleanly to modern agentic patterns. Conversations and their Items are managed differently from the old thread model.
For teams with significant existing code on the Assistants API: don't try to refactor everything at once. The Foundry (classic) portal still supports access to hub-based projects that may be running on the older API. You can run both in parallel while you migrate agent by agent. The official guidance is that new investments are focused on the new Foundry portal and Responses API, so the migration is forward-only, but you have time to do it methodically.
When writing new agents with the Responses API, use the azure-ai-projects 2.x SDK and its agent module. The SDK abstracts most of the Conversations/Items/Responses model so you don't have to manage raw HTTP calls for standard patterns.
You know it worked when: Your agent creates a new Conversation object successfully and returns a Response object (not a Run) after the first turn, without any "deprecated endpoint" or "route not found" error.
Here's a situation that trips up a lot of teams doing an incremental migration: you created projects under the old hub-based architecture in Azure AI Studio or Foundry (classic), and now they're completely invisible in the new Foundry portal. Nobody deleted them. They're fine. They're just in a different place.
The new Foundry portal only displays the default project for each Foundry resource. Hub-based projects, those created under the old Hub + Azure OpenAI + Azure AI Services model, don't appear in the new portal at all. You need the Foundry (classic) portal to work with them.
Here's how to get there:
- In the new Foundry portal, select the project name in the upper-left corner.
- Select "View all resources".
- A new browser tab opens the Foundry (classic) portal (the old ai.azure.com experience).
- From there, you can see and work with all your hub-based projects.
- To identify the default project for a Foundry resource, look for the "(default)" label next to the project name in the classic portal. Only that project surfaces in the new portal's project list.
If you need to work with multiple projects under the same Foundry resource and want them accessible in the new portal, you have two options: accept that only the default project appears in the new portal and use the classic portal for the others, or migrate those hub-based projects to the new Foundry resource model. For most teams, the pragmatic path is to use the classic portal for existing hub-based work while building new projects in the new Foundry model.
One important note: when you're in the classic portal, switch to the Microsoft Foundry (classic) documentation set, the new docs don't cover hub-based project workflows and you'll find conflicting guidance if you try to mix the two.
You know it worked when: The Foundry (classic) portal shows your hub-based projects in the left navigation, and you can open and interact with them as before, deployments, connections, and all associated resources intact.
Advanced Troubleshooting
Disabling Preview Features in Enterprise Environments
If you're running Microsoft Foundry in a production environment, you probably don't want preview features enabled by default, preview capabilities come with no SLA guarantees and can change behavior between deployments. The platform gives you two ways to control this.
The first approach is Azure Policy integration. Microsoft Foundry has full Azure Policy support, meaning your organization's existing policy infrastructure can govern which Foundry features are accessible. If your security team or platform engineering team already manages Azure Policy definitions, you can extend those policies to block or audit the use of preview-flagged resources within Foundry projects. Work with your Azure Policy administrator to create a custom policy definition targeting the Foundry resource provider namespace.
The second approach is custom RBAC roles. You can create a custom role that explicitly excludes actions related to preview features. This is more surgical, it limits what individual users or service principals can do without affecting the entire subscription. The official Microsoft Foundry documentation covers the exact action strings you need to exclude in the role definition under "Disable preview features in Microsoft Foundry."
For tagging-based governance, you can also apply resource tags to Foundry resources and use Azure Policy to enforce that only tagged resources meeting your approval criteria can be used in specific resource groups. This is particularly useful for teams managing both development and production Foundry environments in the same subscription.
MCP and A2A Authentication Issues
Microsoft Foundry has full authentication support for MCP (Model Context Protocol) and A2A (Agent-to-Agent) patterns. If your multi-agent workflow is failing at the authentication layer, the most common cause is that the service principal or managed identity used by one agent doesn't have the correct Foundry project-level role. Each agent in a multi-agent setup needs its own identity with explicit access to the Foundry project it's operating in. Check your Foundry project's IAM settings and confirm that the calling agent's managed identity has at minimum Contributor access.
AI Gateway Integration
For teams routing Foundry API calls through Azure API Management (APIM) as an AI gateway, verify that the gateway's outbound policy is using the new /openai/v1/ route format rather than the old monthly-versioned path. APIM policies that were configured for Azure OpenAI's ?api-version= pattern will send malformed requests to the Foundry endpoint. Update the backend URL in your APIM policy to reflect the new stable route.
Monitoring with Built-in Observability
Microsoft Foundry includes real-time observability out of the box, you don't need to set up a separate Application Insights instance for basic tracing. In the Foundry portal, navigate to the Operate section to access built-in metrics, model tracking, and performance monitoring. If you're seeing unexplained latency spikes or error rate increases, start here before digging into logs. The Operate section also shows agents registered from other clouds, which is useful for cross-cloud debugging scenarios.
Escalate to Microsoft Support if: your Foundry resource upgrade from Azure OpenAI silently failed and you're in an inconsistent state where the resource shows both old and new API behaviors; your Azure Policy integration is blocking Foundry resource creation in a way that the policy UI doesn't explain; or you're experiencing authentication failures with MCP/A2A that persist after confirming RBAC assignments are correct. These are infrastructure-layer issues that Microsoft support engineers can resolve with backend access. For billing discrepancies between what the Foundry portal shows and what appears on your Azure invoice, open a billing support ticket, not a technical one.
Prevention & Best Practices
Getting Microsoft Foundry working is one thing. Keeping it working as the platform continues to evolve is another. I've watched teams solve their setup problems and then get caught flat-footed three months later when another API or portal change rolls out. Here's how to stay ahead of it.
Watch the "What's New" documentation page. Microsoft Foundry is an actively evolving platform. The official "What's new in Microsoft Foundry documentation?" page is updated regularly and is the earliest signal you'll get of upcoming changes. If your team has a weekly engineering sync, make it a habit to glance at this page, five minutes there can save hours of debugging later.
Pin your SDK versions in production. The azure-ai-projects package is at 2.x, and the JavaScript/TypeScript SDK is in preview. For production workloads, pin your package versions in your requirements.txt or package.json and have a deliberate upgrade process. Don't let your CI/CD pipeline pull the latest version automatically without validation. A minor version bump in an AI SDK can change how the client handles authentication or routing.
Use Foundry's built-in evaluations before going to production. The platform includes evaluation capabilities specifically designed for testing model and agent behavior at scale. Before you push a new agent version or model deployment to production, run evaluations in a staging Foundry project. This catches behavior regressions that unit tests typically miss.
Separate your development and production Foundry projects. They should be in different resource groups, ideally with different service principals and RBAC assignments. Development projects should have preview features enabled so your team can experiment. Production projects should have preview features blocked via Azure Policy. This separation also makes billing analysis much cleaner.
Document which projects are hub-based vs. new Foundry model. As you migrate over time, you'll inevitably have both architectures running. Keep an internal record (a simple wiki page is fine) noting which projects are still hub-based and living in Foundry (classic), and which have been migrated to the new Foundry resource model. When something breaks, this context tells you immediately which portal and which SDK patterns to check first.
- Bookmark both the new Foundry portal and the Foundry (classic) portal, you'll need both during any migration period
- Set up Azure Monitor alerts on your Foundry resource for authentication failure spikes, they often signal a role assignment lapsing or a service principal secret expiring
- Add the Microsoft Foundry "What's New" documentation page to your team's weekly reading list
- Pin
azure-ai-projectsandopenaipackage versions in your productionrequirements.txtand treat upgrades as intentional deployments, not automatic updates
Frequently Asked Questions
What exactly is Microsoft Foundry and how is it different from Azure OpenAI?
Microsoft Foundry is a unified Azure platform that consolidates Azure AI Studio, Azure OpenAI, and Azure AI Services into a single service under one resource provider. Azure OpenAI was a focused service for OpenAI model access, Foundry goes much broader: it adds multi-agent orchestration, a tool catalog with over 1,400 integrations, enterprise memory for agents, built-in evaluations and monitoring, and publishing capabilities to Microsoft 365, Teams, and containers. If you're coming from Azure OpenAI, the good news is you can upgrade your existing resource to a Foundry resource without losing your endpoint, API keys, or current state, the upgrade path preserves everything.
I'm coming from Azure OpenAI, do I need to change my API keys or endpoint URLs?
No, when you upgrade an existing Azure OpenAI resource to a Foundry resource, your endpoint URL and API keys are preserved. Your applications don't need to update their connection strings just to complete the upgrade. What you'll want to update over time is the SDK (switching from the old AzureOpenAI() constructor pattern to the unified azure-ai-projects 2.x client) and the API route format (from monthly api-version params to the new stable /openai/v1/ routes). But those are planned migration steps, not day-one requirements.
Why can't I see my old hub-based projects in the new Foundry portal?
Hub-based projects, those created in Azure AI Studio or the Foundry (classic) portal under the old Hub + Azure OpenAI + AI Services architecture, don't appear in the new Foundry portal. The new portal only shows the default project for each Foundry resource. To access hub-based projects, select the project name in the upper-left corner of the new portal, choose "View all resources," and a new tab will open the Foundry (classic) portal where those projects live. They haven't been deleted; they're just accessible through a different portal entry point.
What happened to Threads, Runs, and Assistants from the Assistants API?
These concepts still exist conceptually, but they've been renamed in the new Responses API (Agents v2). Threads are now Conversations, Messages are now Items, Runs are now Responses, and Assistants are now Agent Versions. This isn't just cosmetic, the Responses API has a different state model and endpoint structure. If you have code that calls the Assistants API directly (Agents v0.5 or v1), it will continue working through hub-based projects in Foundry (classic), but new development should use the Responses API. The official migration path is to rebuild agent logic using the azure-ai-projects 2.x SDK's agent module.
Does Microsoft Foundry cost money just to use the portal?
No, the platform itself is free to use and explore. Costs happen at the deployment level: when you deploy a model, run evaluations at scale, or consume API calls, those generate charges based on the underlying services you're consuming. Each product within Foundry (models, tools, AI toolchain features) has its own billing model. The platform doesn't charge a "platform fee" on top of that. To understand what you'll actually pay, look at the pricing for the specific Azure AI and Azure OpenAI model deployments you create, plus any associated storage or compute costs from underlying Azure services.
Who is Microsoft Foundry actually designed for, is it only for developers?
Microsoft Foundry is built for three distinct groups. Application developers who are building AI-powered products with agents, models, and tools are the primary audience, they get the SDKs, the agent builder, and the tool catalog. ML engineers and data scientists who fine-tune models, run evaluations, and manage deployments at scale get dedicated capabilities in the model management section. And IT administrators and platform engineers who need to govern AI resources, enforce policies, and manage access across teams get the Foundry Control Plane, Azure Policy integration, centralized RBAC, and the security and governance tooling. Each group has a different entry point into the platform but they all share the same underlying Foundry resource infrastructure.