Microsoft Agent Framework, two lineages in one project

Microsoft Agent Framework, two lineages in one project

For two years Microsoft developed two agent building libraries in parallel. One grew out of research and favoured free form conversation between agents, the other was built for enterprises and emphasised plugins, security, and integration with the rest of the offering.

Maintaining two answers to the same question proved indefensible. Microsoft Agent Framework merges both lineages into one project, released as stable in April 2026, with identical concepts and interfaces in Python and on the .NET platform.

For anyone holding code on AutoGen or Semantic Kernel, this is the indicated migration target. For a new project it is one of several sensible options, and below I describe when picking this one is justified.

Two levels: agent and workflow

The project separates two things other libraries often fuse, and that separation is its best idea.

An agent is a model with instructions and a set of tools. It receives a task, decides itself which tools to call and in what order, and returns a result. Freedom is an advantage here, since on an unpredictable task a rigid plan gets in the way.

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

def check_stock(sku: str) -> int:
    """Returns the number of units available in the warehouse."""
    return warehouse.count(sku)

agent = ChatAgent(
    chat_client=OpenAIChatClient(model="gpt-4o"),
    instructions="You answer questions about product availability. Always check stock.",
    tools=[check_stock],
)

result = await agent.run("Do we still have shoes in size 42?")

A workflow describes what should happen, written out explicitly by you. Steps, conditions, branches, and checkpoints are visible, so the run is repeatable.

Dividing work between those two levels is a practical guideline for the whole project. Describe a business process with known steps as a workflow. Leave a single step requiring judgement to an agent. The reverse, handing the whole process to an agent, produces something you can neither debug nor reproduce.

Orchestration patterns

Five ready arrangements exist for combining multiple agents, and knowing them by name pays off, since they cover most real needs.

The sequential arrangement passes one agent's result to the next. Simplest and most often sufficient.

The concurrent arrangement runs several agents over the same input and collects the results. Sensible when the tasks are independent, since it shortens time to that of the slowest.

Group conversation lets agents exchange messages, as in the original AutoGen. Flexible and hardest to predict.

Handoff passes control to another agent along with the whole context. That is the arrangement familiar from support desks, where a case travels to a specialist.

The coordinator arrangement plans the work, distributes it, and assembles results, returning to the plan when something fails.

When choosing among them, start with the simplest you can defend. Sequential and concurrent cover most uses, while group conversation looks the most interesting and most often disappoints in production, since the same input produces different runs.

Checkpoints and resumption

This feature decides whether a solution belongs in production on longer processes, and many libraries still lack it.

A workflow saves state at designated moments. If the process breaks halfway, through an external service failure or a deployment restart, resumption starts from the last checkpoint rather than the beginning.

The significance shows only in the bills. A twelve step process failing on the tenth costs ten model calls every time you try to fix the bug, absent checkpoints. With checkpoints it costs one.

The second advantage concerns human involvement. A workflow can pause and wait for approval, with state sitting saved for as long as needed. That allows building processes where an agent prepares a decision and a person confirms it, without holding the process in memory for three days.

The harness, or the execution layer

The mid 2026 release added a layer packaging into one piece the things previously assembled by hand around every serious agent.

That means the reasoning loop, shell and file system access, context management across long sessions, and flows with human approval. It is exactly the set every team building an agent for code or file work used to write themselves, usually worse.

Separately, an approach appeared where the model, rather than picking tools one at a time, writes a short program calling them all, and the program runs once in an isolated environment. The gain is twofold: fewer model calls and fewer turns, since the whole sequence goes in one pass.

That solution is at an early stage and deserves treating as an experiment rather than a foundation. The direction is worth attention, though, since it shows where the whole field is heading: from a model picking tools to a model writing the code that calls them.

Middleware, or control over the run

A mechanism that turns out to matter more than the orchestration patterns themselves in a serious deployment, while occupying little space in the documentation.

Every execution stage can carry a function intercepting what happens: before the model call, after it, before a tool call, and after it completes. It looks unremarkable and solves four problems at once.

The first is approving actions. A tool modifying data or sending a message can require confirmation, and middleware is where you check that, without scattering conditions across tool code.

The second is recording the run. Every call together with arguments, result, timing, and token usage lands in a log in one place, so later diagnosis needs no rerun.

The third is error handling. A tool raising an exception should usually return the message to the model rather than tearing down the whole run, since the model can often correct the arguments and retry.

The fourth is capping cost. A call and token counter kept in this layer lets you abort a run past a threshold instead of discovering the overrun on an invoice.

Write those four things once, at the project's start, and attach them to every agent. Adding them later, with twelve agents in place, is the same work multiplied by twelve.

