Assistants API Retires August 26, 2026: Migrate Foundry Agents

If a Foundry Agent Service (classic) workload depends on Assistants API behavior, migrate that dependency before the Assistants API retires on August 26, 2026; classic itself retires later, on March 31, 2027, and does not have an earlier platform-wide migration cutoff.

Two Retirement Dates, One Dependency-Based Decision​

The documented dates apply to different components:

• August 26, 2026: Assistants API retirement.
• March 31, 2027: Foundry Agent Service (classic) retirement.

The earlier date matters only when a workload uses Assistants API behavior or infrastructure derived from Azure OpenAI Assistants. A classic workload without that dependency should be assessed against the classic service lifecycle separately.
Microsoft provides a documented migration guide and migration tool that can automate parts of moving from Assistants API to Foundry Agents. The tool does not eliminate application testing. Teams still need to validate identity, persistence, external actions, and production operations according to their own architecture and requirements.
WindowsForum user discussions about Foundry Agent Service general availability, multi-agent orchestration, and the broader “Agent Factory” model consistently describe a transition from prototype-style AI applications toward managed agents that can reason, act, and collaborate. Another WindowsForum discussion focuses on the practical challenge of moving from a working prototype to an enterprise-ready deployment. For this migration, that means identifying the actual dependency first rather than assigning every classic workload the same deadline.
Use this decision tree:

1. Search for Assistants API usage. Look for assistants, threads, messages, runs, related SDK calls, or infrastructure originally built around Azure OpenAI Assistants.
2. If that usage is present, target production cutover before August 26, 2026. Allow time for testing and remediation before retirement.
3. If it is absent, assess the Foundry Agent Service (classic) lifecycle separately. Do not assign the Assistants API deadline merely because the workload is labeled “classic.”
4. Use Microsoft’s migration guide and tool to move applicable workloads to Foundry Agent Service. Treat the automated result as a starting point that still requires application-specific verification.

Step 1: Confirm the Workload’s Actual Dependency​

Do not classify a workload solely by the product name displayed in the Azure portal, an invoice, or an architecture diagram. Inspect the running application, deployed packages, infrastructure, and telemetry.
Search repositories and deployment artifacts for:

• assistant, assistants, thread, threads, message, messages, run, and runs
• Azure OpenAI Assistants SDK packages or REST routes
• Stored assistant, thread, message, or run identifiers
• Polling or asynchronous processing built around runs
• Infrastructure modules created specifically for Azure OpenAI Assistants
• Scheduled jobs, notebooks, workers, or support tools that call the old API
• Test fixtures and configuration files containing old endpoints
• Shared wrappers that may hide Assistants API calls from the main application

A text match is not proof of an active dependency. Determine whether each result belongs to production code, an inactive test, historical documentation, or an unrelated feature.
Create a concise workload record containing:

1. Application and owner.
2. Production and nonproduction environments.
3. Current Azure project or resource.
4. SDKs and APIs used by the deployed build.
5. Stored service-generated identifiers.
6. External systems called during processing.
7. Authentication methods used locally, in CI/CD, and in production.
8. Evidence of recent traffic.
9. Migration owner and planned completion date.

Use runtime telemetry where possible. Source searches cannot identify an old binary, notebook, secondary deployment, or scheduled process that remains active outside the primary repository.

Step 2: Prepare the Target Environment​

Before running installation commands, confirm that you have:

• An Azure subscription
• A Microsoft Foundry project
• The appropriate language SDK
• The corresponding Azure identity package

Use a nonproduction project for the initial migration and validation work.
For Python, install Azure AI Projects and Azure Identity:
pip install "azure-ai-projects>=2.3.0" azure-identity
For .NET, install all packages listed in the supplied migration setup:

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

Do not add a prerelease flag unless Microsoft’s current documentation for the version you are intentionally testing requires it.
For local development, authenticate with the Azure CLI:
az login
Applications can use DefaultAzureCredential to obtain credentials through the Azure identity chain rather than embedding secrets in source code.
Local authentication and production authentication must be tested separately. A successful az login demonstrates that the developer’s interactive identity works; it does not prove that a managed identity, service principal, hosted application, container, or build agent has access to the Foundry project.
Record the resolved package versions in the lock file or build output, and reproduce the same environment in CI. This avoids confusing migration defects with differences between developer and build environments.

