The Microsoft Stack
Start Here
Overview and approach
Foundry
The production AI platform
Building Agents
Pro-code and low-code
Data and Retrieval
What grounds the agents
Operating in Production
Running it safely

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:

More Structure
Open-ended to explicitly controlled
Agents
LLM plus tools plus MCP. Conversational, open-ended
Harness
Opinionated agent: planning, memory, files, observability
Workflows
Graph-based multi-agent: typed, checkpointed
CapabilityUse whenAvoid when
AgentTask is open-ended or conversational, single LLM + tools sufficesTask is deterministic and can be coded as a function
HarnessLong multi-step tasks needing planning, memory, file access, and built-in observabilityYou need full control over every execution step
WorkflowProcess has well-defined steps, multiple agents must coordinate, need checkpointingSimple 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)

PatternDescription
SequentialA - B - C, output feeds next
ParallelA splits to B + C, merge at D
ConditionalRoute based on output value
Magentic-OneMulti-agent collaboration with shared context
Human-in-the-loopPause at checkpoint, await approval

MAF vs Foundry Agents SDK

Both deploy to Foundry Hosted Agents. Choose based on how much control you need:

DimensionMicrosoft Agent FrameworkFoundry Agents SDK (azure-ai-projects)
OrchestrationYou write it explicitlyFoundry manages it
ControlFull - every step is codeDeclarative - Foundry decides execution
ComplexityHigher - you build the plumbingLower - portal or SDK, Foundry does the rest
Graph workflowsYesNo
Harness (planning + memory)YesNo
Best forComplex multi-agent, custom routing, long-running tasksStandard agents, rapid prototyping, team without ML engineers
HostingFoundry, Azure Container Apps, any runtimeFoundry 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

ResourceLink
Documentationlearn.microsoft.com/agent-framework
GitHubgithub.com/microsoft/agent-framework
Build 2026 announcementdevblogs.microsoft.com/agent-framework
Migration from AutoGenMigration guide
Migration from Semantic KernelMigration 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.