Skip to content
MfPy

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.

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.

PackageStatus
agent-framework-coreStable — always released in lockstep with agent-framework
agent-framework-foundryStable
agent-framework-openaiStable
agent-framework-declarativeStable (left beta during 2026)
agent-framework-orchestrationsStable (left beta during 2026)
agent-framework-ag-uiStable
agent-framework-github-copilotStable
agent-framework-a2aBeta (1.0.0bYYMMDD line)
agent-framework-copilotstudioBeta
agent-framework-mem0Beta
agent-framework-anthropicBeta
agent-framework-bedrockBeta
agent-framework-gemini, agent-framework-mistral, agent-framework-ollamaBeta
agent-framework-azurefunctionsBeta
agent-framework-durabletaskBeta
agent-framework-redisBeta
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 packagesBeta

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).

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")

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 Never
from 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.

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 path
factory = AgentFactory()
agent = factory.create_agent_from_yaml_path("agent.yaml")
response = await agent.run("Hello!")
# Method 2: from inline YAML
yaml_content = """
kind: Prompt
name: GreetingAgent
instructions: 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 to False only for YAML you fully control.
  • additional_mappings={...} extends the built-in provider table — point a custom Provider.ApiType key at your own SupportsChatGetResponse implementation 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 FileCheckpointStorage
from agent_framework.declarative import WorkflowFactory
from 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 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, ChatContext
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import DefaultAzureCredential
@chat_middleware
async 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.

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 TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from 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 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_middleware
from azure.ai.contentsafety.aio import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeTextOptions
from azure.core.credentials import AzureKeyCredential
cs_client = ContentSafetyClient("https://<region>.cognitiveservices.azure.com/",
AzureKeyCredential("<key>"))
@chat_middleware
async 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()

The framework is async-first:

  • Agents expose await agent.run(...) and async for update in agent.run(..., stream=True): ....
  • Chat clients implement the SupportsChatGetResponse protocol — await client.get_response(...).
  • Checkpoint storage (FileCheckpointStorage, InMemoryCheckpointStorage) exposes awaitable save, load, get_latest, list_checkpoints, list_checkpoint_ids and delete.
  • A2AAgent uses httpx.AsyncClient under the hood; pass your own with http_client= for custom TLS or retries, or auth_interceptor= for auth.

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, FileHistoryProvider
from agent_framework.mem0 import Mem0ContextProvider
from 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.

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 Agent
from agent_framework.devui import serve
from 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. Use mode="user" for shareable demos — it returns generic errors and locks down the management endpoints.
  • Bearer-token auth is on by default (auth_enabled=True). Without auth_token= or DEVUI_AUTH_TOKEN, a loopback server generates a token and logs it at start-up; set DEVUI_AUTH_TOKEN to keep it stable across restarts.
  • auth_enabled=False is only allowed on loopback hosts. Binding to a network address such as host="0.0.0.0" without a token raises ValueError at 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).

  • 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 FileCheckpointStorage for local, or wrap a CheckpointStorage-compatible backend for cloud storage.
  • Durable agents on Azure Functions. agent-framework-azurefunctions + agent-framework-durabletask expose DurableAIAgent, DurableAIAgentClient, and AgentFunctionApp for long-running orchestrations.
  • Multiple LLM providers. Swap Foundry, OpenAI, Anthropic, Bedrock, Ollama, and local Foundry via the chat-client of the same interface (SupportsChatGetResponse).

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, FileHistoryProvider
from 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.jsonl
await 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.

from agent_framework import Agent, MCPStreamableHTTPTool, MCPStdioTool
from 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 Agent
from agent_framework.openai import OpenAIChatClient
from 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.

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.

DateVersionChanges
2026-10-251.23.0MCP section: WebSocket transport removed (MCP SDK 2.x); mcp_client= noted.
2026-10-251.22.0Middleware 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.