Microsoft Agent Framework

Microsoft's open-source .NET/Python (Go preview) SDK that succeeds Semantic Kernel and AutoGen: one AIAgent abstraction over any chat client, a layered middleware/context-provider pipeline, typed graph workflows, and Azure Foundry integration.

Contents

Microsoft Agent Framework (MAF) is Microsoft’s open-source SDK for building agents and multi-agent workflows in .NET and Python, with Go in public preview. The AutoGen and Semantic Kernel teams built it as the next generation of both projects. It takes AutoGen’s simple agent abstractions and Semantic Kernel’s enterprise features (sessions, type safety, middleware, telemetry), and adds typed graph workflows (overview). Version 1.0 went GA for .NET and Python on 2026-04-03 with a long-term-support commitment (1.0 announcement). The Python package was at 1.26.0 on 2026-11-12 (README). Semantic Kernel’s own README now calls MAF its successor (SK README). The AutoGen lineage, the AutoGen-to-MAF mapping and the five built-in orchestrations are covered on AutoGen and Microsoft Agent Framework. This page covers MAF’s internals: the agent abstraction, the run pipeline, sessions, CodeAct, and what Semantic Kernel users must change.

Core abstractions

Abstraction.NETPythonRole
Agent baseAIAgentBaseAgent / SupportsAgentRun protocolOne run interface for every agent kind
Model-backed agentChatClientAgent over any IChatClientAgent(client=...) over any SupportsChatGetResponse clientInstructions + tools + loop
Remote / managed agentsA2AAgent, CopilotStudioAgent, GitHubCopilotAgentFoundryAgent, A2AAgent, GitHubCopilotAgent, ClaudeAgentProxy a runtime you don’t own
Conversation stateAgentSessionAgentSessionLocal history or a service conversation ID
Context injectionChatHistoryProvider + AIContextProvidersone context_providers listHistory, memory, RAG, dynamic instructions
Interceptionagent / chat-client middlewareagent, chat and function middlewareLogging, policy, rewriting
OrchestrationWorkflow (graph)WorkflowBuilder graph or experimental @workflowExplicit multi-step / multi-agent paths

Sources: pipeline docs, SK migration guide, workflows.

In .NET the key design choice is building on Microsoft.Extensions.AI. Any inference SDK that implements IChatClient can back an agent, and message and content types are shared with the wider .NET AI stack (SK migration guide). Stable connectors at 1.0: Microsoft Foundry, Azure OpenAI, OpenAI, Anthropic Claude, Amazon Bedrock, Google Gemini and Ollama (1.0 announcement).

The run pipeline

A run is a stack of layers, and you customise behaviour by choosing the right one (pipeline docs):

flowchart TD
  U["agent.run(input, session)"] --> AM["Agent middleware + telemetry (wraps whole run)"]
  AM --> RA["RawAgent: run context providers (history, memory, RAG); collect per-run middleware"]
  RA --> FI["FunctionInvocation: tool-calling loop"]
  FI --> CM["Chat middleware + telemetry (per model call)"]
  CM --> RC["RawChatClient (Foundry, OpenAI, Anthropic, ...)"]
  RC --> FI
  FI -- "tool call" --> FM["Function middleware (per tool call)"] --> T["Tool"]
  FI --> RA2["Context providers notified of new messages (persist)"]

Diagram follows the Python pipeline in the pipeline docs. .NET has the same three layers: agent middleware, context layer, then IChatClient and its decorators.

What follows from this structure:

  • Agent middleware works on any agent, including remote ones such as A2AAgent or GitHubCopilotAgent. Because it can’t assume what it wraps, it should only touch common concerns. Chat-client middleware isn’t available on agents that have no local IChatClient (pipeline docs).
  • Function middleware runs once per tool call, so it is the natural place for approval, argument validation or auditing. Chat middleware runs once per model call, which suits prompt rewriting and caching.
  • In .NET, ChatClientAgent adds function calling to the chat client by default. Setting UseProvidedChatClientAsIs = true turns this off when you have already built your own pipeline (pipeline docs).
  • Telemetry layers emit OpenTelemetry spans, events and metrics, and do nothing until configured (pipeline docs). Optional Agent Hooks install one fail-closed policy bundle across the agent, chat and function layers, and hold back streamed or persisted output until a verdict allows it.
  • Unlike AutoGen’s AssistantAgent, the Agent keeps looping over tool calls until it can answer (AutoGen migration guide).

Synthesis: this is the same split that LangChain 1.0 middleware and the Vercel AI SDK wrapLanguageModel make: one hook around the loop, one around each model call, one around each tool call. MAF’s addition is a separate context-provider layer for history and memory. That keeps agent memory and RAG injection out of middleware.

Sessions and memory

AgentSession holds conversation state. The agent creates it (create_session() / CreateSessionAsync()), and you pass it into every run. To persist it, serialize it (session.to_dict() / SerializeSession) or resume it by service conversation ID (get_session(service_session_id=...)) (conversations docs). A session is either local, where history is stored by a history provider such as InMemoryHistoryProvider, or service-managed, where it holds an opaque server-side ID such as an OpenAI Responses conversation. There is no delete API, because not every provider hosts history. If you need deletion, track sessions yourself and delete them through the provider SDK (SK migration guide). Memory backends at 1.0 include Foundry Agent Service, Mem0, Redis and Neo4j (1.0 announcement).

