Semantic Kernel or Microsoft Agent Framework: what to do with an existing .NET application

I earned the AZ-2005 Applied Skills credential, which centres on Semantic Kernel, on 8 April 2026. Five days earlier, Microsoft had shipped version 1.0 of its successor. The timing sums up the situation: some of the .NET applications that embed AI today rest on a framework whose replacement Microsoft has already named. That is no reason to panic or to rewrite everything. It is a reason to know exactly what changes, what stays, and when to act.

This guide is for teams with a .NET application in production, or in development, that has Semantic Kernel inside it. It is kept up to date: the revision date sits at the top of the page.

Where the two frameworks stand

Two public commitments from Microsoft frame what comes next. Semantic Kernel 1.x remains supported, with critical bug and security fixes, for at least one year after Agent Framework leaves preview. And new feature development now happens mainly in Agent Framework.

In practice: a Semantic Kernel application is not about to stop working. It is about to stop moving forward. Guaranteed support runs until April 2027 at the earliest, and nothing guarantees it beyond that.

What does not change

This is the part the announcements talk about least, and it is the most reassuring one for an existing application.

Your business code. Services, rules, validations, data access through Entity Framework or SQL, permission checks: none of it depends on the orchestration framework. If your AI integration was done cleanly, the AI calls your business code through functions exposed as tools, and that code does not change.

The shared .NET abstractions. Microsoft lifted the basic building blocks out of Semantic Kernel into standalone libraries of the .NET ecosystem: Microsoft.Extensions.AI (the IChatClient interface to talk to a model, IEmbeddingGenerator for vectors) and Microsoft.Extensions.VectorData (collections, records and vector search). Agent Framework is built on both. Code that already uses them will barely be touched.

Your vector layer. For RAG, Agent Framework in .NET uses Microsoft.Extensions.VectorData implementations, and the documentation lists SQL Server among the available stores, alongside Azure AI Search, PostgreSQL, Qdrant and Redis. Your collections, record models and ingestion stay in place. Only the way search is wired to the agent changes.

What changes: the mapping table

The migration is about the agent layer. Microsoft’s official guide covers it in detail; these are the mappings that matter in practice.

On top of this, Agent Framework ships several building blocks as stable: graph-based workflows to chain agents and functions deterministically, checkpointing for long-running processes, human approval along the way, middleware to intercept calls, and OpenTelemetry observability.

The same agent, before and after

Take a simple, common case: a support assistant that answers questions about orders by calling the application’s order repository. The business code, IOrderRepository, already exists and does not change.

With Semantic Kernel:

using System.ComponentModel;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

public sealed class OrderTools(IOrderRepository orders)
{
    [KernelFunction, Description("Returns the current status of a customer order.")]
    public async Task<string> GetOrderStatusAsync(
        [Description("The order number, for example CMD-2026-0142.")] string orderNumber)
        => (await orders.FindAsync(orderNumber))?.Status ?? "unknown order";
}

// The kernel carries the model connector and the plugins.
Kernel kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(deploymentName, endpoint, credential)
    .Build();
kernel.Plugins.AddFromObject(new OrderTools(orders), "Orders");

ChatCompletionAgent agent = new()
{
    Name = "Support",
    Instructions = "Answer questions about customer orders. Never guess a status: call the tool.",
    Kernel = kernel,
    Arguments = new KernelArguments(new PromptExecutionSettings
    {
        FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(),
    }),
};

AgentThread thread = new ChatHistoryAgentThread();
await foreach (AgentResponseItem<ChatMessageContent> item in agent.InvokeAsync(question, thread))
{
    Console.WriteLine(item.Message.Content);
}

With Agent Framework:

using System.ComponentModel;
using Azure.AI.OpenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI.Chat; // AsAIAgent on the OpenAI ChatClient (package Microsoft.Agents.AI.OpenAI)

