Microsoft has released Agent Framework 1.25.0 for Python. It limits the size of catalogs, or collections of tool listings, read through MCP, the protocol for communicating with external tool servers. It also prevents a user's workflow executors and sessions from being reused in another authorization scope. Developers serving multiple users through one agent service should review both discovery settings and workflow creation.
1. MCP catalog discovery gets limits
According to the release notes, agent-framework-core and agent-framework-declarative limit MCP tool and prompt catalog discovery and framework-managed request duration as follows.
Table: Default MCP discovery and request settings
Conditions: Defaults for MCP tool and prompt discovery and framework-owned requests
Units: pages, items, seconds
| Setting | Default | Scope and conditions |
|---|---|---|
| Discovery page cap | 100 pages | Applied per tool or prompt catalog |
| Discovery item cap | 1,000 items | Applied per tool or prompt catalog, independently of the page cap |
| Request timeout | 30 seconds | Applied to framework-managed requests |
If a catalog refresh fails, the entire previous snapshot, a copy of the state before the refresh, is preserved.
Developers with large catalogs can raise the page or item caps. Setting the relevant option to None removes that cap for trusted MCP servers. When more listings are needed, configure limits based on server trust and the required discovery scope.
Request wait times are configured separately. Passing request_timeout=None to an MCP tool restores unlimited request duration. Custom clients retain their own transport and timeout policies.
Discovery approval policies now support callables. They can define permissions by tool name and read-only status and honor explicit caller overrides, or reassigned settings. Policy updates for existing tools are also supported.
2. Workflow executors and sessions are bound to authorization scopes
Executors and sessions that run workflows are bound to one authorization scope, a boundary defining permitted access. Reusing them for a request under another scope is rejected before a model call. AG-UI endpoints, which receive requests, also reject execution of workflow agents wrapped as tools.
The remedy is to pass a factory, a function that creates a fresh workflow, executor, and session for each call. The release notes show this form:
AgentFrameworkWorkflow(workflow_factory=...)Cross-scope reuse is reported as WORKFLOW_SCOPE_CONFLICT. Unsupported workflow agent tools are reported as WORKFLOW_AGENT_TOOL_UNSUPPORTED. Developers receiving these errors must serve the workflow directly through a factory.
3. A new MCP protocol session opens for every call
The security fix in agent-framework-declarative 1.5.0, listed in the same release notes, prevents MCP state sharing across calls. Previously, initialized protocol sessions, units of conversation with a server, were cached and reused in later calls. Now each handler call, including tool execution and listing requests, creates and closes a new session.
Server session continuity across calls is therefore lost. Previous session state does not carry over after resuming from approval waits or checkpoints, which record where work paused. Developers needing continuity must explicitly use remote state handles, identifiers for state retained on the server, or provide an explicitly scoped MCPToolHandler. Checkpoints and approval validation themselves remain unchanged.
Handler creation code also needs adjustment. Replace async with construction with ordinary construction and remove aclose() calls.
The former cache size argument, cache_max_size, is still accepted but ignored without validation. A value other than None triggers a deprecation warning; omitting the argument removes the warning.
4. Discovery limits and scope isolation address different design concerns
100 pages caps the number of pages discovered, while 1,000 items caps the number of catalog entries read. Raising only the page cap leaves the item cap in place, so services handling large catalogs must check both settings. The request timeout separately bounds request wait times.
Execution scope checks instead limit who can reuse executors and sessions, not discovery volume. Set discovery limits based on server trust and catalog size. For scope isolation, structure object creation so that the same executors and sessions are not passed to other users' requests.
5. Start by checking the runtime and shared objects
Starting with this release, installation requires Python 3.11 or later. Environments running Python 3.10 must upgrade their runtime first.
The default MCP handler exposing discovery limits and AG-UI using workflow ownership checks require Core 1.25, so check the related dependencies as well.
Migration for multi-user services can start by locating shared objects. Identifying where executors and sessions are retained reveals which parts need factories that create fresh objects per call.
Shared builders, tools that construct objects from configuration, reuse executors even when caching is disabled, so they cannot replace per-call creation. Use single-user configuration only when all callers are the same principal.
Scope checks target the identities of live executors and sessions. They do not cover state loaded from shared storage or custom tool functions that invoke workflows directly.
Adjusting discovery limits and eliminating object reuse across authorization boundaries are separate migration tasks.