Microsoft Agent Framework (Python) — Feature Tour
Verified feature set across agent-framework-core and its stable and beta sub-packages: A2A, graph workflows, declarative agents, MCP, Magentic orchestration and custom executors.
Package status
Section titled “Package status”Checked 2026-11-19 by installing agent-framework 1.26.0 and reading the resolved sub-package versions. Sub-packages version independently of the meta package; run pip index versions <package> for today’s numbers.
| Package | Status |
|---|---|
agent-framework-core | Stable — always released in lockstep with agent-framework |
agent-framework-foundry | Stable |
agent-framework-openai | Stable |
agent-framework-declarative | Stable (left beta during 2026) |
agent-framework-orchestrations | Stable (left beta during 2026) |
agent-framework-ag-ui | Stable |
agent-framework-github-copilot | Stable |
agent-framework-a2a | Beta (1.0.0bYYMMDD line) |
agent-framework-copilotstudio | Beta |
agent-framework-mem0 | Beta |
agent-framework-anthropic | Beta |
agent-framework-bedrock | Beta |
agent-framework-gemini, agent-framework-mistral, agent-framework-ollama | Beta |
agent-framework-azurefunctions | Beta |
agent-framework-durabletask | Beta |
agent-framework-redis | Beta |
agent-framework-devui, agent-framework-azure-cosmos, agent-framework-azure-ai-search, agent-framework-foundry-local, agent-framework-purview, agent-framework-chatkit, agent-framework-hyperlight and the other integration packages | Beta |
The agent-framework meta package installs core plus the provider packages above in one go — including the beta ones, so no --pre flag is needed for the meta package. When you’re ready to prune dependencies, install the sub-packages directly (stable ones plainly, beta ones with --pre, e.g. pip install agent-framework-foundry and pip install --pre agent-framework-mem0).
Agent2Agent (A2A) protocol
Section titled “Agent2Agent (A2A) protocol”agent-framework-a2a works in both directions: A2AAgent wraps a remote A2A agent as a local agent, and A2AExecutor serves a framework agent (or workflow agent) over A2A. A2AAgentSession and A2AServiceSessionId carry the conversation state. Serving and auth examples are on the A2A protocol page.
from agent_framework.a2a import A2AAgent
remote = A2AAgent(url="https://analyst.example.com/a2a", name="Analyst")response = await remote.run("Summarise Q3")Workflows (graph-based orchestration)
Section titled “Workflows (graph-based orchestration)”The real workflow API is WorkflowBuilder + Executor/FunctionExecutor + Edge groups, all exported from top-level agent_framework. See Workflows & Declarative Agents for the full reference. One-glance example:
from typing_extensions import Neverfrom agent_framework import WorkflowBuilder, WorkflowContext, executor
@executor(id="research")async def research(query: str, ctx: WorkflowContext[dict]) -> None: await ctx.send_message({"data": query})
@executor(id="write")async def write(d: dict, ctx: WorkflowContext[Never, str]) -> None: await ctx.yield_output(f"report: {d['data']}")
workflow = ( WorkflowBuilder(start_executor=research, name="ContentPipeline") .add_edge(research, write) .build())Workflows support checkpointing via FileCheckpointStorage / InMemoryCheckpointStorage, fan-in / fan-out / switch-case routing, and exposing a workflow as an agent via WorkflowAgent.
Declarative agents & workflows (YAML)
Section titled “Declarative agents & workflows (YAML)”agent-framework-declarative provides AgentFactory (single agent from YAML) and WorkflowFactory (multi-agent workflow from YAML). Actions use Power Fx expressions — SetVariable, InvokeAzureAgent, InvokeFunctionTool, If, ConditionGroup, Foreach, Question, RequestExternalInput, SendActivity and others; the supported list is on the workflows page. Full reference: Microsoft Learn — Declarative Workflows.
AgentFactory — load a single agent from YAML
Section titled “AgentFactory — load a single agent from YAML”The factory parses a kind: Prompt YAML definition, picks the chat-client class from the model.provider field (AzureOpenAI, OpenAI, Foundry, …), and returns a configured Agent ready for agent.run(...).
from agent_framework.declarative import AgentFactory
# Method 1: from a YAML file pathfactory = AgentFactory()agent = factory.create_agent_from_yaml_path("agent.yaml")response = await agent.run("Hello!")
# Method 2: from inline YAMLyaml_content = """kind: Promptname: GreetingAgentinstructions: You are a friendly assistant.model: id: gpt-6.1-sol provider: AzureOpenAI"""agent = factory.create_agent_from_yaml(yaml_content)Two security-relevant knobs on the factory constructor:
safe_mode=True(default) blocks=Env.*Power-Fx lookups in the YAML so untrusted YAML can’t read your environment. Flip toFalseonly for YAML you fully control.additional_mappings={...}extends the built-in provider table — point a customProvider.ApiTypekey at your ownSupportsChatGetResponseimplementation when you want to instantiate non-first-party clients from YAML.
If you’ve already constructed a chat client (shared connection pool, custom credentials), pass it via client= so the factory reuses it instead of building a fresh one from the YAML’s model: block.
WorkflowFactory — load a multi-action workflow from YAML
Section titled “WorkflowFactory — load a multi-action workflow from YAML”WorkflowFactory parses kind: Workflow YAML and returns a real Workflow object — every action becomes a node in the graph, so checkpointing, visualisation, and pause/resume work the same as a code-built workflow.
from agent_framework import FileCheckpointStoragefrom agent_framework.declarative import WorkflowFactoryfrom agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient()
# Pre-register agents that the workflow YAML references via `kind: InvokeAzureAgent`.factory = WorkflowFactory( agents={ "Writer": client.as_agent(name="Writer", instructions="Write content."), "Reviewer": client.as_agent(name="Reviewer", instructions="Review content."), }, # Declarative actions put their own types into checkpoints; without this # allow-list every checkpoint fails to save (the run continues, logging errors). checkpoint_storage=FileCheckpointStorage( "./checkpoints", allowed_checkpoint_types=[ "agent_framework_declarative._workflows._declarative_base:ActionComplete", ], ), max_iterations=200, # raise the default 100 for GotoAction loops)
workflow = factory.create_workflow_from_yaml_path("review_pipeline.yaml")
async for event in workflow.run({"input": "draft the agent-framework launch post"}, stream=True): if event.type == "output": print(event.data)Power Fx expressions (anything starting with =, such as =System.ConversationId) are evaluated by the .NET Power Fx engine through pythonnet, so the machine needs a .NET runtime; without one the workflow fails with RuntimeError: PowerFx is not available (dotnet runtime not installed).
Pre-registering agents (agents={...}) is the common pattern when the same agent definition is reused across many workflows. For one-off agents, embed the Prompt definition inline in the YAML and let the inner AgentFactory build them.
Middleware & hooks
Section titled “Middleware & hooks”Middleware is a first-class concept in agent-framework-core. Three decorators — @chat_middleware, @agent_middleware, @function_middleware — and three base classes — ChatMiddleware, AgentMiddleware, FunctionMiddleware — let you wrap the corresponding call type:
from agent_framework import Agent, chat_middleware, ChatContextfrom agent_framework.foundry import FoundryChatClientfrom azure.identity.aio import DefaultAzureCredential
@chat_middlewareasync def logging_middleware(context: ChatContext, call_next): print(f"before: {len(context.messages)} messages") await call_next() # takes no arguments print(f"after: {context.result}")
agent = Agent( client=FoundryChatClient(credential=DefaultAzureCredential(), model="gpt-6.1-sol"), instructions="You are a helpful assistant.", middleware=[logging_middleware],)The middleware callable’s second parameter is call_next and is awaited with no arguments (the pre-GA next(context) form is gone). Renames such as ChatAgent → Agent, AgentRunResponse → AgentResponse and the removal of display_name and AggregateContextProvider are listed under breaking changes worth knowing. context_providers= takes a list, and several providers can be combined. See middleware for the full reference.
OpenTelemetry observability
Section titled “OpenTelemetry observability”agent-framework-core emits OpenTelemetry traces and metrics through the global providers (instrumentation is on unless ENABLE_INSTRUMENTATION=false). Wire it up with the standard OTel SDK, or call agent_framework.observability.configure_otel_providers():
from opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporterfrom opentelemetry import trace
trace.set_tracer_provider(TracerProvider())trace.get_tracer_provider().add_span_processor( BatchSpanProcessor(ConsoleSpanExporter()))
# Agent runs now emit invoke_agent, chat and execute_tool spans (GenAI semantic conventions)For Azure Monitor, use azure.monitor.opentelemetry.configure_azure_monitor(connection_string=...).
Content safety
Section titled “Content safety”Content safety is not a framework-specific wrapper class. Call Azure AI Content Safety directly from a middleware:
from agent_framework import ChatContext, ChatResponse, Message, MiddlewareTermination, chat_middlewarefrom azure.ai.contentsafety.aio import ContentSafetyClientfrom azure.ai.contentsafety.models import AnalyzeTextOptionsfrom azure.core.credentials import AzureKeyCredential
cs_client = ContentSafetyClient("https://<region>.cognitiveservices.azure.com/", AzureKeyCredential("<key>"))
@chat_middlewareasync def safety_guard(context: ChatContext, call_next): # Don't name the parameter `next`: it would shadow the built-in used below. last_user = next((m for m in reversed(context.messages) if m.role == "user"), None) if last_user and last_user.text: verdict = await cs_client.analyze_text(AnalyzeTextOptions(text=last_user.text)) if any((c.severity or 0) > 2 for c in verdict.categories_analysis): context.result = ChatResponse( messages=[Message(role="assistant", contents=["I can't help with that request."])] ) raise MiddlewareTermination("blocked by content safety") await call_next()Async patterns
Section titled “Async patterns”The framework is async-first:
- Agents expose
await agent.run(...)andasync for update in agent.run(..., stream=True): .... - Chat clients implement the
SupportsChatGetResponseprotocol —await client.get_response(...). - Checkpoint storage (
FileCheckpointStorage,InMemoryCheckpointStorage) exposes awaitablesave,load,get_latest,list_checkpoints,list_checkpoint_idsanddelete. A2AAgentuseshttpx.AsyncClientunder the hood; pass your own withhttp_client=for custom TLS or retries, orauth_interceptor=for auth.
Mem0 — semantic long-term memory
Section titled “Mem0 — semantic long-term memory”agent-framework-mem0 ships Mem0ContextProvider — a ContextProvider that searches a Mem0-hosted memory store before each run and persists request+response messages after. Use it for cross-session recall (“the user prefers metric units”), facts you want to surface independently of the conversation history.
from agent_framework import Agent, FileHistoryProviderfrom agent_framework.mem0 import Mem0ContextProviderfrom agent_framework.openai import OpenAIChatClient
memory = Mem0ContextProvider( api_key="m0_...", # or set MEM0_API_KEY user_id="alice@example.com", # one of user_id / agent_id / application_id is required context_prompt="## Memories\nConsider these when answering:",)
agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful assistant.", context_providers=[ FileHistoryProvider(storage_path="./sessions"), # short-term memory, # long-term semantic recall ], default_options={"store": False}, # keep history in the file, not also server-side)
async with memory: # opens the underlying Mem0 client session = agent.create_session(session_id="alice-2026") await agent.run("I'm planning a trip — remember I always want vegetarian options.", session=session) await agent.run("Suggest a weekend in Lisbon.", session=session) # The second run sees the vegetarian preference even if it's not in the recent chat history.Mem0ContextProvider accepts either an AsyncMemoryClient (cloud Mem0 platform) or AsyncMemory (open-source Mem0 instance). Pass mem0_client= when you’ve already constructed one in your app — the provider will not close a client it didn’t create.
At least one of user_id, agent_id or application_id must be set. The check runs at the start of each before_run and after_run, not in the constructor, so a missing filter surfaces as a ValueError on the first agent.run. Use application_id for tenant scoping, user_id for per-end-user memory, and agent_id when multiple agents share the same user.
Local interactive testing — DevUI
Section titled “Local interactive testing — DevUI”agent-framework-devui (re-exported as agent_framework.devui) is a built-in FastAPI/Uvicorn dev server that exposes any list of agents or workflows over an OpenAI-compatible HTTP API plus an interactive web UI. Useful for poking at an agent without writing your own front-end.
from agent_framework import Agentfrom agent_framework.devui import servefrom agent_framework.openai import OpenAIChatClient
writer = Agent( client=OpenAIChatClient(), name="writer", instructions="You write concise marketing copy.",)
# Blocks the current process — uvicorn under the hood.serve( entities=[writer, my_workflow], # mix agents and workflows host="127.0.0.1", port=8080, auto_open=True, # pop the browser instrumentation_enabled=True, # wire OpenTelemetry traces in the UI)Three knobs that matter when deploying beyond localhost:
mode="developer"(default) returns full error tracebacks and exposes admin APIs. Usemode="user"for shareable demos — it returns generic errors and locks down the management endpoints.- Bearer-token auth is on by default (
auth_enabled=True). Withoutauth_token=orDEVUI_AUTH_TOKEN, a loopback server generates a token and logs it at start-up; setDEVUI_AUTH_TOKENto keep it stable across restarts. auth_enabled=Falseis only allowed on loopback hosts. Binding to a network address such ashost="0.0.0.0"without a token raisesValueErrorat start-up. DevUI is a developer harness, not a hardened production runtime.
For directory-based discovery (one folder per agent), point at the directory instead of passing instances:
serve(entities_dir="./agents", port=8080)The dev server is also runnable from the CLI: devui ./agents --port 8080 (auth is on by default; --auth-token, --no-auth and --mode user are the related flags).
Production patterns
Section titled “Production patterns”- Package minimisation. Pin only the sub-packages you need:
pip install --pre agent-framework-foundry agent-framework-redis. - Session persistence. Use
agent.create_session()with the Redis, Cosmos, or mem0 providers depending on your backend. - Checkpointing long-running workflows. Use
FileCheckpointStoragefor local, or wrap aCheckpointStorage-compatible backend for cloud storage. - Durable agents on Azure Functions.
agent-framework-azurefunctions+agent-framework-durabletaskexposeDurableAIAgent,DurableAIAgentClient, andAgentFunctionAppfor long-running orchestrations. - Multiple LLM providers. Swap Foundry, OpenAI, Anthropic, Bedrock, Ollama, and local Foundry via the chat-client of the same interface (
SupportsChatGetResponse).
Sessions and conversation history
Section titled “Sessions and conversation history”AgentSession is a lightweight state container — provider instances live on the agent, the session only carries session_id, an optional service_session_id (for service-side history like OpenAI Responses), and a mutable state: dict[str, Any] shared across providers.
from agent_framework import Agent, AgentSession, FileHistoryProviderfrom agent_framework.openai import OpenAIChatClient
history = FileHistoryProvider(storage_path="./sessions", skip_excluded=True)agent = Agent( client=OpenAIChatClient(), context_providers=[history], default_options={"store": False}, # otherwise the Responses API also keeps the history)
session = agent.create_session(session_id="user-42") # picks up ./sessions/user-42.jsonlawait agent.run("Continue the chat", session=session)
# Session round-trips cleanly through to_dict/from_dict — handy if you want to# stash a snapshot in your own datastore alongside the JSONL.snapshot = session.to_dict()restored = AgentSession.from_dict(snapshot)Built-in providers (InMemoryHistoryProvider, FileHistoryProvider) plus the Redis/Cosmos backends in the beta sub-packages all subclass HistoryProvider. To roll your own, override get_messages() and save_messages() — the rest of the lifecycle (load_messages / store_inputs / store_outputs / store_context_messages flags) is handled by the parent.
MCP — two transports, one tool surface
Section titled “MCP — two transports, one tool surface”from agent_framework import Agent, MCPStreamableHTTPTool, MCPStdioToolfrom agent_framework.openai import OpenAIChatClient
# Streamable HTTP (most remote MCP servers)async with MCPStreamableHTTPTool( name="learn", url="https://learn.microsoft.com/api/mcp", request_timeout=30, # Per-request auth headers from agent.run(..., function_invocation_kwargs=...) header_provider=lambda kwargs: {"Authorization": f"Bearer {kwargs['token']}"},) as learn: agent = Agent(client=OpenAIChatClient(), tools=learn) await agent.run("Explain DefaultAzureCredential", function_invocation_kwargs={"token": user_token})
# Stdio (local servers — filesystem, git, sqlite, etc.)async with MCPStdioTool( name="filesystem", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],) as fs: agent = Agent(client=OpenAIChatClient(), tools=fs)Since 1.23.0 the framework runs on MCP Python SDK 2.x, which dropped the WebSocket transport (MCPWebsocketTool remains only as a deprecated stub that cannot connect) and MCP tasks. You can also pass your own entered mcp.Client with mcp_client= instead of url= or command=.
Per-tool approval gates work uniformly:
mcp = MCPStdioTool( name="git", command="uvx", args=["mcp-server-git"], approval_mode={ "always_require_approval": ["git_push", "git_reset"], "never_require_approval": ["git_status", "git_diff"], "default": "always_require", },)For hosted MCP (the provider runs the MCP client server-side), feature-detect via isinstance(client, SupportsMCPTool) and call client.get_mcp_tool(name=..., url=...). See the MCP page for full transport, header, lifecycle and approval coverage.
Magentic — manager + workers + replanning
Section titled “Magentic — manager + workers + replanning”MagenticBuilder is the most involved of the orchestration patterns: a manager agent maintains a task ledger, dispatches to workers, and can replan when a stall is detected.
from agent_framework import Agentfrom agent_framework.openai import OpenAIChatClientfrom agent_framework.orchestrations import MagenticBuilder
manager = Agent( client=OpenAIChatClient(), name="manager", instructions="You coordinate a research team. Plan, delegate, and verify.",)
workflow = MagenticBuilder( participants=[researcher, analyst, writer], manager_agent=manager, # wrapped in a StandardMagenticManager for you max_stall_count=3, # replan after three rounds without progress enable_plan_review=True, # pause after the initial plan for human review checkpoint_storage=storage, # resume across process restarts).build()To tune the ledger prompts, pass StandardMagenticManager(agent=manager, ...) as manager= instead of manager_agent=. Stall handling is max_stall_count / max_reset_count and the manager’s replanning.
The plan-review HITL event is durable — combined with checkpointing, a user can come back hours later in a different pod and approve the plan, and the workflow resumes from the exact superstep that paused.
Custom workflow executors
Section titled “Custom workflow executors”Beyond agents, workflows accept arbitrary executors. The @executor decorator is the lightweight form; subclassing Executor gives access to per-instance state and @response_handler for HITL.
from agent_framework import AgentExecutorResponse, WorkflowContext, executor
@executor( id="upper_case_executor", input=AgentExecutorResponse, output=AgentExecutorResponse, workflow_output=str,)async def upper_case( response: AgentExecutorResponse, ctx: WorkflowContext[AgentExecutorResponse, str],) -> None: upper_text = response.agent_response.text.upper() # with_text preserves the prior conversation chain so downstream # AgentExecutors still see the full history. await ctx.send_message(response.with_text(upper_text)) await ctx.yield_output(upper_text)The with_text helper on AgentExecutorResponse matters when you transform agent output and want the next AgentExecutor to retain conversation history — sending a plain str instead would invoke from_str on the downstream executor and reset its message cache.
Further reading
Section titled “Further reading”Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-10-25 | 1.23.0 | MCP section: WebSocket transport removed (MCP SDK 2.x); mcp_client= noted. |
| 2026-10-25 | 1.22.0 | Middleware examples now use call_next() (the next(context) form no longer works, and naming the parameter next broke the built-in next() in the content-safety example). Replaced an incorrect breaking-changes list (context_providers was never made singular) with a link to the current list. Corrected the Mem0 filter check (it runs per run, not at construction), DevUI auth (on by default; non-loopback without a token raises) and CLI flags, span names, and checkpoint storage methods. The WorkflowFactory example now allow-lists the declarative checkpoint type (without it no checkpoint saved) and notes the .NET runtime needed for Power Fx. History-provider examples on OpenAIChatClient now set store=False. |