public sealed class OrderTools(IOrderRepository orders)
{
    // No framework attribute: a plain method, described for the model.
    [Description("Returns the current status of a customer order.")]
    public async Task<string> GetOrderStatusAsync(
        [Description("The order number, for example CMD-2026-0142.")] string orderNumber)
        => (await orders.FindAsync(orderNumber))?.Status ?? "unknown order";
}

var tools = new OrderTools(orders);

// No kernel: the agent is created from the chat client, tools included.
AIAgent agent = new AzureOpenAIClient(endpoint, credential)
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "Answer questions about customer orders. Never guess a status: call the tool.",
        tools: [AIFunctionFactory.Create(tools.GetOrderStatusAsync)]);

AgentSession session = await agent.CreateSessionAsync();
AgentResponse response = await agent.RunAsync(question, session);
Console.WriteLine(response.Text);

Three observations. The business method is identical bar one attribute. The wiring code loses a third of its lines, because the Kernel and the plugin disappear. And the model call no longer goes through a provider-specific agent type: moving from Azure OpenAI to another compatible provider only touches the line that creates the client.

With dependency injection, the registration becomes:

builder.Services.AddKeyedSingleton<AIAgent>("support", (sp, _) =>
    sp.GetRequiredService<IChatClient>().AsAIAgent(
        instructions: "Answer questions about customer orders. Never guess a status: call the tool.",
        tools: [AIFunctionFactory.Create(sp.GetRequiredService<OrderTools>().GetOrderStatusAsync)]));

What about RAG?

If your application queries business documents, search is now wired in as a context provider. TextSearchProvider takes a search function, which can sit on top of your existing Microsoft.Extensions.VectorData collection, and either runs it before each model call or exposes it as a tool the model calls on demand:

AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    ChatOptions = new() { Instructions = "Answer from the provided documents and cite them." },
    AIContextProviders = [new TextSearchProvider(SearchDocumentsAsync, new TextSearchProviderOptions
    {
        SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
    })],
});

SearchDocumentsAsync is the function you write over your own store: it is where business-aware chunking and permission filtering live, two decisions I cover in the RAG on SQL Server 2025 guide. The framework changes; those two decisions do not.

What to do, depending on where you stand

The last point is not a detail. A migration is a good moment to take AI out wherever it adds nothing: a calculation, a format check or a business rule has no business inside an agent. That is the principle I describe in AI proposes, deterministic logic disposes: the model proposes, a deterministic layer validates.

Migration checklist

1. Inventory. List every use of Microsoft.SemanticKernel in the solution and sort them: model connectors, plugins and functions, agents, memory and search, filters, prompt templates.
2. Isolate. If it is not done already, put AI behind an interface of your domain (for instance IOrderAssistant), implemented in the infrastructure layer. It is the same principle as the swappable document extraction I use on engagements: the business depends on a contract, not on a framework.
3. Freeze a reference set. Before touching the code, record thirty or so real questions with the expected answers and tool calls. That set is what tells you whether the migration changed any behaviour.
4. Switch the tools. Drop [KernelFunction], keep [Description], pass the methods through AIFunctionFactory.Create.
5. Switch the agents. Replace the creation of the Kernel and the agent with AsAIAgent(...), AgentThread with AgentSession, InvokeAsync with RunAsync.
6. Carry over the filters. What Semantic Kernel filters did (logging, function-call checks, data masking) moves to Agent Framework middleware.
7. Rewire search. Keep the vector collection, replace the wiring with a TextSearchProvider or a search tool.
8. Compare. Replay the reference set, compare answers and tool calls, and switch on OpenTelemetry before going to production.

For an application where AI is well isolated, steps 4 to 7 fit in a single work package. For one where it is scattered, step 2 is the real job, and it is worth doing even without a migration.

Going further

Microsoft’s migration guide also covers cases specific to Azure AI Foundry and hosted OpenAI assistants, which this guide leaves aside. If your .NET application embeds AI and you want to know what migration would involve for you, that is exactly the scope of AI integration in .NET applications.