Microsoft Agent Framework 1.0: The Unified SDK for Production AI Agents — A Complete Guide

On April 3, 2026, Microsoft closed a three-year chapter. AutoGen — the research framework that accumulated over 54,000 GitHub stars and popularized multi-agent conversation patterns — was placed into maintenance mode. Its ideas did not die. They were merged with Semantic Kernel's enterprise tooling into a single production SDK: Microsoft Agent Framework (MAF) 1.0.

This was not a gentle rebrand. MAF 1.0 shipped with stable APIs, a long-term-support commitment, first-class Python and .NET runtimes, and native interoperability with the rest of the 2026 agent ecosystem through MCP and A2A. Between them, the two predecessor projects carried over 75,000 stars and three years of enterprise field experience. The message was clear: the experimentation era is over.

If you are starting a new agent project today — or maintaining one built on AutoGen 0.2 or Semantic Kernel — this article is your map. We will cover what changed, what the architecture looks like, the five orchestration patterns you need to know, the CodeAct innovation that collapsed the agent loop, and a full step-by-step guide to building a working multi-agent system.

The Merger: Why Microsoft Killed Two Frameworks to Build One

For two years, teams building agentic AI on the Microsoft stack faced an awkward question: AutoGen or Semantic Kernel?

AutoGen, born in Microsoft Research, gave the world conversable agents, group chats, and the Magentic-One multi-agent system. It was brilliant for prototyping — but lacked the middleware, telemetry, session management, and security primitives that production systems demand.

Semantic Kernel had those enterprise features. Its plugin architecture, type-safe tool definitions, and OpenTelemetry integration made it a natural fit for deployment. But it lacked AutoGen's flexible multi-agent orchestration.

Teams ended up gluing them together themselves — or choosing one and living with the gaps. The Microsoft Agent Framework 1.0 announcement ended that dilemma. Semantic Kernel became the foundation layer — the kernel, plugin model, and provider connectors. AutoGen's orchestration concepts were reimplemented as a graph-based workflow engine on top. One package. One mental model.

What happened to AutoGen? AutoGen is now in maintenance mode: Microsoft will patch bugs and security issues but will not add new features. The community-driven AG2 fork continues under Apache 2.0, adding AgentOS-style cross-framework interoperability. Existing AutoGen 0.2 projects should plan a migration path to either AG2 or MAF.

Architecture: Agents, Workflows, and the Runtime

MAF separates concerns cleanly into three layers:

Agents are long-lived, stateful execution units. They use LLMs to interpret inputs, call tools and MCP servers, maintain session state, and generate responses. They are not prompt wrappers — they are runtime components with managed lifecycles.

Workflows are graph-based orchestration engines. They connect agents and functions, enforce execution order, support checkpointing and hydration for long-running processes, and enable human-in-the-loop intervention. The key architectural win: reasoning lives in the agent; execution policy lives in the workflow.

The Runtime provides the connective tissue: middleware pipelines that intercept every stage of execution, pluggable memory backends (Foundry Agent Service, Mem0, Redis, Neo4j, or custom), and OpenTelemetry traces that span the entire agent lifecycle.

Six Providers, One-Line Swap

MAF 1.0 ships with first-party service connectors for Azure OpenAI, OpenAI, Anthropic Claude, Amazon Bedrock, Google Gemini, and Ollama. Swapping providers is a one-line configuration change. No code-path forks. No separate SDK branches.

MCP and A2A Are Native

Model Context Protocol (MCP) support is built into the core — agents discover and invoke tools from any MCP-compatible server. The Agent-to-Agent (A2A) protocol ships via the agent-framework-a2a adapter, enabling cross-framework agent collaboration. Neither is bolted on. Both shipped at 1.0.

Five Orchestration Patterns, One Framework

Microsoft formalized five multi-agent blueprints that emerged from AutoGen's research lineage. These are not metaphors — they are pre-built, type-safe workflow templates.

