Microsoft Agent Framework

ms-agent-framework · microsoft/agent-framework · ★ 11k · last commit 2026-05-26

Primitive shape

No installable primitives

Summary

Microsoft Agent Framework (MAF) — Summary

Microsoft Agent Framework (MAF) is an open, production-grade framework for building AI agents and multi-agent workflows in Python and .NET (C#), maintained by Microsoft Foundry. It ships a graph-based orchestration engine supporting sequential, concurrent, handoff, and group-collaboration patterns with checkpointing, streaming, and human-in-the-loop control. MAF includes a DevUI web dashboard (localhost:8080) for interactive agent development, observability via built-in OpenTelemetry integration, and Foundry-hosted agent deployment with two additional lines of code. It supports declarative YAML agent definitions and an Agent Skills concept for domain-specific knowledge bases.

MAF is most similar to claude-flow from the seeds — both target multi-agent orchestration with code-class subagent definitions and production deployment intent — but differs sharply: MAF is a Python/.NET SDK (not a CLI plugin), exposes a graph-based workflow runtime with checkpointing and time-travel debugging, integrates with Azure AI Foundry as first-class hosting, and ships a dedicated DevUI sample app rather than relying on the IDE.

Overview

Microsoft Agent Framework — Overview

Origin

Microsoft Agent Framework (MAF) was created by Microsoft Foundry to serve teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET. It offers migration paths from both Semantic Kernel and AutoGen, positioning itself as the unified enterprise agent SDK for the Microsoft ecosystem.

Philosophy

From the README:

"MAF is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET, while keeping architecture choices open as requirements evolve."

The framework explicitly targets production requirements: durability, restartability, observability, governance, and human-in-the-loop control. It is graph-based (not prompt-chaining) by default, treating agent communication as data flow through typed nodes.

Manifesto Quotes

"It supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment."

"Foundry Hosted Agents (new): Deploy and host your agents to Foundry-hosted infrastructure with just 2 additional lines of code."

"Agent Skills: Build domain-specific knowledge bases from multiple sources—files, inline code, class libraries—for agents to discover and use."

Target Audience

Enterprise development teams building multi-agent systems in Python or C#/.NET, migrating from Semantic Kernel or AutoGen, or integrating with Azure AI Foundry.

Key Differentiators

Dual-language (Python + .NET C#) with consistent APIs
Graph-based orchestration (not linear chain) with checkpointing and time-travel
Foundry-hosted deployment (2 lines of code to cloud)
Built-in OpenTelemetry distributed tracing
Declarative YAML agent definitions
DevUI sample app for development/debugging

Architecture

Microsoft Agent Framework — Architecture

Distribution

Python: pip install agent-framework (PyPI: agent-framework)
.NET: dotnet add package Microsoft.Agents.AI (NuGet)
DevUI: pip install agent-framework-devui --pre

Directory Structure

python/
  packages/
    core/           # Core agent + workflow engine
    devui/          # DevUI web app + API server
    foundry/        # Azure Foundry integration
    foundry_hosting/
    declarative/    # YAML agent definitions
    chatkit/        # Chat UI components
    a2a/            # Agent-to-Agent protocol
    ag-ui/          # AG-UI integration
    anthropic/      # Anthropic provider
    azure-ai-search/
    bedrock/        # AWS Bedrock provider
    claude/
    copilotstudio/  # Copilot Studio integration
    gemini/
    github_copilot/
    ... (20+ provider packages)
  samples/
    02-agents/      # Single agent examples
    03-workflows/   # Multi-agent workflow examples
    04-hosting/     # Foundry-hosted agent samples
dotnet/
  src/              # C#/.NET source
  samples/
declarative-agents/ # YAML declarative definitions
docs/
schemas/

Required Runtime

Python >= 3.10 (Python path)
.NET SDK (C# path)
Azure credentials (for Foundry-hosted features)
Docker (optional, for DevUI)

Install Complexity

pip install agent-framework installs all sub-packages. DevUI: pip install agent-framework-devui --pre. Multi-step for Azure/Foundry integration (requires az login).

Target AI Tools

Azure OpenAI
OpenAI
Anthropic Claude
Google Gemini
AWS Bedrock
GitHub Copilot SDK
Microsoft Foundry (first-class)
Any OpenAI-compatible API

DevUI

Binary: devui ./agents --port 8080
Port: 8080 (default)
Tech stack: React frontend + Python FastAPI backend
Features: agent/workflow discovery, interactive chat, sample gallery, Bearer token auth

Components

Microsoft Agent Framework — Components

Core SDK Primitives

Agent Class

Agent — Base agent class wrapping an LLM client with instructions, tools, and middleware

Workflow Patterns (Graph Nodes)

Sequential node — Run agents one after another
Concurrent node — Fan out to multiple agents in parallel
Handoff node — Transfer control between agents
Group Collaboration node — Coordinated multi-agent group
Human-in-the-loop node — Pause for human approval/input

Middleware System

Request/response middleware pipeline for pre/post processing, exception handling, custom pipelines

Client Adapters (Provider Packages)

FoundryChatClient — Azure Foundry
OpenAIChatClient — OpenAI
AnthropicChatClient — Anthropic
BedrockChatClient — AWS Bedrock
GeminiChatClient — Google Gemini
GithubCopilotChatClient — GitHub Copilot

Declarative Agents

YAML-format agent definitions in declarative-agents/ for configuration-as-code

Agent Skills

Domain-specific knowledge bases from files, inline code, or class libraries
Design documented in docs/decisions/0021-agent-skills-design.md

DevUI Package (`agent-framework-devui`)

serve(entities, port, auto_open) — Programmatic API to launch dev UI
devui ./agents --port 8080 — CLI for directory-based agent discovery
API server at /v1/* endpoints
Sample entity gallery for onboarding

Scripts

devsetup.sh — Developer environment setup
Python pre-commit hooks (.pre-commit-config.yaml)
pyright type checking (pyrightconfig.samples.json)

Labs (Experimental)

python/packages/lab/ — Benchmarking, reinforcement learning, research packages

AF Labs

Benchmarking framework
Reinforcement learning capabilities
Research initiatives

Prompts

Microsoft Agent Framework — Prompts

Verbatim Excerpt 1: Basic Agent Construction Pattern

From python/README.md quickstart:

agent = Agent(
  client=FoundryChatClient(
      credential=AzureCliCredential(),
  ),
  name="HaikuAgent",
  instructions="You are an upbeat assistant that writes beautifully.",
)

print(await agent.run("Write a haiku about Microsoft Agent Framework."))

Prompting technique: Direct instructions parameter as system prompt. Agent is given an identity and purpose inline. Simple string instructions become the system prompt for every call.

Verbatim Excerpt 2: DevUI Serve API (from devui/README.md)

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from agent_framework.devui import serve

def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"Weather in {location}: 72°F and sunny"

# Create your agent
agent = Agent(
    name="WeatherAgent",
    client=OpenAIChatClient(),
    tools=[get_weather]
)

# Launch debug UI - that's it!
serve(entities=[agent], auto_open=True)
# → Opens browser to http://localhost:8080

Prompting technique: Tool-augmented agent with Python function as tool. Function docstring serves as tool description. No explicit system prompt shown — relies on default behavior.

Verbatim Excerpt 3: Declarative YAML Agent (from declarative-agents/ pattern)

# YAML-defined agent (declarative format)
name: MyAgent
instructions: |
  You are a helpful assistant for enterprise workflows.
  Always respond in structured formats when possible.
tools:
  - type: code_interpreter
  - type: file_search
model: gpt-5.4-mini

Prompting technique: YAML-as-code declarative definition. Instructions as multiline string. Tool bindings declared by type, not code.

Observations

MAF does not ship pre-written "agent behavior" prompts in the way skill-pack frameworks do. The framework's value is in orchestration and hosting infrastructure, not in pre-authored agent behaviors. Prompt content is entirely user-defined.

Uniqueness

Microsoft Agent Framework — Uniqueness

Differs From Seeds

MAF is closest to claude-flow among the 11 seeds — both target production multi-agent orchestration. However MAF differs fundamentally: it is a Python/.NET SDK library (not a Claude Code plugin), provides Azure Foundry as first-class cloud hosting, ships a graph-based workflow runtime with checkpointing/time-travel debugging (claude-flow uses linear hive-mind coordination), and includes OpenTelemetry distributed tracing rather than SQLite-based local memory. Unlike any seed framework, MAF targets enterprise developers who need provider flexibility (Azure OpenAI + OpenAI + Anthropic + Bedrock + Gemini) and governance features. The dual-language support (Python + C#/.NET) is unique in the corpus.

Positioning

Enterprise SDK for teams building production AI agents. Positioned as the official Microsoft-blessed successor to both Semantic Kernel and AutoGen for production agent workloads. The integration with Azure AI Foundry for hosted deployment differentiates it from all seeds.

Observable Failure Modes

Azure lock-in risk: Best features (hosting, durability, checkpointing) require Azure Foundry — teams on AWS/GCP miss out on first-class support
DevUI is a sample app: Documentation explicitly warns DevUI is "not intended for production use" — teams may outgrow it quickly
Token cost opacity: No built-in token accounting across multi-model workflows
Pre-release packages: Some packages (devui) require --pre flag — stability unclear
No JavaScript/TypeScript: Python and .NET only; browser-based agents need separate tooling

What Makes It Interesting

The only framework in this batch that ships a complete production-hosting pathway (Foundry) as part of the same SDK, alongside a graphical DevUI for development. The time-travel debugging feature for workflows is not seen in any seed framework.

Workflow

Microsoft Agent Framework — Workflow

Development Phases

Phase	Artifact	Description
Define Agent	`Agent(client=..., instructions=..., tools=[...])`	Instantiate agent with provider client
Define Workflow	Workflow graph (Python code or YAML)	Connect agents via sequential/concurrent/handoff nodes
Local Dev	DevUI at localhost:8080	Interactive testing via devui CLI or `serve()`
Test	Sample tests, pytest	Validate workflow behavior
Deploy (Local)	uvicorn/gunicorn	Standard Python app hosting
Deploy (Foundry)	`+2 lines of code`	Push to Azure Foundry hosted infrastructure

Approval Gates

Human-in-the-loop node — explicit pause point requiring human approval/input within workflow
DevUI auth token — Bearer token required for direct API calls (security gate)

Gate types: yes-no (human-in-the-loop), typed-confirm (Bearer token)

Workflow Orchestration Patterns

Workflows are defined as graphs:

from agent_framework import Sequential, Concurrent, Handoff

workflow = Sequential([
    agent_a,
    Concurrent([agent_b, agent_c]),
    agent_d
])

Supports checkpointing, streaming output, and time-travel debugging of workflow state.

Spec/Config Format

YAML for declarative agents (in declarative-agents/)
Python code for programmatic workflow graphs
No per-feature spec folder convention

State/Artifact Flow

User prompt
  → Agent (LLM client + tools + middleware)
  → Workflow graph traversal
  → Streaming output (token-by-token)
  → Foundry-hosted state persistence (optional)
  → OpenTelemetry traces/spans

Memory Context

Microsoft Agent Framework — Memory & Context

State Storage

Foundry-hosted: Azure Foundry manages state persistence for hosted agents
Workflow checkpoints: In-memory checkpoints during graph traversal with time-travel debugging capability
No built-in local persistence layer documented — state is in-memory per session unless using Foundry hosting
Agent Skills: Domain knowledge bases from files, code, or class libraries (file-based knowledge, read-only)

Memory Type

In-memory during execution. Azure Foundry for cloud-hosted persistent state.

Context Handoff

Workflow graph nodes pass context as typed messages between agents. The graph runtime manages context propagation.

Compaction

Not documented. The framework does not ship a context compaction mechanism — this is delegated to the underlying LLM client (Azure OpenAI, etc.).

Cross-Session State

Only available via Foundry-hosted agents, which manage conversation history and agent state externally.

OpenTelemetry Observability

Built-in OpenTelemetry integration for distributed tracing. Every agent call, tool call, and workflow transition produces spans. Traces are exportable to any OTel-compatible backend.

State Files

None for local usage. Foundry cloud manages state server-side.

Memory Persistence Level

Local usage: session (in-memory)
Foundry-hosted: global (managed by Azure)

Orchestration

Microsoft Agent Framework — Orchestration

Multi-Agent Support

Yes. MAF is designed primarily for multi-agent systems.

Orchestration Pattern

Graph-based (hierarchical / parallel-fan-out / sequential — all supported simultaneously within one workflow graph):

Sequential: agents run one after another
Concurrent: fan-out to multiple agents in parallel
Handoff: pass control from one agent to another
Group Collaboration: coordinated multi-agent coordination

Max Concurrent Agents

Unknown (not documented with a cap; depends on Azure Foundry quota in hosted mode).

Isolation Mechanism

None at the code level for local execution. Foundry-hosted agents run in isolated cloud containers (isolation handled by Azure infrastructure, not by the framework SDK itself).

Subagent Definition Format

code-class — agents are Python class instances (Agent(...)) or YAML-defined objects (declarative format).

Spawn Mechanism

Direct Python instantiation or declarative YAML loading. No runtime dynamic spawning mechanism beyond the graph definition.

Multi-Model Usage

Yes. MAF supports different model clients per agent node. A workflow can use GPT-5.4 for planning, Claude for coding, Gemini for analysis — each Agent instance takes its own client parameter.

Execution Mode

Event-driven / interactive-loop. Workflows are driven by user prompt inputs, run to completion (or to a human-in-the-loop gate), and return streaming or final output.

Consensus Mechanism

None. Agents communicate via typed message passing in the graph; no voting/consensus protocol.

Prompt Chaining

Yes. One workflow stage's output is the input to the next agent in the graph — classic prompt chaining.

Crash Recovery

Workflow checkpointing provides state restoration. Foundry-hosted agents have durability guarantees.

Context Compaction

Not handled by the framework — delegated to underlying LLM client.

Cross-Session Handoff

Via Foundry-hosted state only.

Streaming Output

Yes. Token-by-token streaming is supported.

Ui Cli Surface

Microsoft Agent Framework — UI / CLI Surface

CLI Binary

DevUI CLI: devui binary (from agent-framework-devui package)
Subcommands: devui ./agents --port <N> (directory-based agent discovery mode)
Not a wrapper around Claude/Codex — MAF is its own runtime

Local Web Dashboard (DevUI)

Exists: Yes
Type: web-dashboard
Port: 8080 (default)
Tech stack: React frontend + Python FastAPI/uvicorn backend
Features:
- Agent/workflow discovery from directory structure
- In-memory entity registration via serve() API
- Sample entity gallery (curated examples for onboarding)
- Interactive chat/run interface
- Bearer token authentication (development token auto-logged at startup)
- Direct API access at /v1/*

DevUI Usage

# Directory-based
devui ./agents --port 8080

# Programmatic
from agent_framework.devui import serve
serve(entities=[agent], auto_open=True)

Observability

OpenTelemetry: Built-in distributed tracing — every agent call, tool call, and workflow transition produces spans
Exportable to any OTel backend (Jaeger, Zipkin, Azure Monitor, etc.)
No dedicated log viewer in DevUI (traces exported externally)

IDE Integration

None documented. Framework is SDK-only — no VS Code extension, no Kiro integration.

Cross-Tool Portability

Medium. Works with any LLM provider via adapters. Not tied to a specific IDE or AI client. Python/.NET only (no JavaScript/TypeScript native support for framework core).

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.

Distribution

Type: standalone-repo
License: MIT
Install: multi-step

Surfaces

CLI binary: devui
CLI subcmds: 1
Local UI: web-dashboard
UI port: 8080
Tech stack: React frontend + Python FastAPI backend

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 2
Templates: 3

Workflow

Phases: 5
Approval gates: 1
Spec format: yaml
Spec storage: flat-files
Delta or full: whole-file

Orchestration

Multi-agent: Yes
Pattern: parallel-fan-out
Isolation: none
Consensus: none
Prompt chaining: Yes

Multi-model

Multi-model: Yes
BYOK: Yes
Modal: text+vision

Execution

Mode: event-driven
Crash recovery: Yes
Compaction: No
Session handoff: Yes
Streaming: Yes

Memory

Type: none
Persistence: session
Search: none

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: Yes
Audit format: proprietary
Replay: Yes

Tools

Primary: Azure AI Foundry
Targets: 7
Portability: high

Signals

Stars: 11k
Last commit: 2026-05-26
Maintainer: active
Quality score: 5/10

Summary

Microsoft Agent Framework (MAF) — Summary

Overview

Microsoft Agent Framework — Overview

Origin

Philosophy

Manifesto Quotes

Target Audience

Key Differentiators

Architecture

Microsoft Agent Framework — Architecture

Distribution

Directory Structure

Required Runtime

Install Complexity

Target AI Tools

DevUI

Components

Microsoft Agent Framework — Components

Core SDK Primitives

Agent Class

Workflow Patterns (Graph Nodes)

Middleware System

Client Adapters (Provider Packages)

Declarative Agents

Agent Skills

DevUI Package (agent-framework-devui)

Scripts

Labs (Experimental)

AF Labs

Prompts

Microsoft Agent Framework — Prompts

Verbatim Excerpt 1: Basic Agent Construction Pattern

Verbatim Excerpt 2: DevUI Serve API (from devui/README.md)

Verbatim Excerpt 3: Declarative YAML Agent (from declarative-agents/ pattern)

Observations

Uniqueness

Microsoft Agent Framework — Uniqueness

Differs From Seeds

Positioning

Observable Failure Modes

What Makes It Interesting

Workflow

Microsoft Agent Framework — Workflow

Development Phases

Approval Gates

Workflow Orchestration Patterns

Spec/Config Format

State/Artifact Flow

Memory Context

Microsoft Agent Framework — Memory & Context

State Storage

Memory Type

Context Handoff

Compaction

Cross-Session State

OpenTelemetry Observability

State Files

Memory Persistence Level

Orchestration

Microsoft Agent Framework — Orchestration

Multi-Agent Support

Orchestration Pattern

Max Concurrent Agents

Isolation Mechanism

Subagent Definition Format

Spawn Mechanism

Multi-Model Usage

Execution Mode

Consensus Mechanism

Prompt Chaining

Crash Recovery

Context Compaction

Cross-Session Handoff

Streaming Output

Ui Cli Surface

Microsoft Agent Framework — UI / CLI Surface

CLI Binary

Local Web Dashboard (DevUI)

DevUI Usage

DevUI Package (`agent-framework-devui`)