Azure Assistants API retired: migrating to Foundry Agents

On 26 August 2026 the Azure OpenAI Assistants API reached its retirement date. Microsoft's documentation now states it plainly: "The Assistants API is retired. Use the generally available Microsoft Foundry Agents service." Production code that still creates assistants, appends messages to threads and polls runs is calling a service Microsoft no longer supports. The date had been on the calendar since early in the year, but plenty of Azure estates in Sweden still carry assistants built during the 2024 and 2025 copilot wave: internal Q&A bots on file search, analyst tools on code interpreter, customer-facing helpers wired up through function calling. If any of those are yours, this is the migration week, and there is a second deadline already behind it. The classic Foundry Agent Service, which was built on top of the same Assistants infrastructure, is itself deprecated with retirement scheduled for 31 March 2027.

Two deadlines, one direction of travel

It helps to be precise about what retired this week and what retires next year, because the two are easy to conflate.

26 August 2026: Azure OpenAI Assistants API. The classic OpenAI-style surface: assistants, threads, messages, runs and run steps, reached via the OpenAI client's beta assistants endpoints against an Azure OpenAI resource. Microsoft's docs mark it retired and point every reader at the Foundry Agents migration guide.
31 March 2027: Foundry Agent Service (classic). The Azure agents layer reached through the azure-ai-agents SDK and its AgentsClient. It exposed the same thread-and-run model because it was built on Assistants infrastructure underneath. Microsoft staff confirmed the March 2027 retirement date on the Q&A forum in July, and recommended starting migration well before it.

The dependency between the two is the uncomfortable part. Classic Foundry agents sit on Assistants infrastructure, so a workload on the classic Agent Service is not safely parked until March 2027; it is running on a foundation whose public API was retired this week. Microsoft has not published a statement that classic agent workloads break on the August date, but the risk posture is clear enough that the sensible reading is the same for both groups: the destination is the new Foundry Agent Service, built on the Responses API, and the migration effort is nearly identical whichever starting point you have. Do it once, now, and both deadlines stop mattering.

The new model: agents, conversations, responses

The new Foundry Agent Service replaces the Assistants object model with three primitives, and Microsoft's migration guide gives a clean mapping.

Threads become conversations. A thread stored messages server-side. A conversation stores items: messages, tool calls, tool outputs and other data, which makes the stored context richer than a message list.
Runs become responses. A run was an asynchronous process you polled until it left the queued and in_progress states. A response is a single call: you provide input items (or point at a conversation for context) and get output items back. Tool call loops are explicitly managed rather than hidden inside run state, and background mode covers long-running work with durable streams that survive disconnects.
Assistants become versioned agents. Instead of create_agent or beta.assistants.create, you call create_version with a structured definition carrying explicit kind, model and instructions fields. Every change produces a new agent version, which finally gives you a real answer to "which prompt was live in production last Tuesday?"

One structural change deserves special attention because it breaks the mental model most Assistants code was written with: the new API splits work across two clients. The project client (AIProjectClient from azure-ai-projects 2.3.0 or later in Python) handles agent creation and versioning. Conversations and responses go through an OpenAI client you obtain from the project, via get_openai_client() in Python or getOpenAIClient() in JavaScript. Code that funnelled everything through one client object needs restructuring, not just renamed method calls.

What the change looks like in code

The before and after, condensed from Microsoft's migration guide. First the retired pattern:

# RETIRED: Assistants API pattern
assistant = client.beta.assistants.create(
    model="gpt-4.1",
    name="my-assistant",
    instructions="You politely help with math questions.",
    tools=[{"type": "code_interpreter"}],
)
thread = client.agents.threads.create(
    messages=[{"role": "user", "content": "..."}],
)
run = project_client.agents.runs.create(
    thread_id=thread.id, agent_id=assistant.id,
)
while run.status in ("queued", "in_progress"):
    time.sleep(1)
    run = project_client.agents.runs.get(
        thread_id=thread.id, run_id=run.id)

And the replacement:

# CURRENT: Foundry Agent Service on the Responses API
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeInterpreterTool, PromptAgentDefinition,
)

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions="You politely help with math questions.",
        tools=[CodeInterpreterTool()],
    ),
)

conversation = openai.conversations.create(
    items=[{"type": "message", "role": "user",
            "content": "..."}],
)
response = openai.responses.create(
    input="Draw a graph for a line with slope 4.",
    conversation=conversation.id,
    extra_body={"agent_reference": {
        "name": "my-agent", "type": "agent_reference"}},
)

Notice what disappeared: the polling loop. The response comes back as a completed object with output items, token usage and the conversation reference in one shot. Follow-up turns either add items to the conversation with conversations.items.create() or simply issue another responses.create() against the same conversation ID.

Tool availability: check before you assume

Most Assistants-era tools carry over, several arrive upgraded, and a few classic tools do not exist in the new service. From the migration guide's availability table, the deltas that matter:

Carried over at GA: Code Interpreter, File Search, Function calling, Azure AI Search, OpenAPI tools, Grounding with Bing Search.
Upgraded: MCP tool calling moves from public preview in classic to GA in the new service. Web Search and Image Generation are new, with Web Search at GA.
Gone: Azure Functions tool. Available at GA in classic, not present in the new service. Workloads that invoked Azure Functions as an agent tool need rework, typically to a Function-calling wrapper or an OpenAPI tool fronting the Function's HTTP trigger.
Replaced: Connected Agents gives way to the Agent-to-Agent (A2A) tool in public preview. The Deep Research tool is gone; Microsoft's recommendation is the Deep Research model combined with the Web Search tool.

