Skip to content
Agent Guides

Microsoft Agent Framework (Python)

Unified agent SDK that merges Semantic Kernel and AutoGen into one Pythonic library. Build single agents, multi-agent orchestration, cross-framework collaboration (A2A), and declarative workflows against the same primitives.

Install

Terminal window
pip install agent-framework

Version

Core 1.2.2 stable · providers 1.0.0b260429 beta · May 2026 · Python 3.10 – 3.13

Best for

Azure-native agents, multi-agent orchestration via WorkflowBuilder, cross-framework A2A, declarative YAML agents.

Zero → Hero

Section titled “Zero → Hero”

A guided reading order across the comprehensive guide, 2025 features, advanced and production docs. Each checkpoint is a section — read linearly or dive in wherever suits you.

1 · Setup & core fundamentals Install, architecture, unified SDK, authentication · 20 min
2 · Your first agent Agent basics, lifecycle, task execution · 20 min
3 · Model providers OpenAI, Azure OpenAI, Foundry, Anthropic, Ollama, Bedrock · 15 min
4 · Tools @tool, FunctionTool, approval gates, schemas, runtime context · 15 min
5 · MCP integration MCPStdioTool, MCPStreamableHTTPTool, MCPWebsocketTool · 20 min
6 · Skills Progressive-disclosure domain knowledge, scripts, resources · 15 min
7 · Middleware Agent / chat / function middleware, redaction, retries · 20 min
8 · Multi-agent orchestration Sequential, Concurrent, Handoff, GroupChat, Magentic · 30 min
9 · Human in the loop request_info, response_handler, orchestration HITL, tool approval · 20 min
10 · Checkpointing Persist and resume workflows across restarts · 15 min
11 · Compaction Sliding window, summarization, token-budget strategies · 15 min
11b · Sessions & history AgentSession, FileHistoryProvider, custom storage backends · 15 min
12 · Observability & telemetry OpenTelemetry spans, metrics, logs, Azure Monitor · 20 min
13 · Evaluation evaluate_agent, LocalEvaluator, @evaluator, ground-truth checks · 20 min
14 · Structured output Pydantic schemas, validation, type-safe responses · 15 min
15 · Graph workflows Directed graphs, streaming, time-travel · 25 min
15b · Functional workflows @workflow, @step, RunContext, HITL, checkpointing · 20 min
16 · Declarative agents YAML/JSON config, Pydantic validation · 15 min
17 · A2A protocol Interop with OpenAI SDK, Claude SDK, LangGraph, Google ADK · 20 min
18 · Production Azure Container Apps, scaling, security, DR · 30 min

Jump to a topic

Section titled “Jump to a topic”
Model providers (OpenAI, Azure, Foundry, Anthropic, Ollama, Bedrock)
Multi-agent orchestration (5 builders)
Middleware — agent / chat / function
Tools — @tool & FunctionTool
MCP tools (stdio, streamable HTTP, websocket)
Skills — progressive-disclosure knowledge
Human in the loop — request_info & approval
Checkpointing — pause/resume workflows
Compaction — stay inside the context window
Sessions & history — AgentSession, FileHistoryProvider
Observability & telemetry (OpenTelemetry)
Evaluation — evaluate_agent, LocalEvaluator
Agent lifecycle
Pydantic structured output
Graph workflows
Functional workflows (@workflow / @step)
A2A cross-framework
Declarative YAML agents
Content safety
Async best practices

Reference

