Microsoft Agent Framework
Microsoft Agent Framework is the open-source, pro-code SDK for building agents and multi-agent applications - the route to take when the agent logic is yours to write rather than configure. It went GA in April 2026 as the direct successor to both AutoGen and Semantic Kernel, written by the same teams.
When not to use it: if you can write a function to handle the task, do that. Agents add latency, cost, and non-determinism. Use MAF when the task is genuinely open-ended, requires tool use, or needs multi-step orchestration.
Languages: Python, .NET (Go in public preview - limited features)
GitHub: github.com/microsoft/agent-framework
Three Core Capabilities
MAF has three distinct capability levels - choose the simplest one that solves your problem:
| Capability | Use when | Avoid when |
|---|---|---|
| Agent | Task is open-ended or conversational, single LLM + tools suffices | Task is deterministic and can be coded as a function |
| Harness | Long multi-step tasks needing planning, memory, file access, and built-in observability | You need full control over every execution step |
| Workflow | Process has well-defined steps, multiple agents must coordinate, need checkpointing | Simple single-agent scenarios |
Agents
Individual agents that call an LLM, use tools, and connect to MCP servers.
Supported model providers: Microsoft Foundry, Azure OpenAI, Anthropic, OpenAI, Ollama, and others.
import asyncio
from microsoft_agent_framework import Agent, AzureFoundryModelProvider
async def main():
provider = AzureFoundryModelProvider(
endpoint="https://my-foundry.services.ai.azure.com",
model="gpt-5"
)
agent = Agent(
provider=provider,
instructions="You are a financial analyst. Answer questions about quarterly reports concisely.",
tools=[] # add file search, code interpreter, MCP tools here
)
response = await agent.run("What drove the Q2 margin compression?")
print(response.text)
asyncio.run(main())
Tools and MCP
Agents can call functions and connect to MCP servers:
from microsoft_agent_framework import Agent, MCPClient
agent = Agent(
provider=provider,
instructions="You have access to enterprise data.",
mcp_clients=[
MCPClient(server_url="https://my-foundry.services.ai.azure.com/mcp"), # Foundry Toolboxes
MCPClient(server_url="https://my-fabric.fabric.microsoft.com/mcp"), # OneLake
]
)
Harness
An opinionated agent with batteries-included capabilities for long, complex tasks. The Harness adds:
- Planning and to-do tracking - agent creates a plan, tracks progress across steps
- Context compaction - manages long contexts automatically, preserves what matters
- File access and memory - read/write files, persist facts across sessions
- Don't-ask-again tool approval - approve a tool class once, not every call
- Built-in observability - traces, metrics, costs without extra configuration
from microsoft_agent_framework import AgentHarness
harness = AgentHarness(
provider=provider,
instructions="You are a research analyst. Complete multi-step research tasks.",
# Harness handles planning, memory, file I/O, and observability automatically
)
result = await harness.run("Research our top 5 competitors and produce a comparison report.")
# Agent plans the task, searches, compiles, writes files, tracks progress
Use the Harness when you'd otherwise need to implement your own planning loop, memory management, or progress tracking.
Workflows
Graph-based workflows that connect agents and functions for processes with defined steps. Key properties:
- Type-safe routing - typed inputs/outputs between nodes
- Checkpointing - resume from any point after failure
- Human-in-the-loop - pause workflow for approval, then continue
- Branching and parallel execution - conditional paths, concurrent agent runs
from microsoft_agent_framework import Workflow, WorkflowNode
@WorkflowNode
async def extract_entities(text: str) -> dict:
return await extraction_agent.run(text)
@WorkflowNode
async def classify_risk(entities: dict) -> str:
return await classification_agent.run(entities)
@WorkflowNode
async def generate_report(entities: dict, risk: str) -> str:
return await reporting_agent.run(entities, risk)
workflow = Workflow(
nodes=[extract_entities, classify_risk, generate_report],
edges=[
(extract_entities, classify_risk),
(extract_entities, generate_report),
(classify_risk, generate_report),
]
)
result = await workflow.run(input_text)
Workflow patterns (all stable)
| Pattern | Description |
|---|---|
| Sequential | A - B - C, output feeds next |
| Parallel | A splits to B + C, merge at D |
| Conditional | Route based on output value |
| Magentic-One | Multi-agent collaboration with shared context |
| Human-in-the-loop | Pause at checkpoint, await approval |
MAF vs Foundry Agents SDK
Both deploy to Foundry Hosted Agents. Choose based on how much control you need:
| Dimension | Microsoft Agent Framework | Foundry Agents SDK (azure-ai-projects) |
|---|---|---|
| Orchestration | You write it explicitly | Foundry manages it |
| Control | Full - every step is code | Declarative - Foundry decides execution |
| Complexity | Higher - you build the plumbing | Lower - portal or SDK, Foundry does the rest |
| Graph workflows | Yes | No |
| Harness (planning + memory) | Yes | No |
| Best for | Complex multi-agent, custom routing, long-running tasks | Standard agents, rapid prototyping, team without ML engineers |
| Hosting | Foundry, Azure Container Apps, any runtime | Foundry Hosted Agents |
Rule of thumb: start with Foundry Agents SDK. Move to MAF when you hit the ceiling of what declarative agents can do.
Microsoft AI Platform compares all four ways to build on Microsoft side by side, if the choice is wider than this pair.
Important Limitations
- Third-party systems - Microsoft does not warrant security or compliance of third-party MCP servers. You are responsible for reviewing data flows outside Azure. Check the Transparency FAQ before production deployment.
- Go support - no CodeAct, RAG, or declarative agents yet. Use Python or .NET for production.
- Does not auto-load .env files - call
load_dotenv()explicitly or set environment variables directly. - Responsible AI - MAF does not add content filters automatically. You must implement metaprompt, content filters, or safety systems yourself when using MAF with third-party models.
Resources
| Resource | Link |
|---|---|
| Documentation | learn.microsoft.com/agent-framework |
| GitHub | github.com/microsoft/agent-framework |
| Build 2026 announcement | devblogs.microsoft.com/agent-framework |
| Migration from AutoGen | Migration guide |
| Migration from Semantic Kernel | Migration guide |
Key Takeaways
- If you can write a function to handle the task, do that. Agents add latency, cost, and non-determinism - only reach for MAF when the task is genuinely open-ended or requires multi-step tool use.
- Start with the simplest capability level: Agent for conversational, Harness for long multi-step tasks, Workflow for processes with explicit steps.
- MAF does not add content filters automatically when using third-party models. Implement your own safety systems.
- The Go SDK is in preview and missing CodeAct, RAG, and declarative agents - use Python or .NET for production.
- AutoGen and Semantic Kernel users should migrate to MAF - it's the direct successor from the same teams, with migration guides for both.
Next: Copilot Studio - the pro-code route, set against the low-code one that business users can own.