Microsoft has given developers a firm deadline: migrate any application dependent on the Azure OpenAI Assistants API before August 26, 2026, or face service disruption. The retirement, confirmed this week in an official Microsoft Learn documentation update, marks the end of the preview-era feature that let developers build stateful, multi-tool AI assistants.
A separate, later retirement affects the broader Foundry Agent Service (classic) on March 31, 2027, but for teams whose code directly calls the Assistants API, the clock is ticking louder. Microsoft offers a migration guide and a partially automated tool to move workloads to the generally available Microsoft Foundry Agents service—though testing everything from authentication to persistence remains squarely the developer’s job.
What exactly is changing?
The Azure OpenAI Assistants API, which has lived as a classic, preview-era component inside Microsoft Foundry, is being switched off. The official documentation now carries a banner: “The Assistants API is deprecated and will be retired on August 26, 2026.” The recommended replacement is the Microsoft Foundry Agents service, a newer, enterprise-grade agent runtime that includes managed identity, multi-agent orchestration, and built-in tool integrations.
Crucially, not everything labeled “classic” dies on the same day. Foundry Agent Service (classic) itself retires later, on March 31, 2027. The earlier cutoff applies only when a workload relies on Assistants API-specific behaviors, objects, or infrastructure—assistants, threads, messages, runs, and the SDK packages around them. If your classic workload never touches those, you have until spring 2027 to move.
Microsoft’s migration tool can help translate Assistants API code into Foundry Agents code, but it does not replace rigorous application testing. Teams still need to verify identity, persistence, external actions, and production operations. The tool automates code conversion; it doesn’t automate validation.
What it means for you
The impact splits neatly along user profiles:
For home users and hobbyists
None. If you tinker with Azure OpenAI in a personal capacity but haven’t built production-grade applications on the Assistants API, this retirement doesn’t touch you. Even so, if you’ve been experimenting with early agent prototypes using classic tooling, now is the moment to pivot to Foundry Agents for any project you intend to keep running past next summer.
For developers and IT teams
If your organization has any code, scripts, notebooks, or scheduled jobs that call the Assistants API—whether through the REST API directly, the Azure OpenAI SDK, or community libraries—you must migrate before August 26, 2026. This includes:
- Applications that create assistants, threads, messages, or runs.
- Any polling or asynchronous processing built on runs.
- Internal tools, support bots, or data pipelines that lean on the stateful thread management of Assistants.
A single overlooked cron job or a dusty Jupyter notebook can still break after the cutoff. The retirement is a hard stop: API calls will simply fail.
For administrators and architects
You’ll need to inventory all Azure OpenAI resources, Foundry projects, and associated identities. Look not only at the main application but also at its periphery: CI/CD pipelines that spin up test assistants, data labeling scripts, or one-off utilities used by data science teams. Because the Assistants API has been scoped at the Azure OpenAI resource level, any user with access to that resource can create and modify assistants. That means discovery must span the whole resource, not just the “production” codebase.
How we got here
The Assistants API launched in preview back when Microsoft and OpenAI were racing to give developers more than just chat completions. It introduced persistent threads, automatic context management, and parallel tool calling— code interpreter, file search, and custom functions—all behind a single API. Developers could build copilot-like experiences without managing conversation state or context window trivia.
But the preview was always a stepping stone. Microsoft’s vision shifted toward a fully managed agent platform, culminating in the general availability of the Foundry Agent Service. That service brings features the old Assistants API lacks: native support for managed identities (no more embedding API keys), multi-agent collaboration, and deeper integration with Azure’s operational backbone—monitoring, governance, and policy enforcement.
In parallel, Microsoft rebranded and reorganized its AI developer surface, splitting the old “Foundry (classic)” portal from the new Foundry portal. The Assistants API got stuck in the classic side, technically still available but increasingly marginalized. The retirement announcement formalizes the end of that transitional era.
WindowsForum users have long debated the merits of this shift. Some praise the richer orchestration in Foundry Agents; others worry about the complexity of migrating working prototypes. Microsoft’s decision to give a full two years’ notice—rare by cloud service standards—suggests the company expects many teams to have nontrivial migration efforts.
What to do now
The migration isn’t a one-click operation, but Microsoft has provided a path. Here’s how to proceed.
1. Inventory your Assistants API dependencies
Start by searching your code repositories, deployment artifacts, and infrastructure-as-code files for keywords: assistant, assistants, thread, message, run, Azure OpenAI Assistants, and relevant SDK package names. Don’t stop at source code. Check:
- Scheduled jobs, workers, and cron tasks.
- Jupyter notebooks in shared drives.
- CI/CD pipeline definitions that spin up test resources.
- Configuration files and key vaults storing assistant IDs or thread IDs.
- Telemetry and app logs that might reveal hidden callers.
A match alone doesn’t mean an active production dependency; one team’s dead prototype is another’s latent outage. Verify by correlating with runtime traffic data. Create a simple spreadsheet for each workload: app name, owner, environments, APIs used, and evidence of recent activity.
2. Classify which deadline applies
If the workload calls the Assistants API in any capacity, the August 26, 2026 cutoff is your deadline. If it uses Foundry classic but has zero Assistants API footprint, you have until March 31, 2027—but don’t procrastinate; migrations at the last minute rarely go smoothly.
For workloads that straddle both (e.g., a classic project that uses the Assistants SDK only in one module), the earlier deadline governs that module. You can’t ignore the dependency just because the rest of the project is “classic.”
3. Prepare your target environment
Set up a non-production Foundry project for the migration. Install the current SDKs:
- For Python: pip install "azure-ai-projects>=2.3.0" azure-identity
- For .NET: dotnet add package Azure.AI.Projects; dotnet add package Azure.AI.Projects.Agents; dotnet add package Azure.AI.Extensions.OpenAId; dotnet add package Azure.Identity
Note the .NET list is longer; early missteps often involve missing packages. Record resolved versions in your lock file so CI and dev machines match. Authenticate locally with az login, but remember that production will use managed identities or service principals—test those separately.
4. Run the migration tool and review its output
Microsoft’s migration guide for your language will detail the tool. Apply it in this order:
- Branch your code.
- Back up configuration and data.
- Run the tool against a non-production workload.
- Review every changed file; don’t blindly accept patches.
- Fix build errors using the latest SDK docs.
- Document anything the tool missed (e.g., custom middleware, specialized thread handling).
- Build and run the result in your test Foundry project.
5. Test beyond “it compiled”
The tool converts code, but it can’t verify that your app still behaves correctly. A representative test should cover:
- Authentication: can the app obtain credentials without a developer logged in?
- Connection: does it reach the intended Foundry project?
- Agent configuration: are the right tools and instructions attached?
- Representative input/output: does a typical request return a correct, complete result?
- Restart: does the app still work after a restart, or does it lose state?
- Persistence: if your app stored conversation threads as Assistants API thread IDs, those IDs likely won’t work in Foundry Agents. You may need to store your own mapping or rehydrate conversations from your database.
- External actions: test each custom tool call, webhook, and function with real backends. A function that worked in Assistants might behave differently under the new agent runtime.
- Error handling: what happens when an external call times out? Are retries idempotent?
- Logging and monitoring: do logs still contain the correlation IDs your support team needs?
6. Execute a disciplined production migration
For each Assistants-dependent workload, follow these steps:
- Stop adding new features or dependencies that touch the old API.
- Capture a baseline: sample requests, expected responses, known edge cases.
- Complete the code migration and review.
- Update identity configuration, ensuring managed identity or service principal has proper access.
- Reconnect each external integration and test independently, then together.
- Deploy to staging with production-like networking and identity. Run acceptance tests.
- Cut over to production before August 26, 2026, with enough buffer for remediation. Don’t plan your first prod attempt for the retirement date.
7. Verify post-cutover and stay vigilant
After moving production traffic, check:
- Production identity works without a developer’s cached token.
- Requests reach the correct Foundry project.
- Restart the app and confirm it recovers.
- Test follow-up input to verify conversation continuity.
- Confirm retries don’t duplicate business actions.
- Inspect logs for accidental logging of secrets or sensitive prompt data.
- Scan scheduled jobs, notebooks, older clients, and secondary regions for remaining Assistants API traffic.
Watch DNS, network logs, and app telemetry for weeks afterward. Dormant features and monthly reports might not fire during a smoke test.
What if something breaks?
Common pitfalls and their fixes:
Authentication works locally but fails in production. Check which identity DefaultAzureCredential is picking. In a VM, it might be a managed identity; in a container, a pod identity or environment variable. Ensure that identity has Cognitive Services OpenAI User (or custom role) on the Foundry project, not just on the old Azure OpenAI resource.
SDK packages installed but code doesn’t build. Verify all required packages are present and versions match. For .NET, ensure you installed Azure.AI.Projects.Agents and Azure.AI.Extensions.OpenAId, not just the top-level Azure.AI.Projects. Rebuild in a clean environment to catch stale dependencies.
Basic requests work, external actions fail. Re-test the external service in isolation. Network rules, authentication tokens, or schema differences may have changed. Don’t assume a feature with the same name works identically.
Historical threads can’t be reopened. You probably stored only Assistants API thread IDs. Those IDs are not portable. You’ll need to either rebuild conversation context from your own database or, if the history is irreplaceable, design a bridge that replays old messages through the new agent. Microsoft does not officially support reusing old IDs directly.
Traffic still hits the old API after migration. Hunt down every possible caller: stale worker roles, old container images, regional deployments you forgot, cron jobs, and even support scripts. Repository searches don’t catch running binaries.
Outlook
Microsoft’s move signals the maturation of its agent platform. Foundry Agents isn’t just a rename; it’s a pivot toward production-grade, identity-aware, multi-agent systems—the kind that enterprises increasingly demand. The two-year notice is generous by cloud standards, but don’t mistake it for a lack of urgency. The complexity of functional AI agents means migration often surfaces subtle regressions: a tool authentication change, a thread state mismatch, an unintentional loss of customer conversation history.
Watch for Microsoft to iterate on the migration tooling, especially as feedback rolls in. The company’s documentation promises “supported” migration paths but won’t spoon-feed custom logic. If your application does anything more than basic conversation—and most do—you’ll need hands-on engineering time.
For developers already on Foundry Agents, the Assistants API retirement is a distant alarm. For the rest, it’s time to open the codebase and start searching.