microsoft--agent-framework/docs/decisions/0032-durable-azure-functions-extraction.md

status, contact, date, deciders, consulted, informed

status	contact	date	deciders	consulted	informed
Accepted	cgillum	2026-07-21	cgillum, vrdmr, chetantoshniwal	westey-m, eavanvalkenburg, kshyju, larohra, ahmedmuhsin

Extract Durable Task and Azure Functions hosting into a separate repository

Context and Problem Statement

The Durable Task and Azure Functions hosting integrations (agent-framework-durabletask, agent-framework-azurefunctions, plus their samples, docs, and CI) currently live in the microsoft/agent-framework (MAF) monorepo. They carry heavyweight specialized dependencies (Azure Functions runtime, Durable Task) and need integration-test infrastructure (Functions Core Tools, Azurite, a DTS emulator) that the core repo otherwise does not.

This ADR proposes moving them into a dedicated repository (microsoft/agent-framework-durable-extension) and considers how to do so without breaking existing users who import them today.

Decision Drivers

• Independent lifecycle — the hosting integrations should be able to version and release on their own cadence, decoupled from core (extends ADR-0008's goal of keeping heavyweight/optional dependencies out of the main package).
• Dependency & CI isolation — keep core lean and its PR pipeline free of heavyweight hosting dependencies and integration-test prerequisites.
• Ownership — a dedicated repo would give the integrations their own issues, CODEOWNERS, and contribution flow.
• No breaking change — existing from agent_framework.azure import … code and pip install agent-framework[all] should keep working (stable-import-path guarantee, ADR-0008).

Considered Options

1. Keep in the MAF repo (status quo).
2. Move out, drop the core shim — the extension becomes standalone; core stops re-exporting the types and removes them from [all].
3. Move out, keep core's backward-compat shim + [all] (proposed) — the code would live in the new repo; core would still lazily re-export the entry-point types from agent_framework.azure and keep both packages in the [all] extra (resolved from PyPI).

Decision Outcome

Proposed choice: Option 3. Extract the integrations for lifecycle, dependency, and ownership isolation, while preserving the existing import surface so the move is invisible to consumers. Option 1 forgoes the isolation benefits; Option 2 achieves them but would be a breaking change for existing imports and the [all] extra.

Consequences

• Good — would give independent release cadence, a leaner/faster core repo and CI, and clear ownership for the hosting integrations.
• Good — no user-visible break: existing imports and agent-framework[all] would continue to work unchanged.
• Neutral — type definitions would live once in the extension; the core shim would re-export only a curated subset of entry-point types (no metadata duplication). The extension's own samples/docs would import directly from agent_framework_durabletask / agent_framework_azurefunctions; the shim would be compatibility-only.
• Neutral — users may still open GitHub issues against the core repo for problems in the extension, but the extension's own repo would be the primary place for issues and PRs. These issues would need to be triaged and transferred to the extension repo.
• Neutral — .NET public API boundary. The extension should prefer the smallest stable public core API over friend-assembly access where the capability is useful to external hosts or tooling. For workflow routing metadata, the agreed first step is to expose a read-only Workflow.Edges view plus public EdgeData.Connection and FanOutEdgeData, while keeping graph construction internal (#7448, #7459). This reduces internal coupling but adds a public API compatibility commitment. Any remaining internal dependencies would still need to be evaluated individually before retaining InternalsVisibleTo.
• Bad — Python version coordination. Core's shim correctness would track the extension's publish cadence. In the other direction, when an extension package adopts a new core API, maintainers would need to choose per feature between raising its minimum core version (simpler, but forces every extension user to upgrade) and conditional imports with fallback behavior (preserves support for older core versions, but adds implementation and testing complexity).

Validation

Compliance would be validated by:

• Python: uv lock --check passing with both packages resolving from PyPI; the shim entry-point symbols importing at runtime after uv sync --all-extras; pyright staying clean on agent_framework/azure/__init__.pyi; and extension tests running against both the minimum supported and current core versions when conditional compatibility behavior is used.
• .NET: tests from an external assembly confirming that workflow routing metadata is inspectable through the agreed public surface while graph construction remains internal.

A known risk is publish-lag: if a symbol is added to core's shim before the extension has published a release that exports it, that symbol would not resolve at runtime. The mitigation would be to omit any such symbol from the shim until the extension publishes it, then add the entry and re-lock.

More Information

• Related: ADR-0008 (vendor namespaces + stable import paths), ADR-0021 (lazy-loading gateways), issue #7448 and PR #7459 (.NET workflow routing API).
• Follow-ups: during extraction, keep the shim's re-exported symbols in sync with each newly published extension release (adding any symbol only once the extension publishes it); document the direct-import convention in the extension's samples READMEs so samples are not switched back to the shim.