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

pip install agent-framework

Version

Core 1.18.0 stable · agent-framework-foundry and agent-framework-openai bundled via agent-framework==1.18.0 · September 2026 · Python 3.10 – 3.13 · consolidated Class & API Reference

Best for

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

Earlier drafts had fabricated APIs

Pages under this guide previously documented agent_framework.graphs.AgentGraph, agent_framework.a2a.A2AProtocolAdapter, AzureAIAgentClient, ChatAgent, ai_function, and other names that do not exist. The real primary agent class in Python is Agent; the Azure chat client is FoundryChatClient from agent_framework.foundry. Pages were rewritten in April 2026 after introspecting agent-framework-core==1.1.0 and re-verified in May 2026 against 1.5.0. See Errata in the comprehensive guide for the running list.

azure-ai-agents integration add-on — class reference

The azure-ai-agents package is an optional Microsoft add-on for the Azure AI Agents service. It is not a replacement for agent-framework — use it alongside the framework when you need direct access to Azure AI Agents service resources (see the migration notice for when to reach for it). Source-verified class reference covering the AgentsClient, thread/run/streaming model, and hosted-tool classes now lives in the Appendix: azure-ai-agents Add-on section of the comprehensive guide.

Where to start

New? Follow Zero → Hero below in order (~3–5 hours). Already shipping? Use Jump to a topic to go straight to what you need.

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

19 · Class & API Reference Consolidated, source-verified reference for every class across workflows, agents, memory, tools, security, skills, checkpointing, middleware, evaluation, settings, and A2A/declarative — plus the azure-ai-agents add-on appendix · 45 min

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

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.

Class & API Reference Consolidated, source-verified class reference — Workflows, Agents/Modes/Orchestration, Memory/Sessions, Tools/MCP, Security/FIDES, Skills, Checkpointing/Compaction, Middleware, Evaluation, Settings, A2A/Declarative — plus the azure-ai-agents add-on appendix.

10-Class Deep Dives (1.15.0) Source-verified, runnable examples for WorkflowViz, FileMemoryProvider, AgentModeProvider, BackgroundAgentsProvider, ToolApprovalMiddleware, SwitchCaseEdgeGroup, MessageInjectionMiddleware, ToolResultCompactionStrategy, SummarizationStrategy, and TokenBudgetComposedStrategy.

10-Class Deep Dives Vol. 2 (1.16.0) Source-verified deep dives for the second batch of 10 classes — verified against agent-framework 1.16.0.

10-Class Deep Dives Vol. 3 (1.17.0) Source-verified deep dives: WorkflowBuilder, SlidingWindowStrategy, TruncationStrategy, ContextWindowCompactionStrategy, LocalEvaluator, InlineSkill, FileAccessProvider, MemoryContextProvider, FileHistoryProvider, MCPWebsocketTool — all verified against agent-framework 1.17.0.

10-API Deep Dives Vol. 4 (1.18.0) Source-verified deep dives: VectorStoreField, VectorStoreCollectionDefinition, InMemoryCollection, InMemoryStore, Filter, FilterGroup, SecretString, load_settings (function), create_agent_hooks_middleware (function), GroupChatBuilder — all verified against agent-framework 1.18.0.

What’s shipped (September 2026 introspection)

• Stable core — agent-framework-core 1.18.0 (September 2026). The full class-by-class API surface — previously spread across 49 per-volume “class deep dive” pages — is now consolidated into one Class & API Reference section of the comprehensive guide (plus an azure-ai-agents add-on appendix). See the Revision history below for the version-by-version summary.
• 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.
• Skills (experimental) — MemoryStore, SkillResource, InlineSkillResource, ClassSkill, InlineSkill, FileSkill now emit ExperimentalWarning on import — do not depend on these APIs in production yet.
• 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.

Breaking changes in 2026 releases

• display_name parameter removed from agents.
• middleware= now requires a list — no longer accepts a single instance.
• AgentRunResponse / AgentRunResponseUpdate renamed to AgentResponse / AgentResponseUpdate.
• AggregateContextProvider removed — compose ContextProvider instances directly.
• context_providers stays plural in agent-framework-core==1.5.0 (verified against source). An earlier draft of this guide incorrectly said it was renamed to singular.
• output_executors= in WorkflowBuilder is deprecated in 1.5.0 — replace with output_from=. The old parameter still works but emits a warning.
• Migrating from standalone Semantic Kernel or AutoGen? See the official guide — ~2–4 hours for a typical app.

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.4.0 — 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