Step 3: Run Microsoft’s Migration Tool​

Follow Microsoft’s current migration guide for the language and SDK used by the application. Use the documented migration tool when the workload is based on Assistants API objects or behavior that the tool supports.
Apply it in this order:

1. Create a branch or otherwise preserve the current application source.
2. Back up application-owned configuration and data needed for testing.
3. Run the tool against a representative nonproduction workload.
4. Review every generated or modified file.
5. Resolve build errors using the current Microsoft SDK documentation.
6. Record anything the tool did not migrate.
7. Build and run the result in the nonproduction Foundry project.

Do not treat successful conversion or compilation as production acceptance. Automation can help transform the integration, but it cannot prove that the organization’s identity model, stored history, external systems, monitoring, or operational procedures behave correctly.

Step 4: Validate One Representative Workload​

Start with one workload that exercises the application’s important paths. Confirm that the application can:

1. Authenticate using the identity intended for the test environment.
2. Connect to the intended Foundry project.
3. Use the required agent configuration.
4. Submit representative input.
5. Receive and process a result.
6. Emit diagnostics sufficient to investigate a failure.
7. Operate correctly after an application restart.

Then select additional validation checks based on the application’s design. These are organization-specific checks, not universal Microsoft migration requirements:

• Whether conversation or task state must persist
• Whether historical records must remain visible
• Whether processing continues after the original request
• Whether the agent calls tools, webhooks, or external APIs
• Whether retries could repeat a business action
• Whether prompts, responses, or action records have retention rules
• Whether support teams require correlation IDs or audit data
• Whether multiple regions or secondary deployments are active

WindowsForum user reports about enterprise agent orchestration emphasize that agents may interact with other systems rather than merely return text. Where that applies, test the complete application path. A similar model response does not establish that persistence, actions, authorization, or failure handling remain equivalent.

Step 5: Migrate in an Exact Order​

For each Assistants-dependent workload, use the following sequence:

1. Stop adding new Assistants API dependencies.
   Keep the migration scope from growing while conversion is underway.
2. Capture a baseline.
   Save representative inputs, accepted outputs, known failures, and application telemetry needed for comparison.
3. Run or apply the documented migration path.
   Use Microsoft’s guide and tool where supported, then review the resulting code and configuration.
4. Update identity configuration.
   Verify the intended identities and access assignments in development, CI/CD, staging, and production.
5. Review persistence.
   Determine whether the old application stored complete business data or only service-generated IDs. Do not assume old IDs can be used directly by the target service.
6. Reconnect external actions.
   Test each required integration independently before testing it through the migrated application.
7. Update organization-specific operations.
   Revise only the dashboards, alerts, runbooks, support procedures, and retention controls the workload actually needs.
8. Deploy to staging.
   Use production-like identity and networking rather than relying exclusively on a developer workstation.
9. Complete acceptance testing.
   Obtain the approvals required by the organization and application owner.
10. Cut over with remediation time remaining.
    For Assistants-dependent workloads, complete the production move before August 26, 2026 rather than scheduling the first production attempt on the retirement date.

If historical continuity is required, keep an application-owned association between old and new records after confirming that the design meets the organization’s audit, privacy, and retention requirements. Do not treat unlike service-generated identifiers as interchangeable.

Step 6: Plan Cutover and Recovery​

Rollback depends on the application architecture and the continued availability of its dependencies. Test it instead of assuming it will work.
Before cutover:

1. Retain the previous deployable application build.
2. Back up application-owned data and configuration required for recovery.
3. Record which production route is active.
4. Decide how records created after cutover will be handled if the application rolls back.
5. Protect external actions against duplication during retries or route changes.
6. Keep old resources until their operational, audit, and retention value has been reviewed.
7. Document the conditions that trigger rollback and who can authorize it.

Do not assume that deleting an old server-side resource has a uniform effect. The consequences depend on what the application stores, references, or retrieves. Follow Microsoft’s current resource documentation and test the application-specific result.