Observability and costs

An agent fails differently from ordinary code, since it raises no exception and instead returns an answer worse than expected. That changes how it must be watched.

The library emits telemetry in a widely adopted format, so runs plug into tooling the team already uses without a separate dashboard. A single run appears as a tree: model calls, tool calls, timings, and token usage.

Three measures deserve watching from day one. Turns per task shows whether the agent is circling. Cost per task says whether the solution scales. The share of tasks completing successfully, measured over a fixed set of cases, says whether a change to the instructions improved anything or merely looked like an improvement.

That third measure requires a set of cases with expected results and is the only one letting you compare two versions of an agent. Without it, judgement reduces to an impression from a few manual attempts, and impressions mislead regularly, particularly around system prompt changes.

What it connects to

The library does not tie you to one model vendor, and that is a meaningful change from Microsoft's earlier tooling.

Ready connectors cover Microsoft's services, OpenAI models, Claude, Google and Amazon offerings, and locally run models. Switching vendor means swapping the client in the agent constructor, with no changes elsewhere.

Two protocols that became standards this year are supported as well. The first lets you attach tools and data sources exposed by external servers, so an existing integration with a company system needs no custom code. The second describes communication between agents from different vendors, which matters when your agent must talk to somebody else's.

Verify support for both against your own case before writing them into an architecture document. The standards are young and compatibility is sometimes partial.

Microsoft Agent Framework against the alternatives

The first criterion is mundane and decisive: language. If the backend runs on .NET, this library is practically the only serious option, since none of the others ships a variant for that platform. LangGraph and the OpenAI Agents SDK give you Python and JavaScript, Google ADK gives you Python, Java, and Go, and .NET appears in none of them.

The second is the support commitment. The stable release carries a promise to keep the interface, which after the history with two previous projects has real value for a team planning a deployment measured in years.

The third, as always, is whether a framework is needed at all. An agent with three tools and one step is a hundred lines of code calling the model directly, with no library involved.

Migrating from the earlier projects

The vendor supplies guides for both lineages, and starting there pays off, since they map the concepts.

Moving from the first library, the biggest change is abandoning conversation as the control mechanism. What was an exchange of messages between agents becomes a workflow with explicit steps. It usually turns out the order was fixed anyway, so the change removes irreproducibility without taking anything away.

Moving from the second, the biggest change is the agent model. Plugins and functions carry over directly, while the planning layer works differently and needs rethinking.

In both cases the order of work is the same. First extract the tools as ordinary code independent of the library, since that is the most valuable part and moves unchanged. Then build a set of test cases with expected results, since without one you cannot tell a successful migration from a failed one. Only then rewrite the orchestration.

Do not migrate everything at once. One process moved in full and run alongside the old one says more than a plan covering ten processes, since only comparing both versions on the same traffic shows the difference in quality and cost.

Common mistakes

The first is handing an agent a whole process with known steps. Describe known steps as a workflow, since you gain repeatability and cheaper debugging.

The second is skipping checkpoints on long processes. Every restart then costs a full run from the beginning, model calls included.

The third is choosing group conversation because it looks the most interesting. Production values repeatability, and that arrangement does not provide it.

The fourth is having no per run cost cap. An agent in a loop can make dozens of calls before anybody notices a problem.

The fifth is writing the protocols into an architecture document without verifying compatibility on your own case. The standards are young and support is sometimes partial.

The sixth is migrating without a test set. Agents do not return values comparable with an equals sign, so without cases carrying expected results, judging a change is guesswork.

FAQ

Is this the successor to AutoGen and Semantic Kernel?

Yes, the vendor calls it the direct successor to both, created by the same teams. AutoGen is in maintenance mode, Semantic Kernel remains supported, and new development goes into a single repository.

Does it work outside the Microsoft ecosystem?

Yes. Ready connectors cover models from various vendors, locally run ones included, and the library does not require Microsoft cloud services. Integration with them runs deeper than with the rest, though, which under a deployment in that cloud is sometimes the deciding argument.

Python or .NET?

Both variants share the same concepts and comparable scope, so choose by your backend language. The .NET variant is the differentiator here against the competition, since most agent libraries do not offer one.

Do I need a framework for a simple agent?

Usually not. An agent with a few tools and one step is little code calling the model directly. A framework earns its keep with state management, checkpoints, retries, and observability.

How do I tell whether it suits my project?

Build one real process from your own system in it, not an example from the documentation, and measure three things: cost per run, response time, and how quickly you establish the cause after a failed run. The third measure decides most often and is checked least.

Documentation sits on the project site, and release news on the team blog.