Section titled “Reference”
Model providers Every first-party chat client — real constructors.
Multi-agent orchestration Sequential, Concurrent, Handoff, GroupChat, Magentic.
Middleware Agent / chat / function pipelines, short-circuit patterns.
Tools @tool decorator, FunctionTool, approval, schemas, context.
MCP integration Stdio, streamable HTTP, websocket — approval and headers.
Skills Progressive-disclosure knowledge via Skill / SkillsProvider.
Human in the loop request_info, response_handler, tool approval, resume.
Checkpointing File / in-memory storage, custom backends, resume semantics.
Compaction Sliding window, summarization, token-budget strategies.
Sessions & history AgentSession, history providers, multi-provider audit logs, cross-process serialization.
Observability & telemetry OpenTelemetry spans, metrics, logs, Azure Monitor integration.
Evaluation evaluate_agent, evaluate_workflow, LocalEvaluator, @evaluator.
Comprehensive guide Single-page technical reference — all core concepts.
2025 features A2A, graph workflows, declarative agents, OpenTelemetry.
Functional workflows @workflow, @step, RunContext HITL, as_agent(), checkpointing.
Advanced Azure AI Agents, production deployment patterns.
Recipes Copy-paste code for common scenarios.
Diagrams System architecture, lifecycle, orchestration.
Production guide Azure Container Apps, Kubernetes, CI/CD, compliance.

What’s shipped (May 2026 introspection)

Section titled “What’s shipped (May 2026 introspection)”
  • Stable core APIs — agent-framework-core 1.2.2 with LTS commitment.
  • First-party chat clients — agent_framework.foundry.FoundryChatClient, agent_framework.openai.OpenAIChatClient, agent_framework.anthropic.AnthropicClient, plus Bedrock / Ollama in the 1.0.0b provider line.
  • Middleware — @chat_middleware / @agent_middleware / @function_middleware decorators and base classes; pass middleware=[...] (must be a list in 2026 releases).
  • Workflows — WorkflowBuilder with .add_edge / .add_chain / .add_fan_in_edges / .add_fan_out_edges / .add_switch_case_edge_group / .add_multi_selection_edge_group; checkpoint via FileCheckpointStorage / InMemoryCheckpointStorage.
  • Functional workflows (experimental) — @workflow / @step decorators and RunContext for HITL and state — write workflows as plain async Python functions without graph wiring.
  • Declarative agents (beta) — agent_framework.declarative.AgentFactory / WorkflowFactory load from YAML.
  • A2A (beta) — one class, agent_framework.a2a.A2AAgent, wraps a remote A2A endpoint as a local Agent.

Install, minimal example

Section titled “Install, minimal example”
import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient


async def main():
    agent = Agent(
        client=OpenAIChatClient(),          # positional or keyword
        instructions="You are a helpful assistant.",
    )
    response = await agent.run("What is the Microsoft Agent Framework?")
    print(response.text)


asyncio.run(main())

Previous drafts of this page used a ChatAgent(chat_client=...) minimal example. ChatAgent is not a public class in agent-framework-core 1.2.2 — the primary agent class is Agent and the keyword is client= (not chat_client=).

Ready for the full walk-through? Start with Core Fundamentals →

Revision history

Section titled “Revision history”
DateVersionChanges
2026-05-041.0.5Added dedicated Functional Workflows page covering @workflow, @step, RunContext, FunctionalWorkflow.as_agent(). Enhanced Graphs & Declarative page with WorkflowViz examples, add_chain, add_multi_selection_edge_group, @executor decorator, and Agent.as_tool(). All verified against agent-framework-core==1.2.2 source.
2026-05-011.0.4Bumped pinned core/provider versions to agent-framework-core==1.2.2 and 1.0.0b260429 provider line. Expanded streaming, function-middleware, functional-workflow, and feature-stage code examples after re-introspecting the installed library.
2026-04-221.0.3Added dedicated pages: Tools, Skills, Checkpointing, Compaction, Observability & Telemetry, Evaluation. Zero→Hero reflow to 18 steps; Jump-to-topic grid and Reference card grid updated.
2026-04-221.0.2Added dedicated pages: Model Providers, Orchestration, Middleware, MCP, Human-in-the-loop. Verified against source of agent-framework-core==1.1.0; corrected context_providers plural-vs-singular errata.
2026-04-211.0.1Index redesigned into Zero → Hero reading order + Jump-to-topic grid using Starlight cards.
2026-04-201.0.1Version pin corrected to v1.0.1; verified via agent-framework PyPI package.
April 16, 20261.0 GAGraduated from Preview; ChatClientAgentOptions.Instructions removed; first-party connectors; Azure App Service support.
November 20251.0 PreviewInitial Python guide; multi-agent orchestration.