1. Sequential — Agents are organized in a pipeline. Each agent processes the task in turn, passing its output to the next. Ideal for review chains and multi-stage reasoning.
2. Concurrent — Multiple agents work on the same task in parallel. Their independent results are collected and aggregated. Perfect for ensemble reasoning and fan-out analysis.
3. Handoff — Agents transfer control based on context. A triage agent routes the user to the right specialist without the user knowing which agent is active. Clean domain routing.
4. Group Chat — A collaborative conversation among multiple agents, coordinated by a manager that determines speaker selection and conversation flow. The pattern that made AutoGen famous, now with deterministic control.
5. Magentic — Based on the Magentic-One research system, a dedicated Magentic manager maintains a task ledger, tracks progress, and dynamically delegates subtasks to specialized agents. Designed for open-ended problems where the solution path is not known in advance.

All five patterns support streaming, checkpointing, human-in-the-loop, and structured telemetry.

The Agent Harness: Batteries Included

In July 2026, Microsoft released the Agent Framework Harness — an opinionated, batteries-included scaffolding that turns a language model into an agent that can actually do things.

A model on its own generates text. To call tools, work through multi-step tasks, remember what it has done, and keep going until the job is finished, you need a runtime wrapped around the model. That runtime is the harness.

With one call, create_harness_agent(), you get:

• Function invocation — automatic tool-calling loop with configurable iteration limits
• Per-service-call history persistence — checkpointing after every model call for crash recovery
• Compaction — context-window management that keeps long loops from overflowing
• Todo list and plan/execute mode — the agent tracks what it has done and what remains
• Approvals — safety gates before sensitive tool calls
• Web search — built-in grounding capability
• Telemetry — OpenTelemetry traces for every action, tool call, and workflow step

You supply the chat client, the instructions, and your tools. Everything else has sensible defaults that you can customize or disable.

CodeAct: The Loop Killer

At BUILD 2026, the MAF team shipped a pattern that represents the first substantive architectural shift in agent design this year: CodeAct.

The traditional agent loop works like this: the model picks a tool, the tool runs, the result goes back to the model, the model picks the next tool — repeat. A 12-step workflow means 12 round-trips between the model and the tool runtime. Latency compounds. Token costs multiply. Traces become graphs of tool calls that are hard to replay and audit.

CodeAct replaces that loop with a single step. The model writes one short Python program that calls every tool it needs via call_tool(...), executes it once in a sandboxed Hyperlight micro-VM, and returns a consolidated result.

Microsoft's published benchmarks show the impact:

Wiring	Time	Tokens
Traditional agent loop	27.81s	6,890
CodeAct	13.23s	2,489
Improvement	52.4%	63.9%

CodeAct Improvement Over Traditional Agent Loop
Improvement (%)

The implications are larger than latency savings. A CodeAct program is deterministic — you can save it, replay it, and audit it. The model's reasoning shifts from "decide one step at a time" to "plan the entire workflow up front." Plans get tighter. Failure modes become more legible.

Wiring it in is a one-line change to how your tools are registered. As of July 2026, CodeAct is available in the agent-framework-hyperlight alpha package for Python, with .NET support on the roadmap.

Step-by-Step: Build Your First Multi-Agent System

Let's build a working multi-agent system with MAF 1.0 in Python. We will create a simple research pipeline: a researcher agent searches the web, a writer agent synthesizes findings, and a reviewer agent checks the output for factual consistency. We will wire them together with a sequential workflow.

Prerequisites

• Python 3.10+
• An Azure AI Foundry project endpoint (or an OpenAI / Azure OpenAI API key)
• pip install agent-framework azure-identity

Step 1: Configure the Chat Client

MAF supports six providers. For this example we use Azure AI Foundry with the Azure CLI credential:

import os
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

client = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model="gpt-4o",
    credential=AzureCliCredential(),
)

If you are using OpenAI directly:

from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(
    api_key=os.environ["OPENAI_API_KEY"],
    model="gpt-4o",
)

Step 2: Define Your Agents

Each agent gets a name, instructions, and a list of tools. The Agent class is the core abstraction:

from agent_framework import Agent

researcher = Agent(
    client=client,
    name="Researcher",
    instructions=(
        "You are a thorough researcher. Given a topic, search the web "
        "and return a structured summary with key facts, dates, and sources."
    ),
    tools=[],  # We will add tools in Step 3
)

writer = Agent(
    client=client,
    name="Writer",
    instructions=(
        "You are a concise technical writer. Synthesize the research notes "
        "into a well-structured report with an introduction, three body "
        "sections, and a conclusion. Use Markdown."
    ),
)

