Python: [Feature]: Roadmap for AnyIO-backed asyncio and Trio support

[eavanvalkenburg]

Description

Track a staged path for the Python Agent Framework to run supported agents and workflows on both asyncio (the existing default) and Trio through AnyIO. Trio/AnyIO support can start as an explicitly experimental, opt-in AF feature, including an optional dependency on Azure Core Experimental where it is needed. Experimental support is not a production-readiness claim.

Target developer experience: keep await agent.run(...) and existing asyncio.run(...) applications working; applications using a verified combination of features and integrations could instead select Trio at their entry point with anyio.run(main, backend="trio"). No framework-wide backend setting should be necessary. Publish which features and packages are verified on each backend; do not advertise blanket Trio compatibility while integrations remain asyncio-only. Redis is out of scope for this roadmap for now.

Proposed roadmap

1. Define the contract and test boundary. Record the decision and migration trade-offs in an ADR, including experimental status, dependency/performance costs, and the default asyncio behavior. Establish a package/feature compatibility matrix and an isolated dual-backend test target. Start with a fake backend-neutral chat client, then exercise Agent.run(), non-streaming and streaming calls, async/sync/concurrent tools, workflow event delivery, cancellation, and cleanup. Keep the existing pytest-asyncio auto-mode suite intact; run explicitly AnyIO-marked tests with pytest-asyncio in strict mode.
2. Spike the Azure transport now, without waiting for a new Azure SDK release. The generated Foundry and Azure AI Search clients already accept a caller-provided transport=. Try azure.core.experimental.transport.AsyncHttpXTransport via that extension point, first with Search key authentication under asyncio and Trio, then with token credentials, Foundry project operations, Azure AI Inference, streaming, retry, cancellation, and close. Verify the implementation rather than assuming that HTTPX alone makes the pipeline portable: the current experimental transport inherits an asyncio-based retry sleep and has async-response handling to examine. Check credential transport configuration separately. Prefer upstream fixes to the experimental transport where needed; a broken transport is not acceptable just because the AF feature is experimental.
3. Migrate the core paths needed for the verified feature set. Add AnyIO as a direct core dependency when core starts using it; assess its dependency footprint and benchmark relevant lock contention and network-heavy workloads against the existing asyncio implementation before broad adoption. Replace backend-bound primitives and port concurrent tool execution in reviewable steps. Preserve context-variable isolation, observable error shapes, and per-operation cancellation behavior; AnyIO task groups and worker threads are not drop-in replacements for asyncio.gather() and asyncio.to_thread().
4. Handle workflow streaming and durability explicitly. Redesign task/event ownership in the workflow runner without leaving task-group cancel scopes straddling async-generator yields. Preserve event ordering, queue buffering/backpressure, stream-close cleanup, checkpoint replay, and the file checkpoint store's cross-loop write serialization and cancellation guarantees. Cover those invariants under both backends before claiming workflow support.
5. Handle long-lived core resources. Give MCP lifecycle/reconnect work and background agents explicit task ownership across calls and during shutdown, replacing asyncio task/future coupling without introducing orphaned tasks or changing public behavior. Gate these as separate workstreams rather than treating them as mechanical substitutions.
6. Expose verified Azure integrations as experimental. If the transport spike succeeds, provide a documented opt-in path for Foundry and Azure AI Search to pass the experimental async HTTPX transport into all Azure SDK clients they construct, including Search index/knowledge-base paths; respect caller-provided clients and define who owns and closes the transport and credentials. Keep existing asyncio/aiohttp behavior as the default. Scope any azure-core-experimental dependency to the experimental integration rather than making it mandatory across AF; revisit AF's explicit aiohttp requirements only after validating the selected transport path. Be clear that Azure Core Experimental itself is not recommended for production use. Add HttpxTransport support for SDK Azure/azure-sdk-for-python#41382, [azure-ai-projects] Support an HTTPX async transport for AnyIO/Trio applications Azure/azure-sdk-for-python#49154, and [azure-search-documents] Enable HTTPX async transport for AnyIO/Trio callers Azure/azure-sdk-for-python#49155 remain relevant upstream follow-ups, not release prerequisites for an AF experiment.
7. Publish an explicit experimental support matrix. Audit remaining optional providers, hosting, and tools individually. Document or clearly report asyncio-only paths until migrated. Add targeted CI and an opt-in Trio example; retain asyncio as the default and expand the verified experimental surface only when both backends pass the relevant behavior and performance checks. Reassess the status and upstream dependency before considering any broader support claim.

Completion criteria

For each advertised experimental Python feature/provider combination, tests run under asyncio and Trio and cover results, errors, streaming, retries, cancellation, resource cleanup, and, where applicable, checkpoint recovery. The default asyncio path remains compatible. Unsupported combinations are identified explicitly rather than silently falling back to asyncio; experimental dependencies and their production-readiness limitations are documented.

Contributor guidance

Core team ownership for now: please do not pick up this issue or submit implementation PRs for it yet. We are working through some open questions and will update this issue when it is ready for community contributions.

Language/SDK

Python