Skip to main content

Python Microsoft Agent Framework Producer Example

AAEP integration with Microsoft Agent Framework (MAF), Microsoft's official agent framework that succeeded Semantic Kernel as the recommended path for building production agents on Azure and beyond.

If you're building agents with Microsoft's stack and want AAEP support — especially with Narrator integration in view — this is the example to copy.


What this example demonstrates

  • Direct integration with microsoft.agents and the MAF agent lifecycle
  • Native handling of MAF's tool/function calling system
  • MAF middleware pattern for intercepting agent steps
  • Streaming output via MAF's async response iterators
  • Tool invocation with safety-gated confirmation for irreversible operations
  • All 12 core AAEP event types emitted from MAF-driven agents
  • Compatible with Azure OpenAI, Azure AI Foundry, and OpenAI-compatible models

This example reuses the AAEPEmitter from python-minimal — same machinery, MAF-specific adapter. Everything follows the same safety contract.


When to use this pattern

Pick this pattern when:

  • You build agents with Microsoft Agent Framework
  • You target Azure AI Foundry, Azure OpenAI, or any MAF-compatible model
  • You need Narrator/Microsoft Accessibility compatibility in the long term
  • You want AAEP support that aligns with Microsoft's official agent stack

Pick python-anthropic-sdk when: you call Anthropic models directly without MAF.
Pick python-langchain when: you use LangChain rather than MAF.
Pick python-minimal when: you build agents from scratch without framework.


Installation

cd examples/producers/python-microsoft-agent-framework
pip install -e .

You'll need Microsoft Agent Framework installed (the microsoft-agents package or compatible). For Azure model access:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_API_KEY="..."

The example also runs in mock mode without any credentials, so the conformance suite can verify it in CI.

Requires Python 3.10 or newer.


Quick start

from microsoft.agents import Agent, AgentBuilder
from aaep_maf import MAFAAEPMiddleware

# Step 1: build your MAF agent normally
agent = (AgentBuilder()
    .with_model("gpt-4o")
    .with_tools(your_tools)
    .build())

# Step 2: create the AAEP middleware
def my_transport(event):
    """Send AAEP events to subscribers (HTTP/SSE, WebSocket, etc.)"""
    print(event)  # in production: serialize and send

middleware = MAFAAEPMiddleware(send_event=my_transport)

# Step 3: attach the middleware to your agent
agent.add_middleware(middleware)

# Step 4: run sessions normally — AAEP events emit automatically
result = await agent.invoke("What's my Azure budget status?")

The middleware observes agent execution and emits AAEP events without modifying the agent's behavior. Pure addition, no friction.


Running the included demo

python -m aaep_maf.example_agent

Drives a MAF-style agent through three scenarios: a basic query, a tool call, and a high-risk tool that triggers confirmation. Uses mock mode if MAF or Azure credentials aren't installed/configured.


Running the conformance suite against it

# Terminal 1: start the server (port 8083)
python -m aaep_maf.server --port 8083

# Terminal 2: run conformance
aaep-conformance producer --endpoint http://localhost:8083 --level 2

The server uses mock MAF mode by default for CI portability.


Project layout

python-microsoft-agent-framework/
├── README.md
├── pyproject.toml
├── aaep_maf/
│   ├── __init__.py
│   ├── middleware.py           # MAFAAEPMiddleware (the core integration)
│   ├── example_agent.py        # Runnable demo
│   └── server.py               # HTTP/SSE wrapper for conformance testing
└── tests/
    ├── __init__.py
    └── test_middleware.py

Key design decisions

1. Middleware pattern, not callback handler

MAF uses a middleware pattern (similar to ASP.NET Core or Express.js) where steps in the agent loop pass through a chain of middleware. Our MAFAAEPMiddleware slots into this chain, observing each step and emitting the appropriate AAEP event.

This is different from python-langchain's callback handler — MAF didn't choose the callback pattern, so we follow MAF's pattern instead. Both produce identical AAEP events; the integration shape differs.

2. Safety gates for tools fire BEFORE execution

When MAF prepares to invoke a tool, our middleware:

  1. Inspects the tool's metadata (name, irreversibility, risk)
  2. If irreversible or high-risk: emits agent.awaiting.confirmation (urgency=critical, default_decision=reject)
  3. Blocks the middleware chain until reply arrives (or timeout default)
  4. Only allows MAF to proceed on accept

MAF doesn't natively block on user input mid-execution. We achieve it via asyncio.Future synchronization, the same pattern used in the python-anthropic-sdk adapter.

3. Azure AI Foundry compatible

The example respects MAF's content-filter and grounding annotations. When MAF reports a content filter blocked output, our middleware emits a session.errored with error_category: "policy" and proper remediation hints — preserving the safety signal for AT.

4. Same emitter as python-minimal

Imports AAEPEmitter from the python-minimal package. Bug fixes propagate. Safety guarantees are uniform.


Microsoft Narrator forward compatibility

This example is positioned for eventual Narrator integration. Key alignments:

  • UIA-friendly summaries — summary_normal fields are written for screen reader announcement, not for visual display
  • Speech rate compliance — events respect the subscriber's negotiated pace_wpm and cognitive_load capabilities
  • NaviSync-ready — the streaming output format works with Narrator's natural-pause heuristics

When AAEP eventually integrates with Narrator (whether via direct adoption or a community bridge), this example will be the canonical Python reference.


See also

Metadata

Release files for aaep-maf-producer 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aaep-maf-producer 1.0.0
File Size Uploaded Provenance Actions
aaep_maf_producer-1.0.0.tar.gz 19.7 kB Without provenance Details for aaep_maf_producer-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aaep-maf-producer 1.0.0
File Interpreter ABI Platform Actions
aaep_maf_producer-1.0.0-py3-none-any.whl Python 3 none any Details for aaep_maf_producer-1.0.0-py3-none-any.whl

Total release size: 35.9 kB

Release files / aaep_maf_producer-1.0.0.tar.gz

Download URL aaep_maf_producer-1.0.0.tar.gz
Size 19.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a030049675ed7f54d2e83708ff3140f7e8f58af23ac6d1ff359f3d3be8181fe0
BLAKE2b-256 checksum
How to use checksums
4c9800311307955034b9720fe75870bbb7a796bfba5c11aeee9e3108f1d774b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / aaep_maf_producer-1.0.0-py3-none-any.whl

Download URL aaep_maf_producer-1.0.0-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fd08f22b8222090bca9e9f160e933b2ea986689b1b551976b7e341636aa522d5
BLAKE2b-256 checksum
How to use checksums
90cbbe36cfc3bb18040234cc2d211e3185e07b8f8f4fd04522b96c6b2828b053
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for aaep-maf-producer 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page