Microsoft Agent Framework Python 1.15.0: A Practical Upgrade Guide

Microsoft Agent Framework Python 1.15.0 is a focused upgrade for teams building production agents and multi-agent workflows. The August 21 GitHub release adds optional A2UI support, a first-class middleware failure signal, stronger workflow checkpoint registration, resilient hosted-agent recovery, and fixes for streamed tool calls, MCP tool-name collisions, and message-history growth. PyPI lists agent-framework 1.15.0 as the current stable package, released on August 22, with Python 3.10+ support.

The practical takeaway: upgrade when you need generated interfaces, clearer middleware error handling, or better long-running workflow behavior—but test observability and streaming consumers because 1.15.0 includes a breaking OpenTelemetry semantic-convention change.

What changed in Microsoft Agent Framework 1.15.0

Microsoft’s signed python-1.15.0 release groups the changes into additions, behavior changes, and fixes. It is not a new agent programming model; it is a stability and integration release for the Python framework.

This release should be read as an operational upgrade. The most valuable changes are not a single new model connector; they are the boundaries around agent execution, state, UI streaming, and telemetry.

Installation and compatibility

PyPI lists the stable package as agent-framework 1.15.0 and documents Python 3.10 or newer on Windows, macOS, and Linux. For a complete development installation:

1python -m venv .venv
2source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
3python -m pip install --upgrade pip
4python -m pip install agent-framework==1.15.0

The meta-package includes the framework’s core and optional integrations. For a smaller deployment, Microsoft documents selective packages such as agent-framework-core, agent-framework-foundry, and provider-specific packages. Pin the version in production rather than relying on an unbounded install, then upgrade individual integrations deliberately.

A minimal agent still follows the familiar pattern:

1import asyncio
2from agent_framework import Agent
3from agent_framework.openai import OpenAIChatClient
4
5async def main() -> None:
6    agent = Agent(
7        client=OpenAIChatClient(),
8        instructions="Answer briefly and identify uncertainty.",
9    )
10    result = await agent.run("Explain why workflow checkpoints matter.")
11    print(result)
12
13if __name__ == "__main__":
14    asyncio.run(main())

The example uses the public package shape documented on PyPI. Provider credentials and model configuration remain environment- or constructor-specific, so do not copy a production key into source code.

The 1.15.0 execution path

The release’s changes make more sense as one request path rather than isolated bullet points. A user request enters an agent or workflow, passes through middleware and tools, optionally emits A2UI-compatible streaming events, and can be checkpointed for recovery.

The important design principle is explicit control flow. A middleware policy failure should be distinguishable from a provider timeout. A streamed tool call should retain its identity across the UI boundary. A resumed workflow should deserialize known checkpoint types instead of guessing from arbitrary payloads.

A2UI and streamed tool-call identity

Version 1.15.0 adds optional A2UI support across agent-framework-ag-ui and agent-framework-openai. The release notes also call out preservation of streaming tool-call indices for A2UI consumers.

That matters when a frontend renders a tool call before the final assistant message arrives. If the consumer loses the tool-call index, it can attach a later argument fragment to the wrong tool, duplicate a status card, or show a result under the wrong step. The fix is especially relevant to applications that combine AG-UI protocol patterns with streamed multi-tool runs.

Treat A2UI as an optional presentation contract, not as permission to expose every backend capability to the browser. Keep authorization, tool allowlists, and server-side validation outside the generated interface layer.

MiddlewareFailure: make policy stops observable

Middleware frequently handles authentication, budgets, tenant policy, redaction, retries, and tool authorization. Before a dedicated fatal signal, a middleware component could raise a generic exception or return an ambiguous result. Downstream code then had to infer whether the run should retry, ask the user for approval, or stop permanently.

MiddlewareFailure gives the pipeline a named failure state. A useful policy is:

1. Validate identity and tenant permissions before model execution.
2. Reject unauthorized tools as a fatal policy failure.
3. Retry transient provider and network errors separately.
4. Record the policy reason without logging secrets or full prompts.
5. Surface a safe user-facing message while keeping diagnostic detail in protected telemetry.

Do not automatically retry a permission failure. Retrying the same unauthorized tool call can turn a clear security boundary into a noisy loop.

Checkpoints, retries, and long-running agents

The release adds a process-wide workflow checkpoint type registry and registers Cosmos checkpoint state types in the related integration. It also adds steering, retry, and recovery support for resilient Foundry Hosted Agents.

A checkpoint is useful when an agent workflow has durable stages such as retrieval, approval, tool execution, and final delivery. The application should persist enough state to resume safely, but not blindly serialize credentials, raw access tokens, or sensitive tool output.

A production recovery policy can look like this:

Checkpoint registration improves consistency, but it does not make arbitrary state safe. Define versioned schemas, test forward and backward compatibility, and include an idempotency key for external side effects.

For background jobs, compare this approach with the harness engineering patterns for AI coding agents: the shared lesson is that reliable agents need explicit recovery rules, not just a larger context window.

MCP and tool-boundary changes

