From dc14e305036edd34a0f1d637b09a368b53af0c1f Mon Sep 17 00:00:00 2001 From: Chris Gillum Date: Tue, 21 Jul 2026 14:34:49 -0700 Subject: [PATCH 1/4] 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 0000000000..5e4b40158e --- /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/4] 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 5e4b40158e..180aa9a0bc 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/4] 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 180aa9a0bc..80cca598ae 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/4] 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 80cca598ae..62ae4f3850 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