The Azure Functions gap is the one most likely to bite Swedish enterprise estates, because that tool was a convenient way to reach internal systems without exposing an API surface. Budget rework time for it explicitly rather than discovering it during testing.

A step-by-step migration plan

Triage first. If something user-facing is failing right now because it called the retired API this week, do not start with a clean architectural migration. Get a minimal Responses API path serving traffic, then do the structured work below. The new API's stateless-friendly response calls make a thin emergency shim genuinely feasible: one responses.create() per turn with your own context management will hold the line while you migrate properly.

1. Inventory every caller. Search your codebases for beta.assistants, threads.create, runs.create and AgentsClient. Check Azure OpenAI resource metrics and diagnostic logs for traffic against assistants endpoints you did not know about. Shadow copilots built by one team in 2024 are exactly what this retirement flushes out.
2. Classify each workload by starting point. Pure Assistants API callers follow the assistants-to-agents path. Classic Foundry agents follow the classic-to-new path plus a tool availability check. Microsoft's guide has a distinct route for each, and the minimum bar is the same four steps: map your tools, migrate the agent definition, replace threads and runs with conversations and responses, then verify.
3. Stand up a Foundry project. The new service hangs off a Microsoft Foundry project rather than a bare Azure OpenAI resource. Endpoint format: https://resource_name.services.ai.azure.com/api/projects/project_name, authenticated with Entra ID via DefaultAzureCredential.
4. Run the automated migration tool on candidates. Microsoft ships a migration tool (aka.ms/agent/migrate/tool) that rewrites code constructs: agent definitions, thread creation, message creation, run creation. Treat its output as a first draft and review the generated assets, especially around error handling and streaming.
5. Plan for the state you will not get back. The migration tool does not migrate state data: past runs, threads and messages stay in the old format. If conversation history has business or regulatory value, export what you still can and decide deliberately whether users restart with fresh conversations. New state accumulates in the new format from the first call.
6. Rework the tool gaps. Azure Functions tool users move to function calling or OpenAPI tools. Connected Agents users evaluate A2A. Deep Research users test the model-plus-Web-Search combination against their old output quality before promising parity to stakeholders.
7. Verify like it is a new system. Microsoft's own guidance calls out state, tool calls, outputs and error handling as the verification surface. Add token accounting: the response object reports input_tokens and output_tokens with cached-token detail, so rebase your cost dashboards on the new fields.
8. Schedule the classic Agent Service exit now. If step 2 found classic Foundry agents, put their migration in the plan with a completion date well before 31 March 2027. The work is the same shape as what you are doing this month; doing it in the same programme is cheaper than reopening it next year.

The Swedish and EU angle

Data control improves, if you use it. Under the Assistants API, assistants, threads, messages and files were scoped to the Azure OpenAI resource, and anyone with resource or key access could read all of them. Microsoft's own docs recommended layering your authorization on top. The new service is built for single-tenant storage with the option to bring your own Azure Cosmos DB for agent state. For organisations answering GDPR Article 30 records or internal data-classification reviews, that is a materially better story: conversation state in a Cosmos DB account you own, in the Swedish or EU region you chose, under your own encryption and retention policies. Treat the migration as the moment to adopt it, not as a like-for-like port.

The retirement itself is a compliance event. If retired conversation data contained personal data, your records of processing described a store that is now frozen in a legacy format. Update the records, execute retention decisions on exported history, and document the deletion or migration path. Auditors respond far better to "we migrated and disposed of legacy state deliberately" than to a shrug about where old threads went.

Procurement and vendor management should log the lesson. The Assistants API went from launch to retirement inside roughly three years, and the classic Agent Service that replaced it is retiring seven months later. For upphandling teams writing requirements for AI platforms, this argues for contract language about API lifecycle commitments, and for architecture reviews that keep agent logic behind your own abstraction layer. Teams that wrapped their assistant calls in an internal interface are migrating one adapter this month. Teams that scattered beta.assistants calls across services are migrating everything.

Versioning helps with the EU AI Act homework. The GPAI transparency obligations that started applying in August 2025, and the documentation practices many Swedish enterprises are building ahead of the high-risk deadlines, all reward knowing exactly which instructions and tools an AI system ran with at a given time. Versioned agent definitions with explicit kind, model and instructions fields give you that audit trail natively, where the mutable assistant objects of the old API did not.

Takeaways

The Azure OpenAI Assistants API retired on 26 August 2026. Code still calling it is out of support now, not at some future date.
The classic Foundry Agent Service retires 31 March 2027, and it sits on Assistants infrastructure. Migrate both workload types in one programme.
The destination is the new Foundry Agent Service on the Responses API: conversations replace threads, responses replace runs and polling, create_version replaces assistant creation.
Check the tool table before estimating: Azure Functions tool is gone, Connected Agents and Deep Research are replaced, MCP is now GA.
The migration tool rewrites code, not state. Past threads and messages do not come along; export and decide their fate deliberately.
Use the migration to adopt bring-your-own Cosmos DB state storage and agent versioning. Both strengthen your GDPR and AI Act documentation position.