Microsoft Agent Framework 1.0: A Developer Guide

For two years, teams building on Microsoft's AI stack had to make an awkward choice. Semantic Kernel gave you enterprise plumbing — state management, type safety, telemetry, filters — but multi-agent orchestration felt bolted on. AutoGen gave you elegant agent abstractions and research-grade orchestration patterns, but production teams kept hitting gaps around state, observability, and long-running processes.

On April 3, 2026, Microsoft shipped Agent Framework 1.0 for .NET and Python, and that choice went away. The framework is the direct successor to both, built by the same teams, and it folds AutoGen's abstractions into Semantic Kernel's enterprise foundations — then adds a graph-based workflow engine neither of them had.

If you are running agents in production, or planning to, this release deserves an hour of your attention. Here is what actually matters.

What Agent Framework 1.0 Is

The framework organizes itself into three capability tiers, and understanding the split is the fastest way to get oriented.

Agents are individual LLM-driven units that process input, call tools and MCP servers, and return responses. Model support is deliberately broad: Microsoft Foundry, Azure OpenAI, OpenAI, Anthropic Claude, Amazon Bedrock, Google Gemini, and Ollama all work through the same abstraction. That matters for anyone building a multi-model fallback strategy rather than betting a product on one provider.

Harness is an opinionated agent with batteries included for long, multi-step tasks — planning and todo tracking, context compaction, file access and memory, don't-ask-again tool approval, and built-in observability. Think of it as the pre-assembled version for teams who do not want to hand-roll a loop.

Workflows are graph-based compositions that connect agents and plain functions into deterministic, repeatable processes with type-safe routing, checkpointing, and human-in-the-loop support.

Underneath all three sit the shared building blocks: model clients, an agent session for state, context providers for memory, middleware for intercepting agent actions, and MCP clients for tool integration.

Getting Started

Installation is one line in either language.

For Python:

pip install agent-framework

from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
 
credential = AzureCliCredential()
client = FoundryChatClient(
    project_endpoint="https://your-service.services.ai.azure.com/api/projects/your-project",
    model="gpt-5.4-mini",
    credential=credential,
)
 
agent = client.as_agent(
    name="HelloAgent",
    instructions="You are a friendly assistant. Keep your answers brief.",
)
 
result = await agent.run("What is the largest city in France?")
print(f"Agent: {result}")

One gotcha worth knowing up front: Agent Framework does not automatically load .env files in Python. Call load_dotenv() yourself or set environment variables in your shell.

For .NET:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
 
AIAgent agent = new AIProjectClient(
        new Uri("https://your-service.services.ai.azure.com/api/projects/your-project"),
        new AzureCliCredential())
    .AsAIAgent(
        model: "gpt-5.4-mini",
        instructions: "You are a friendly assistant. Keep your answers brief.");
 
Console.WriteLine(await agent.RunAsync("What is the largest city in France?"));

A Go SDK exists in public preview via github.com/microsoft/agent-framework-go, but declarative agents, RAG, CodeAct, and functional workflows are not there yet. Treat Go as experimental for now.

Agents Versus Workflows: The Decision That Matters Most

The single most valuable page in the documentation is the one telling you when not to reach for an agent. Microsoft's own guidance is blunt: if you can write a function to handle the task, write the function.

Beyond that, the split is clean:

Use an agent when	Use a workflow when
The task is open-ended or conversational	The process has well-defined steps
You need autonomous tool use and planning	You need explicit control over execution order
A single LLM call, possibly with tools, suffices	Multiple agents or functions must coordinate

Most production failures we see in agent projects come from ignoring this table. Teams model a deterministic five-step business process as a chatty autonomous agent, then spend months fighting non-determinism they introduced themselves. The workflow engine exists precisely so you do not have to.

The Orchestration Patterns

Agent Framework 1.0 ships five stable orchestration patterns:

Sequential — agents run in order, each consuming the previous output
Concurrent — agents fan out in parallel, results converge
Handoff — one agent transfers control to a specialist based on context
Group chat — multiple agents deliberate in a shared conversation
Magentic-One — a planner-driven pattern for open-ended multi-step tasks

Critically, all five support streaming, checkpointing, human-in-the-loop approvals, and pause/resume for long-running workflows. That last set of features is what separates a demo from a system you can put in front of a compliance team.