Date	Version	Changes
2026-09-14	1.18.0	Installed and introspected agent-framework==1.18.0 source. Added 10-API Deep Dives Vol. 4 covering eight classes (VectorStoreField, VectorStoreCollectionDefinition, InMemoryCollection, InMemoryStore, Filter, FilterGroup, SecretString, GroupChatBuilder) and two functions (load_settings, create_agent_hooks_middleware) — all with source-verified constructors, method tables, and runnable examples. Vol. 2 and Vol. 3 LinkCards added to Reference section. Version card updated to 1.18.0.
2026-09-08	1.17.0	Consistency sweep. Version card and page description moved 1.15.0 → 1.17.0 to match the newest source-verified deep dives (Vol. 3, agent-framework==1.17.0); comprehensive-guide header now states agent-framework 1.17.0 as latest and 1.14.0 as the verified-against version. Zero → Hero deep links into the 2025-features page retargeted to headings that exist. No package installation or symbol verification performed.
2026-08-24	1.15.0	Upgraded to agent-framework 1.15.0 (latest). Added 10-Class Deep Dives document covering WorkflowViz, FileMemoryProvider, AgentModeProvider, BackgroundAgentsProvider, ToolApprovalMiddleware, SwitchCaseEdgeGroup, MessageInjectionMiddleware, ToolResultCompactionStrategy, SummarizationStrategy, and TokenBudgetComposedStrategy — all source-verified with runnable examples.
2026-08-21	1.14.0	Consolidated the 49 per-volume “class deep dive” pages (base + v2–v44 main series, plus the 5-volume azure-ai-agents add-on series) into one Class & API Reference section — 11 subsections (Workflows & Execution, Agents/Modes & Orchestration, Memory/Sessions & File Stores, Tools & MCP, Security & FIDES, Skills, Checkpointing & Compaction, Middleware & Function Invocation, Evaluation, Settings & Configuration, A2A Protocol & Declarative Graphs) plus an azure-ai-agents appendix — inside the comprehensive guide. This index page was rewritten to match: old per-volume LinkCards removed, changelog condensed to this table.
2026-07-10 – 2026-08-03	1.11.0 – 1.13.0	SecureMCPToolProxy + apply_mcp_security_labels (FIDES MCP security proxy); AgentMiddlewareLayer/ChatMiddlewareLayer reworked as public MRO mixins; DevUI (DiscoveryResponse, EntityInfo); Gemini / Mistral / Anthropic-Vertex / Bedrock provider clients; AGUIThreadSnapshot + thread-state persistence; FoundrySessionStore; Foundry hosting (ResponsesHostServer / InvocationsHostServer); FileMemoryProvider.
2026-06-12 – 2026-07-09	1.8.1 – 1.10.0	ToolApprovalMiddleware + AgentLoopMiddleware + JudgeVerdict; six Supports* capability Protocols; WorkflowGraphValidator + typed validation errors; A2A (A2AAgent); declarative graphs (AgentFactory / WorkflowFactory + control-flow/basic executors); WorkflowBuilder output routing (output_from / intermediate_output_from); durable execution (agent-framework-durabletask).
2026-05-15 – 2026-06-05	1.4.0 – 1.8.0	SecureAgentConfig (FIDES/IFC prompt-injection defence: label tracking, policy enforcement, quarantined LLM calls); AgentFileStore + FileAccessProvider; harness providers (TodoProvider, MemoryContextProvider, AgentModeProvider, BackgroundAgentsProvider); WorkflowViz.
2026-04-20 – 2026-05-09	1.0.1 – 1.3.0	agent-framework-foundry and agent-framework-openai promoted to stable; dedicated pages added for Model Providers, Orchestration, Middleware, MCP, HITL, Tools, Skills, Checkpointing, Compaction, Observability, Evaluation. A 2026-05-29 pass corrected an accidental reframing of this index as an azure-ai-agents-only site — agent-framework is the primary framework; azure-ai-agents is the optional add-on.
2026-04-16	1.0 GA	Graduated from Preview; ChatClientAgentOptions.Instructions removed; first-party connectors; Azure App Service support.
2025-11	1.0 Preview	Initial Python guide; multi-agent orchestration.