Multi-tenant pitfall: service conversation IDs are scoped to the API key or project, not to the end user. A hosted agent that shares one key across users must store IDs server-side and check the caller’s user or tenant before resuming a conversation (conversations docs). Otherwise one user can read another user’s conversation. See agent authentication and authorization.

Workflows, hosting and tooling

  • Workflows. Typed executors joined by edges, with fan-out/fan-in, superstep checkpoints, request/response pauses for human-in-the-loop, and .as_agent() to wrap a workflow as an agent. There are five built-in orchestrations: sequential, concurrent, handoff, group chat and Magentic (workflows). See AutoGen and MAF for detail.
  • Declarative agents and workflows in YAML are stable at 1.0. MCP is stable. DevUI, Foundry hosted agents, AG-UI, skills and the Agent Harness were still preview at GA (1.0 announcement). The harness agent adds planning and todos, context compaction, file access and memory, and tool approval (overview).
  • CodeAct. An execute_code tool, backed by Hyperlight (Python/.NET), Monty (Python) or a local .NET executor, lets the model write one program that calls several tools instead of making one model turn per call (CodeAct docs). This is the same idea as smolagents code agents. See code execution sandboxes.
  • Integration with the Azure estate. Foundry is the default in quickstarts, and a Foundry agent record can be loaded with AsAIAgent(agentRecord) (SK migration guide, README). See Azure AI Foundry.

Migrating from Semantic Kernel

Semantic KernelAgent Framework
Every agent needs a KernelNo kernel. chatClient.AsAIAgent(...) / Agent(client=...)
ChatCompletionAgent, OpenAIAssistantAgent, AzureAIAgentChatClientAgent (.NET) / Agent (Python) for all chat-client services
[KernelFunction] + plugin + kernelPlain functions, @tool, AIFunctionFactory.Create, passed as tools=
Caller builds a provider-specific AgentThreadAgent creates an AgentSession
invoke returns an async stream of messagesrun returns one AgentResponse. run(stream=True) / RunStreamingAsync yields AgentResponseUpdate
PromptExecutionSettings in KernelArgumentsTypedDict default_options / options (Python), ChatClientAgentRunOptions (.NET)

Source: SK migration guide. For incremental migration, KernelFunction.as_agent_framework_tool() (semantic-kernel 1.38+) wraps existing SK functions, including SK vector-store search functions, as MAF tools.

Comparison with peers

MAFLangGraphOpenAI Agents SDKClaude Agent SDK
Languages.NET, Python, Go (preview)Python, JSPython, TSPython, TS
Core unitAIAgent + typed Workflow graphState graph with checkpointerAgent + Runner loop, handoffsClaude Code agent loop
Model scopeAny IChatClient / chat clientAny (via LangChain)OpenAI-first (Responses API)Claude
Durable stateSuperstep checkpoints. Single-process runtimeCheckpointers with durability modesSessionsSessions
Enterprise hookAzure/Foundry, OpenTelemetry, .NET DILangSmithOpenAI platform tracingClaude Code permissions/hooks

Sources: this page’s MAF sources, LangChain/LangGraph 1.0, OpenAI Agents SDK docs, Claude Agent SDK overview. Synthesis: MAF’s main differentiator is first-class .NET with dependency-injection-friendly AIAgent registration. No other major agent SDK covers .NET as fully.

Limitations and failure modes

  • Partly preview. At GA, DevUI, hosted agents, skills and the harness were preview. A2A 1.0 was “coming soon” (1.0 announcement). The .NET Hyperlight CodeAct package depends on a NuGet package that isn’t yet published (CodeAct docs). Check the status of each feature before relying on it.
  • Single-process workflows. Distributed execution is planned, not shipped (AutoGen migration guide). For durability across processes, see durable agent execution.
  • Language parity lags. Python-only features (functional workflows, FIDES information-flow security) exist, and Go repeatedly marks features as “coming soon” (workflows, CodeAct docs).
  • CodeAct weakens per-tool controls. Host tools called from inside the sandbox skip function middleware, and approval covers the whole execute_code call (CodeAct docs).
  • Fast API churn. The Python package went from 1.0 in April 2026 to 1.26.0 in November 2026 (1.0 announcement, README), and docs disagree in places (see the contradiction note on AutoGen and MAF).
  • Async resource leaks in Python. MCP tools and clients hold connections, so use async with agent or open()/close() (pipeline docs).

When to use it, and when not

  • Use it for .NET shops, teams on Semantic Kernel or AutoGen (this is the supported path forward), Azure/Foundry deployments that need OpenTelemetry and Entra-based credentials, and workloads that mix agents with typed, checkpointed workflows and human approval steps.
  • Don’t use it if a plain function or a single LLM call will do. Microsoft’s own guidance says so (overview). Python-first teams that want mature durable graphs may prefer LangGraph. TypeScript teams should look at Mastra or the Vercel AI SDK. For a thin loop tied to one vendor, use the OpenAI Agents SDK or the Claude Agent SDK.

Sources

Suggest changes →