Step 7: Verify Production​

After cutover, verify the deployed application rather than relying only on staging results.

1. Confirm that the production identity authenticates without a developer’s credentials.
2. Confirm that requests reach the intended Foundry project.
3. Restart the application and repeat a representative request.
4. Test follow-up input if the product requires continuing context.
5. Test each required external action with valid input.
6. Test authorization failures, timeouts, invalid input, and dependency failures that matter to the workload.
7. Confirm that retries do not duplicate business actions.
8. Check that logs contain the correlation data needed for support.
9. Confirm that secrets and sensitive content are not unintentionally logged.
10. Inspect scheduled jobs, workers, notebooks, older clients, secondary deployments, and regions for remaining Assistants API traffic.
11. Confirm that the application’s required dashboards and alerts observe the new path.
12. Record application-owner acceptance.

Continue monitoring after the initial verification. Dormant jobs, low-traffic features, and monthly processes may not appear during a smoke test.

Troubleshooting​

Authentication works locally but fails in production​

Determine which identity DefaultAzureCredential selects in each environment. Check the production identity’s project access, role assignments, tenant configuration, and network path. Do not copy a developer credential into production as a workaround.

Packages install, but the sample does not build or run​

Inspect the resolved package versions, runtime version, imports or namespaces, and lock file. Rebuild in a clean environment to expose stale dependencies. Compare the application with Microsoft’s documentation for the installed SDK release.
For .NET, confirm that all four listed packages are present, including Azure.AI.Projects.Agents and Azure.AI.Extensions.OpenAId, rather than installing only Azure AI Projects and Azure Identity.

Basic requests work, but an external action fails​

Test the external service independently. Verify its authentication, network access, request schema, timeout behavior, and error responses. A similarly named capability in the target environment does not establish identical configuration or behavior.

Historical sessions cannot be reopened​

Determine whether the application retained the underlying historical content or only old service-generated identifiers. Do not insert an old identifier into the new integration unless Microsoft explicitly documents that operation. Where permitted, present history from application-owned records or use a reviewed transformation process.

Traffic still reaches the Assistants API​

Check scheduled tasks, queues, notebooks, worker deployments, old clients, support utilities, secondary regions, and previous application versions. Compare source-code findings with current telemetry because repository searches cannot reveal every running binary.

The migration tool completes, but behavior differs​

Review the areas outside the tool’s limited role: identity selection, persisted application data, external actions, environment configuration, and production operations. Use the baseline captured before migration to isolate whether the difference comes from code conversion, configuration, permissions, or an external dependency.

Frequently Asked Questions​

Does Foundry Agent Service (classic) retire before the Assistants API?​

No. The Assistants API retires on August 26, 2026, while Foundry Agent Service (classic) retires on March 31, 2027.

Does every classic workload need to migrate by August 26, 2026?​

No. That deadline applies when the workload depends on Assistants API behavior. If it does not, assess the classic-service lifecycle separately.

Why act before the classic retirement date?​

An application associated with classic may still depend on the earlier-retiring Assistants API. The March 31, 2027 classic date does not extend the lifetime of that API.

Can Microsoft’s migration tool complete the entire migration?​

It can automate migration from Assistants API to Agents where supported. Teams still need to test identity, persistence, external actions, and production operations relevant to their application.

Can old service-generated IDs be reused?​

Do not assume so. Preserve them when needed for historical or audit purposes, follow Microsoft’s documented migration path, and use an application-owned association if continuity is required and the design has been reviewed.

Is installing the new SDK enough?​

No. SDK installation prepares the development environment. An Assistants-dependent application still requires code migration and application-specific validation before production cutover.

What internal deadline should an organization use?​

For Assistants-dependent workloads, choose a production deadline before August 26, 2026 that leaves time for testing and corrections. For workloads without that dependency, plan separately against the Foundry Agent Service (classic) lifecycle and Microsoft’s current guidance.

---

References​

1. Primary source: learn.microsoft.com
   
   Loading…

   learn.microsoft.com
2. Primary source: WindowsForum
   
   Loading…

   windowsforum.com