The 1.15.0 release clarifies skill-script arguments and MCP tool argument filtering. It also fixes remote MCP tool-name shadowing while retaining the documented argument allowlist.

These changes are useful because MCP integrations create two separate risks:

• A tool can be technically reachable but outside the current task’s authorization scope.
• Two remote sources can expose confusing or colliding names, making logs and model-selected calls difficult to audit.

Use a narrow allowlist per agent role. Validate arguments on the server even when the framework filters them. Namespace tools in logs with the server identity, not just the short tool name. If you are migrating stateless MCP infrastructure, the MCP 2026-07-28 migration guide provides useful context for transport and session decisions.

OpenTelemetry: the breaking part of the upgrade

The release consolidates OpenTelemetry GenAI semantic-convention support around stable and experimental modes with explicit message-event controls. This is the change most likely to surprise an existing deployment.

Before upgrading, inventory:

• custom span processors and exporters;
• dashboards that query old attribute names;
• redaction rules for prompts, tool arguments, and model outputs;
• alert thresholds based on token or latency attributes;
• sampling configuration for long-running workflows.

Run a staging trace through a normal agent call, a tool call, a middleware rejection, a retry, and a resumed workflow. Compare the resulting spans with your current dashboards. Do not enable message-content events merely because they are available; prompt and tool payloads can contain personal, financial, or proprietary data.

A safe upgrade checklist

1. Create a clean Python 3.10–3.13 environment and install agent-framework==1.15.0.
2. Run unit tests for agents, workflows, tools, MCP clients, and provider adapters.
3. Add a test that asserts unauthorized tools produce a non-retryable policy failure.
4. Test streamed tool calls with at least two concurrent tools and verify stable indices.
5. Restore a checkpoint in a fresh worker process, not only in the original process.
6. Exercise retry and steering behavior against a disposable hosted-agent environment.
7. Compare OpenTelemetry spans before and after the upgrade.
8. Review package locks and selectively pin integrations.
9. Deploy behind a feature flag or a small canary.
10. Watch error rates, duplicate tool calls, checkpoint resumes, latency, and telemetry volume.

A rollback plan should include the previous lockfile, database/checkpoint compatibility notes, and a way to drain or finish in-flight workflows before switching versions.

Common upgrade mistakes

Treating A2UI as an authorization layer

Generated UI describes an interaction; it should not decide whether a user can invoke a tool. Enforce identity and policy on the server.

Retrying every exception

Retry provider timeouts and selected transient failures. Do not retry MiddlewareFailure, invalid arguments, or denied approvals without a new authorization decision.

Reusing old telemetry queries blindly

Semantic-convention changes can make dashboards look empty even when the application works. Validate field names and event settings in staging.

Serializing secrets into checkpoints

Persist workflow state, not ambient credentials. Retrieve short-lived credentials again after resume and rotate them according to the provider’s policy.

Assuming the meta-package is always the right deployment

The full package is convenient for development. Production images may benefit from selective dependencies, smaller attack surface, and explicit provider ownership.

FAQ

Is Microsoft Agent Framework Python 1.15.0 stable?

Yes. PyPI lists agent-framework 1.15.0 as a production/stable package and no longer requires a pre-release install flag.

Does 1.15.0 require MCP?

No. MCP-related filtering and naming fixes are part of the release, but the framework can be used with ordinary Python functions and provider integrations.

Should every application enable A2UI?

No. Use it when your frontend benefits from structured agent-generated interface updates. Keep sensitive tool authorization and validation on the backend.

What should be tested first?

Test telemetry, streamed tool-call identity, middleware policy failures, and checkpoint restore. Those areas map directly to the release’s behavior changes and are more important than a simple import test.

Conclusion

Microsoft Agent Framework Python 1.15.0 is a reliability-oriented release for teams moving beyond toy agent demos. A2UI support improves the frontend path, MiddlewareFailure makes policy boundaries clearer, checkpoint registration strengthens workflow recovery, and MCP fixes reduce ambiguity around remote tools. The trade-off is upgrade work around OpenTelemetry conventions and any code that assumes older streaming or failure behavior.

For most production teams, the safest path is a pinned canary upgrade with trace comparison and explicit tests for authorization, tool streaming, and workflow resume. That gives you the release’s operational improvements without turning a framework update into an uncontrolled agent behavior change.

Sources and visual credits

• Microsoft Agent Framework Python 1.15.0 release notes — primary release source.
• agent-framework 1.15.0 on PyPI — package version, compatibility, installation, and examples.
• Microsoft Agent Framework documentation — official concepts and setup reference.
• AG-UI Protocol: Connect AI Agents to Real-Time Frontends — internal contextual reference.
• Harness Engineering for AI Coding Agents — internal contextual reference.
• MCP 2026-07-28: Stateless HTTP Migration Guide — internal contextual reference.

Visual credit: the Mermaid execution-path diagram is an original editorial diagram by Essam Amdani, based on the release notes and official framework documentation; it is not an official Microsoft architecture diagram. The comparison table is an original editorial summary of the cited release and package sources.