Microsoft published Agent Framework’s Python 1.25.0 release on November 7, 2026, with a breaking change for teams running shared AI assistants through its AG-UI integration. A workflow that reuses live agent executors or sessions across authorization scopes can now reject a subsequent caller before reaching the model.
AG-UI connects an assistant’s interface to its backend. An executor runs an agent; its session holds conversation history and approval state. An authorization scope identifies the person or explicitly authorized group allowed to share server-side state. Microsoft’s integration guide explains those boundaries.
Find the state your service reuses
Check your dependency lock first. The main agent-framework package is 1.25.0, but the separately versioned AG-UI package is 1.8.0. Both require Python 3.11 or later; AG-UI 1.8.0 requires Core 1.25.0 or later, below 2. Do not assume every component has the headline version.
Trace any Workflow or WorkflowAgent passed to a shared endpoint, including nested workflows. Look for objects created once at module startup, factories returning cached workflows, and new executors receiving an old session. The merged change covers shared live executors and sessions, not every Python deployment. Factories already creating independent state need no reconstruction for this particular rule; workflows without AgentExecutor are not subject to this ownership check.
Pay particular attention to builders. Microsoft’s hosting documentation explains that calling build() again can create a new workflow while reusing the executors registered earlier. In the separate WorkflowState hosting interface, even cache_target=False does not make those executors independent. The useful audit question is where each executor and session is allocated—not whether the outer workflow object is new.
Build independent state inside the factory
Use AgentFrameworkWorkflow(workflow_factory=build_workflow_for_thread). The factory must create independent workflows and sessions for separate authorization scopes. Construct the stateful executors inside it, including those in nested workflows; do not return a cached workflow or inject a session shared with another scope. This is the documented migration.
Register the shared endpoint with authorization_scope_resolver backed by authenticated request context. It should return a stable scope for the intended sharing boundary. A browser-supplied thread ID is not authority to access someone else’s state. Authentication-only dependencies can admit a request without supplying the state-ownership scope, as the AG-UI guide notes.
For a related explanation of why sign-in, permissions and approval of an action are separate decisions, see the guide to customer-agent access with Descope Envoy.
A factory call does not mean a fresh conversation on every message. The released workflow implementation caches workflows using both authorization scope and thread ID. Returning to the same pair can retain its conversation, while another scope or thread receives a separately constructed workflow. The factory itself receives only the thread ID—not the authorization scope.
Keep single-user mode and stored history separate
Use single_user=True only when every caller genuinely belongs to one principal. It is not a workaround for a shared service. A single-principal workflow can still keep one conversation state across several threads, so use a factory when those threads must remain independent. The generated single-user scope lasts only for that endpoint registration; durable continuity across restarts needs an application-owned stable resolver. These distinctions are explicit in the endpoint contract.
Fresh objects are only part of the migration. The AG-UI documentation warns that the live-object guard cannot inspect history loaded into new sessions from shared storage. Do not restore sessions using a thread ID alone. Also review custom executor state and provider-held conversation identifiers. A run completing without a scope conflict therefore does not establish that its restored data belongs to the caller.
For durable workflow continuation, checkpoint_storage provides scope-and-thread ownership checks. Review existing records before relying on them after an upgrade, and verify that the same owner can resume after a restart. New object identities do not automatically establish ownership of old records.
Remove unsupported workflow-as-tool paths
There is a separate compatibility change for WorkflowAgent.as_tool(). Detectable configurations are rejected when the endpoint is registered; factory-created cases can report WORKFLOW_AGENT_TOOL_UNSUPPORTED during a run. This also applies in single-user mode. Microsoft’s change description says custom tool functions that invoke workflows remain outside AG-UI’s isolation support. Expose the workflow directly through the factory-backed endpoint rather than hiding it in another tool.
Check two identities before rollout
A successful startup or first conversation is not enough to check a change that may reject the next scope. Based on Microsoft’s regression-test cases, use the following proposed staging checks with synthetic data:
Run identity A, then identity B, then return to A. Repeat with matching and different thread IDs. Each should retain its intended history without receiving the other’s.
Check separate threads belonging to the same principal. Also confirm that a standing approval in one scope is not reused in another.
In an isolated test fixture, deliberately reuse an executor or session across scopes. Confirm that the rejected run makes no model call and that the interface displays the error rather than appearing to hang.
Inspect the AG-UI event stream, not just the HTTP response. The workflow error path emits RUN_STARTED followed by RUN_ERROR for a scope conflict. The diagnostic code is WORKFLOW_SCOPE_CONFLICT; it is a framework ownership refusal, not a model refusing the user’s request.
Before rollout, verify any checkpoint-resume path with both the correct owner and a different owner. Review the release’s other breaking changes separately. For this migration, the acceptance criteria are concrete: independent callers can run, intended conversations continue, and state restored from storage has an owner the application can verify.