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..62ae4f3850 --- /dev/null +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -0,0 +1,88 @@ +--- +status: proposed +contact: cgillum +date: 2026-07-21 +deciders: cgillum, vrdmr, chetantoshniwal +consulted: +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. +- Bad — **cross-repo coupling.** Core's shim correctness would track the extension's publish cadence + (a shim symbol newer than the last published beta would not resolve until republished), and the + .NET extension would still consume internal `Microsoft.Agents.AI.Workflows` surface, so the + `InternalsVisibleTo("Microsoft.Agents.AI.DurableTask")` grant would need to remain in core. + +## Validation + +Compliance would be validated by: `uv lock --check` passing with both packages resolving from PyPI; +the shim entry-point symbols importing at runtime after `uv sync --all-extras`; and `pyright` staying +clean on `agent_framework/azure/__init__.pyi`. + +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). +- 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.