Checkpointing: The Underrated Feature

If you have ever had a forty-minute agent run die on a transient API error, you understand why this matters. Agent Framework's workflow engine persists state via checkpoints, configurable either at build time or runtime, and workflows can be paused and resumed across process restarts using checkpoint storage.

This turns two hard problems into configuration:

Failure recovery. A long-running document-processing workflow that fails at step 7 of 12 resumes at step 7, not step 1. On expensive models that is a direct cost saving, not just a latency win.

Human-in-the-loop. A workflow can pause on a high-risk action, wait hours or days for a human approval that arrives through a completely separate channel, then hydrate and continue. Without checkpointing you end up building a bespoke job queue and state machine around your agent. With it, that is framework behavior.

For any regulated workflow — invoice approval, contract review, financial reconciliation — this is the feature that makes agentic automation defensible.

MCP and A2A: Interoperability Without Lock-In

Two protocol integrations shape how Agent Framework fits into a wider stack.

MCP (Model Context Protocol) support lets agents dynamically discover and invoke tools exposed by any MCP-compliant server. You write the tool once as an MCP server and every MCP-aware client — Agent Framework, Claude, and the growing ecosystem around the MCP standard — can call it. The framework also supports hosted MCP tools, so the server does not have to run in your process.

A2A (Agent-to-Agent) enables cross-runtime collaboration, letting agents coordinate with agents running in other frameworks through structured, protocol-driven messaging. A Microsoft Agent Framework agent can hand work to a LangGraph agent or a Google A2A participant without a custom adapter. Note that full A2A support was still landing at the 1.0 announcement — verify current status before designing around it.

Together these two matter more than any individual feature. They mean adopting Agent Framework does not mean rewriting your tools or committing your entire agent estate to one vendor.

Middleware, Memory, and Declarative Config

Three production-oriented capabilities round out the release.

Middleware hooks intercept and extend agent behavior — content safety, logging, compliance gates. This is the extension point for anyone who needs an audit trail of every tool call, which in practice means anyone deploying agents in finance, healthcare, or government.

Agent memory uses a pluggable architecture covering conversational history, persistent state, and vector retrieval. You are not locked into one memory backend.

Declarative configuration lets you define agents and workflows in YAML. That puts agent behavior under version control and code review, rather than buried in application code — a small change that makes governance dramatically easier.

Should You Migrate?

If you are on Semantic Kernel or AutoGen, the answer is eventually yes. Microsoft has published dedicated migration guides for both, including code analysis and step-by-step plans. The framework is explicitly positioned as the next generation of both projects, which tells you where investment is going.

The practical sequencing we would recommend:

Start with new work. Build your next agent on Agent Framework rather than retrofitting a running system.
Migrate AutoGen projects before Semantic Kernel ones. AutoGen's abstractions map more directly onto the new agent model.
Reserve workflows for processes you already understand. Do not use the graph engine to discover your business process — use it to encode one you have already mapped.
Wire up middleware and telemetry on day one. Retrofitting observability onto a live agent system is far more painful than starting with it.

One caution from the release notes worth repeating: if you connect Agent Framework to third-party servers, agents, or non-Azure models, those are governed by their own license terms and you are responsible for the data that flows to them. For teams in the MENA region operating under data residency requirements, that boundary needs explicit review before you connect anything outside your compliance perimeter.

The Bigger Picture

Agent Framework 1.0 is not a novel idea — it is a consolidation. The interesting signal is that the industry's agent frameworks are converging on the same shape: typed agents, graph workflows, MCP for tools, A2A for interoperability, checkpointing for durability. LangGraph got there from one direction, Agent Framework from another, and the durable execution crowd from a third.

That convergence is good news. It means the architectural patterns you learn now transfer, and the tools you build against MCP keep working as the framework layer churns beneath them.

For teams already invested in .NET or Azure, Agent Framework 1.0 is the obvious default. For everyone else, it is worth studying as the clearest statement yet of what a production agent platform is supposed to look like.

At Noqta, we help teams design and deploy agentic systems that survive contact with production — orchestration, observability, and governance included. If you are evaluating agent frameworks for a real workload, get in touch.