From dc14e305036edd34a0f1d637b09a368b53af0c1f Mon Sep 17 00:00:00 2001 From: Chris Gillum Date: Tue, 21 Jul 2026 14:34:49 -0700 Subject: [PATCH 1/5] docs: add ADR-0032 proposing durable/Azure Functions repo extraction Proposes extracting the Durable Task and Azure Functions hosting integrations into a dedicated repository (microsoft/agent-framework-durable-extension), keeping a backward-compatible shim and the [all] extra so the move is invisible to consumers. Status: proposed, for stakeholder signoff ahead of the code-removal PR. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6181dcf9-857b-43ea-9fd2-fcd6b175ffdd --- ...0032-durable-azure-functions-extraction.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/decisions/0032-durable-azure-functions-extraction.md 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 00000000000..5e4b40158ed --- /dev/null +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -0,0 +1,84 @@ +--- +status: proposed +contact: cgillum +date: 2026-07-21 +deciders: cgillum, vameru, ctoshniwal +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. +- 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**: a shim symbol added to core before the extension republishes would +not resolve. For example, `WorkflowHitlContext` was added after the latest published Azure Functions +beta. The mitigation would be to omit such a 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: add the `WorkflowHitlContext` shim entry once the extension publishes a beta that + exports it; document the direct-import convention in the extension's samples READMEs so samples are + not switched back to the shim. From bc076bf3607bb1d34f24509752238f30cd1d4aba Mon Sep 17 00:00:00 2001 From: Chris Gillum Date: Tue, 21 Jul 2026 14:46:06 -0700 Subject: [PATCH 2/5] Fix GitHub user handles --- docs/decisions/0032-durable-azure-functions-extraction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0032-durable-azure-functions-extraction.md b/docs/decisions/0032-durable-azure-functions-extraction.md index 5e4b40158ed..180aa9a0bcd 100644 --- a/docs/decisions/0032-durable-azure-functions-extraction.md +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -2,7 +2,7 @@ status: proposed contact: cgillum date: 2026-07-21 -deciders: cgillum, vameru, ctoshniwal +deciders: cgillum, vrdmr, chetantoshniwal consulted: informed: --- From 8fad6ce679a1e61ff0c06eb236769c8807d687fe Mon Sep 17 00:00:00 2001 From: Chris Gillum Date: Tue, 21 Jul 2026 14:48:52 -0700 Subject: [PATCH 3/5] docs: generalize publish-lag example in ADR-0032 Replace the WorkflowHitlContext-specific illustration with a generic description of the publish-lag mechanism. The named symbol is currently exported by the extension and present in core's shim, so using it as an 'unpublished' example read as internally inconsistent. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6181dcf9-857b-43ea-9fd2-fcd6b175ffdd --- .../0032-durable-azure-functions-extraction.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/decisions/0032-durable-azure-functions-extraction.md b/docs/decisions/0032-durable-azure-functions-extraction.md index 180aa9a0bcd..80cca598ae7 100644 --- a/docs/decisions/0032-durable-azure-functions-extraction.md +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -70,15 +70,16 @@ Compliance would be validated by: `uv lock --check` passing with both packages r 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**: a shim symbol added to core before the extension republishes would -not resolve. For example, `WorkflowHitlContext` was added after the latest published Azure Functions -beta. The mitigation would be to omit such a symbol from the shim until the extension publishes it, -then add the entry and re-lock. +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: add the `WorkflowHitlContext` shim entry once the extension publishes a beta that - exports it; document the direct-import convention in the extension's samples READMEs so samples are - not switched back to the shim. +- 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. From b316691c188c61f399f736c1e44c1807ff81b822 Mon Sep 17 00:00:00 2001 From: Chris Gillum Date: Tue, 21 Jul 2026 15:02:44 -0700 Subject: [PATCH 4/5] Add note about issue transfers --- docs/decisions/0032-durable-azure-functions-extraction.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/decisions/0032-durable-azure-functions-extraction.md b/docs/decisions/0032-durable-azure-functions-extraction.md index 80cca598ae7..62ae4f38501 100644 --- a/docs/decisions/0032-durable-azure-functions-extraction.md +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -59,6 +59,9 @@ existing imports and the `[all]` extra. 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 From c75d531bf4f4ef72e56624ceb48efa1db496bf68 Mon Sep 17 00:00:00 2001 From: Chris Gillum Date: Fri, 31 Jul 2026 10:16:13 -0700 Subject: [PATCH 5/5] Updates to ADR based on offline discussion --- ...0032-durable-azure-functions-extraction.md | 36 +++++++++++++------ 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/decisions/0032-durable-azure-functions-extraction.md b/docs/decisions/0032-durable-azure-functions-extraction.md index 62ae4f38501..893cfe64bf1 100644 --- a/docs/decisions/0032-durable-azure-functions-extraction.md +++ b/docs/decisions/0032-durable-azure-functions-extraction.md @@ -1,9 +1,9 @@ --- -status: proposed +status: Accepted contact: cgillum date: 2026-07-21 deciders: cgillum, vrdmr, chetantoshniwal -consulted: +consulted: westey-m, eavanvalkenburg, kshyju, larohra, ahmedmuhsin informed: --- @@ -62,16 +62,30 @@ existing imports and the `[all]` extra. - 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. +- 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: `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`. +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 @@ -81,7 +95,9 @@ 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). + [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