diff --git a/docs/decisions/0032-durable-azure-functions-extraction.md b/docs/decisions/0032-durable-azure-functions-extraction.md new file mode 100644 index 0000000000..893cfe64bf --- /dev/null +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -0,0 +1,104 @@ +--- +status: Accepted +contact: cgillum +date: 2026-07-21 +deciders: cgillum, vrdmr, chetantoshniwal +consulted: westey-m, eavanvalkenburg, kshyju, larohra, ahmedmuhsin +informed: +--- + +# 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`](https://github.com/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](0008-python-subpackages.md)'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](https://github.com/microsoft/agent-framework/issues/7448), + [#7459](https://github.com/microsoft/agent-framework/pull/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](0008-python-subpackages.md) (vendor namespaces + stable import paths), + [ADR-0021](0021-provider-leading-clients.md) (lazy-loading gateways), + [issue #7448](https://github.com/microsoft/agent-framework/issues/7448) and + [PR #7459](https://github.com/microsoft/agent-framework/pull/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.