reviewer = Agent(
    client=client,
    name="Reviewer",
    instructions=(
        "You are a meticulous reviewer. Check the report for factual "
        "consistency against the original research notes. Flag any "
        "unsupported claims. Return the corrected report."
    ),
)

Step 3: Add Tools with the @tool Decorator

Any Python function becomes an agent tool with the @tool decorator. Use typing.Annotated and pydantic.Field to give the LLM rich parameter descriptions:

from agent_framework.tools import tool
from typing import Annotated
from pydantic import Field

@tool(description="Search the web for current information on a topic")
def web_search(
    query: Annotated[str, Field(description="The search query")],
) -> str:
    # In production, call a real search API (Bing, Tavily, etc.)
    # This is a stub for the tutorial
    import httpx
    response = httpx.get(
        "https://api.example.com/search",
        params={"q": query},
    )
    return response.json()["results"]

# Attach tools to the researcher
researcher = Agent(
    client=client,
    name="Researcher",
    instructions="...",
    tools=[web_search],
)

Step 4: Orchestrate with a Sequential Workflow

MAF's graph-based workflow engine connects agents into deterministic pipelines:

from agent_framework.orchestrations import SequentialBuilder

workflow = (
    SequentialBuilder()
    .add(researcher, label="Research")
    .add(writer, label="Write")
    .add(reviewer, label="Review")
    .build()
)

# Run the workflow
result = await workflow.run(
    "What are the key trends in agentic AI frameworks in 2026?"
)
print(result.final_output)

Step 5: Add Middleware and Observability

MAF's middleware pipeline lets you intercept every stage of execution without modifying agent prompts:

from agent_framework.middleware import Middleware

@Middleware.before_model_call
def log_prompt(context):
    print(f"[{context.agent.name}] Sending prompt: {context.messages[-1].content[:200]}...")

@Middleware.after_tool_call
def log_tool_result(context):
    print(f"[{context.agent.name}] Tool {context.tool_name} returned: {context.result[:200]}...")

agent = Agent(
    client=client,
    name="Researcher",
    instructions="...",
    tools=[web_search],
    middleware=[log_prompt, log_tool_result],
)

For production telemetry, MAF automatically collects OpenTelemetry traces. Ship them to Azure Monitor or Application Insights to visualize token usage, latency, tool success rates, and error patterns across your entire multi-agent workflow.

Step 6: Run Locally with the DevUI

The DevUI shipped with 1.0 is a browser-based debugger that shows agent execution, message flow, and tool calls in real time. It dramatically improves the debugging experience for multi-agent systems — you can see exactly what each agent decided, which tools it called, and why.

agent-framework devui

Open http://localhost:8000 and you will see your agents, workflows, and conversation threads in a visual interface. You can create new threads, interact with agents, and trace every step.

What to Watch: The Road Ahead

MAF is moving fast. The July 2026 releases included:

• Agent Framework Harness reaching GA — the batteries-included scaffolding for autonomous agents
• CodeAct in alpha — a fundamentally different agent loop with 52% latency reduction
• Background Agents Provider — parent agents can delegate work to parallel child agents
• GitHub Copilot SDK integration — build agents that leverage Copilot's coding capabilities, including shell execution, file operations, and MCP servers
• Go support — announced in July 2026, bringing MAF's programming model to Go developers

When to Choose MAF — and When Not To

MAF is the strongest single choice if your stack includes Azure, .NET, or Microsoft 365. The integration with Azure AI Foundry, native MCP/A2A support, and the unified programming model across Python and .NET make it uniquely suited for enterprise Microsoft shops.

If your stack is AWS-native, Anthropic's Claude Agent SDK may feel more natural. If you need low-level control over agent graphs and are already in the LangChain ecosystem, LangGraph 1.0 remains an excellent choice. If you want the fastest path from idea to prototype, CrewAI's role-based model is still the speed leader.

The framework landscape in 2026 has consolidated around a handful of production-grade options. MAF's convergence of two major open-source projects — and Microsoft's long-term-support commitment — make it the safest bet for teams that want to build once and operate for years.

The experimentation era is over. The platform era has begun.