Python: Durable Support for Workflows by ahmedmuhsin · Pull Request #3630 · microsoft/agent-framework

ahmedmuhsin · 2026-02-02T22:00:54Z

Motivation and Context

Adds workflow orchestration support to Azure Functions, enabling multi-agent workflows with conditional routing, parallel execution, and human-in-the-loop (HITL) patterns using Azure Durable Functions.

Description

Core Package Changes (agent_framework_azurefunctions):

_workflow.py - Orchestration engine that executes MAF Workflows using Durable Functions' generator-based model:
- Sequential and parallel agent/executor execution
- Fan-out/fan-in patterns
- Conditional routing via edge groups (switch/case, single edges)
- HITL via wait_for_external_event with configurable timeouts
_context.py - CapturingRunnerContext for activity execution (captures messages/events without durable storage)
_serialization.py - Serialization utilities for cross-activity message passing (dataclasses, Pydantic models, ChatMessage)
_app.py - Extended AgentFunctionApp with:
- New workflow parameter accepting a Workflow instance
- Auto-registers agents from workflow executors
- HTTP endpoints: POST /workflow/run, GET /workflow/status/{id}, POST /workflow/respond/{id}/{requestId}

New Samples (09-12):

Sample	Pattern
`09_workflow_shared_state`	Shared state + conditional routing (spam detection → email response)
`10_workflow_no_shared_state`	Stateless workflow with switch/case routing
`11_workflow_parallel`	Fan-out/fan-in for parallel agent execution
`12_workflow_hitl`	Human-in-the-loop with approval/rejection flow

Tests:

Unit tests for _workflow.py, _serialization.py, _context.py, and _app.py workflow features (152 total)
Integration tests for all 4 new samples (14 tests)

API Fix:

Updated samples to use chat_client.as_agent() with default_options={"response_format": ...} instead of non-existent create_agent()

Contribution Checklist

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible
Is this a breaking change? No

markwallace-microsoft · 2026-02-03T16:45:36Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azurefunctions/agent_framework_azurefunctions
_app.py	494	187	62%	215–216, 221–222, 257–258, 261, 263–265, 271, 273, 275–278, 280–281, 283–285, 288, 291, 293, 295–296, 299–301, 303, 305, 313, 321–323, 326, 329, 334–335, 338–341, 344, 347–349, 360–363, 369, 371, 379–380, 383, 388–389, 391–392, 394, 397, 400, 402, 404, 406–408, 412–415, 421, 423–424, 426, 437–439, 443–444, 446–447, 453, 464–469, 477, 479, 485–487, 493–494, 496–497, 503–506, 514, 520, 539, 638–639, 747, 755–756, 776–778, 784–786, 792–794, 827–828, 888–889, 938–939, 944, 1026, 1029, 1038–1040, 1042–1044, 1046, 1048, 1059, 1061–1064, 1066, 1068–1069, 1071, 1078–1079, 1081–1082, 1084–1085, 1087, 1091, 1101–1103, 1105–1106, 1108–1110, 1117, 1119–1120, 1122, 1143, 1148, 1160, 1235, 1245, 1252–1254, 1299, 1313, 1324–1326, 1328–1331, 1356, 1363, 1365, 1368
_context.py	65	6	90%	103, 107, 155–156, 164, 171
_serialization.py	186	67	63%	106–107, 112–113, 132–133, 143, 145–147, 166, 174, 176–177, 181–182, 189, 191–193, 214, 220, 222, 225, 227–230, 233–237, 240–241, 243–246, 249–255, 257, 314, 321–326, 328–331, 333, 336, 345–346, 352–353, 359, 375–376
_workflow.py	348	223	35%	133, 138, 140, 147, 196–198, 268–270, 272–274, 296, 302, 304–305, 328–329, 331–335, 337, 344, 369, 372–381, 384–385, 387, 414–415, 418–419, 422–428, 431–432, 435–440, 443–446, 449, 451–455, 470–472, 474, 477–478, 481–486, 488–489, 491–492, 494–495, 498, 516–520, 527, 551, 559–561, 564–565, 567, 615, 618–619, 622, 627, 629–631, 634, 639–643, 646–649, 651–652, 655–659, 661–662, 665–666, 669–670, 673, 675, 678–679, 682, 698–699, 702–703, 705, 707, 709, 712–713, 721–723, 725–728, 731, 734, 741–742, 747, 749, 752, 779–781, 784, 787–789, 791–793, 796–799, 809–811, 813–816, 826, 828, 842–843, 872–873, 888, 918, 921–923, 926, 929, 932, 934–935, 941, 945, 954, 958, 971, 977–978, 981–983, 986–989, 991–992, 994–995, 997–1000, 1002–1003, 1006–1007
packages/core/agent_framework/_workflows
_agent_executor.py	174	24	86%	95, 117, 123, 156, 172–173, 224–225, 227–228, 260–262, 270–272, 282–284, 286, 290, 294, 298–299
TOTAL	16990	2317	86%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4015	235 💤	0 ❌	0 🔥	1m 7s ⏱️

Copilot

Pull request overview

This PR adds comprehensive workflow orchestration support to Azure Functions, enabling multi-agent workflows with conditional routing, parallel execution, and human-in-the-loop (HITL) patterns using Azure Durable Functions.

Changes:

New workflow orchestration engine in _workflow.py that executes MAF Workflows using Durable Functions' generator-based model
Serialization utilities in _serialization.py for cross-activity message passing
Capturing runner context in _context.py for activity execution
Extended AgentFunctionApp with workflow parameter and auto-registration of agents
Four new samples (09-12) demonstrating shared state, stateless, parallel, and HITL workflow patterns
Comprehensive unit and integration tests (152 unit tests, 14 integration tests)
Bug fix: Updated chat_client.as_agent() usage with default_options parameter

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`_workflow.py`	Main orchestration engine with HITL support, parallel execution, and edge group routing
`_serialization.py`	Serialization/deserialization for dataclasses, Pydantic models, and MAF types
`_context.py`	CapturingRunnerContext for activity execution without durable storage
`_app.py`	Extended AgentFunctionApp with workflow support and HTTP endpoints
`_agent_executor.py`	Added agent property to expose underlying agent
Samples 09-12	Four new workflow samples with requirements, configs, and README files
Test files	Unit tests for workflow utilities and integration tests for all samples
`pyproject.toml`	Increased test timeout from 120s to 300s for workflow tests
Sample 07	Fixed type annotations for Azure Functions worker compatibility

Comments suppressed due to low confidence (1)

python/packages/azurefunctions/agent_framework_azurefunctions/_app.py:1056

This import of module asyncio is redundant, as it was previously imported on line 9.

        import asyncio

python/samples/getting_started/azure_functions/10_workflow_no_shared_state/function_app.py

python/packages/azurefunctions/tests/integration_tests/testutils.py

python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/demo.http

Copilot · 2026-02-03T17:00:48Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+                            import json
+


The json module is imported inside a try-except block on line 722. However, json is already imported at the module level (line 22). This redundant import should be removed, and the module-level import should be used instead.

Suggested change

import json

+1 to this comment, unresolving it here since the comment is still relevant

python/packages/azurefunctions/agent_framework_azurefunctions/_serialization.py

python/samples/getting_started/azure_functions/10_workflow_no_shared_state/function_app.py

…ests

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

larohra · 2026-02-04T21:58:57Z

python/packages/azurefunctions/agent_framework_azurefunctions/_app.py

+            logger.debug("[AgentFunctionApp] Extracting agents from workflow")
+            for executor in workflow.executors.values():
+                if isinstance(executor, AgentExecutor):
+                    agents.append(executor.agent)


If the same agent is registered in both "agents" and "workflow" will that agent be re-registered?

larohra · 2026-02-04T21:59:58Z

python/packages/azurefunctions/agent_framework_azurefunctions/_app.py

+            Note: We use str type annotations instead of dict to work around
+            Azure Functions worker type validation issues with dict[str, Any].
+            """
+            import json as json_module


NIT: Move all imports to top of the file

larohra · 2026-02-04T22:13:30Z

python/packages/azurefunctions/agent_framework_azurefunctions/_app.py

+            data = json_module.loads(inputData)
+            message_data = data["message"]
+            shared_state_snapshot = data.get("shared_state_snapshot", {})
+            source_executor_ids = data.get("source_executor_ids", ["__orchestrator__"])


Out of curiosity, why defaulting to __orchestrator__? Is that always going to be there?

larohra · 2026-02-04T22:15:50Z

python/packages/azurefunctions/agent_framework_azurefunctions/_app.py

+                runner_context = CapturingRunnerContext()
+                shared_state = SharedState()
+
+                # Deserialize shared state values to reconstruct dataclasses/Pydantic models


We already have some logic for this in

agent-framework/python/packages/durabletask/agent_framework_durabletask/_models.py

Line 54 in 907654a

def _deserialize_response_format(response_format: Any) -> type[BaseModel] | None:

, can we reuse same classes (feel free to expand on a single class and use it everywhere)

larohra · 2026-02-04T22:19:30Z

python/packages/azurefunctions/agent_framework_azurefunctions/_app.py

+            try:
+                req_body = req.get_json()
+            except ValueError:
+                return func.HttpResponse(


Can we make this a generic function to return a 400 back (I see it being used in multiple places here)

larohra · 2026-02-04T22:22:43Z

python/packages/azurefunctions/agent_framework_azurefunctions/_context.py

+    It captures all messages and events produced during execution without requiring durable
+    entity storage, allowing the results to be returned to the orchestrator.
+
+    Unlike the full InProcRunnerContext, this implementation:


NIT: Is this remnants of a previous implementation? If so, would be good to cleanup

larohra · 2026-02-04T22:23:42Z

python/packages/azurefunctions/agent_framework_azurefunctions/_context.py

+
+    async def drain_messages(self) -> dict[str, list[Message]]:
+        """Drain and return all captured messages."""
+        from copy import copy


NIT: Move to top (for all files)

larohra · 2026-02-04T22:29:30Z

python/packages/azurefunctions/agent_framework_azurefunctions/_serialization.py

@@ -0,0 +1,378 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Serialization and deserialization utilities for workflow execution.


Not sure if you already looked, but agent-framework already has a very comprehensive class for thsi - https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_serialization.py

It would be ideal if we can reuse code from here and not introduce new overrides for similar experiences

larohra · 2026-02-04T22:32:07Z

python/packages/azurefunctions/agent_framework_azurefunctions/_serialization.py

+# ============================================================================
+
+
+def reconstruct_agent_executor_request(data: dict[str, Any]) -> AgentExecutorRequest:


We have some similar logic (to deserialize-from and serialize-to MAF constructs) in this file -

agent-framework/python/packages/durabletask/agent_framework_durabletask/_durable_agent_state.py

Line 472 in 907654a

return DurableAgentStateResponse.to_run_response(entry)

Given that this is doing something similar, it would be a good idea to combine all of them in a single place

alliscode · 2026-02-04T22:36:44Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+                    )
+                else:
+                    # Timeout occurred
+                    logger.warning("HITL request %s timed out after %s hours", request_id, hitl_timeout_hours)


Does the approval_task need to be canceled in this case?

larohra · 2026-02-04T22:39:51Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+# ============================================================================
+
+
+def _evaluate_edge_condition_sync(edge: Any, message: Any) -> bool:


can we have stricter type-checks so that we dont need to add code like getattr(edge, "_condition", None) everywhere

larohra · 2026-02-04T22:40:59Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+    if structured_response:
+        final_text = json.dumps(structured_response)
+
+    assistant_message = ChatMessage(role="assistant", text=final_text)


NIT:

Suggested change

assistant_message = ChatMessage(role="assistant", text=final_text)

assistant_message = ChatMessage(role=Role.ASSISTANT, text=final_text)

larohra · 2026-02-04T23:18:48Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+        List of workflow outputs collected from executor activities
+    """
+    pending_messages: dict[str, list[tuple[Any, str]]] = {
+        workflow.start_executor_id: [(initial_message, "__workflow_start__")]


I would recommend making all these markers ("workflow_start", "hitl_response", etc) as constants and using them everywhere to avoid chances of confusion or typos

larohra · 2026-02-04T23:22:01Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+                            import json
+


+1 to this comment, unresolving it here since the comment is still relevant

larohra · 2026-02-04T23:27:13Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+    """Extract text content from serialized message dictionaries."""
+    message_content = ""
+
+    if message.get("messages"):


This seems very fragile and easy to break. Can we use existing to_dict and from_dict methods provided by MAF here instead? If not, consider having a similar appraoch to https://github.com/microsoft/agent-framework/blob/907654a489a4f41bd4b44618ce5daa994383cb3c/python/packages/durabletask/agent_framework_durabletask/_durable_agent_state.py to use inheritance to make this serialization/deserialization more cleaner and less specific to how it is today.

larohra · 2026-02-04T23:27:47Z

python/packages/azurefunctions/agent_framework_azurefunctions/_workflow.py

+    if response_type_str:
+        try:
+            module_name, class_name = response_type_str.rsplit(":", 1)
+            import importlib


NIT: move to top

ahmedmuhsin force-pushed the durable-workflows-v2 branch from 3663ba2 to c54d3bb Compare February 2, 2026 22:01

markwallace-microsoft added documentation Improvements or additions to documentation python labels Feb 3, 2026

github-actions bot changed the title ~~Durable Support for Workflows in Python~~ Python: Durable Support for Workflows in Python Feb 3, 2026

ahmedmuhsin changed the title ~~Python: Durable Support for Workflows in Python~~ Python: Durable Support for Workflows Feb 3, 2026

ahmedmuhsin force-pushed the durable-workflows-v2 branch from d8db985 to b0e7c16 Compare February 3, 2026 16:51

ahmedmuhsin marked this pull request as ready for review February 3, 2026 16:55

ahmedmuhsin requested a review from a team as a code owner February 3, 2026 16:55

Copilot AI review requested due to automatic review settings February 3, 2026 16:55

Copilot started reviewing on behalf of ahmedmuhsin February 3, 2026 16:55 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

ahmedmuhsin force-pushed the durable-workflows-v2 branch from b0e7c16 to 668d98a Compare February 4, 2026 18:43

ahmedmuhsin and others added 9 commits February 4, 2026 13:29

Add workflow support for Azure Functions

5a16bf5

fix compatability with latest framework changes and add integration t…

48d0eeb

…ests

refactor code

6041327

remove white space

1c6f3a3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

align help text with actual port used

e27c0d9

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

add comment for why #noqa: SIM115 is needed

77bad5f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

replace instance id with a place holder

f94bd99

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

remove unused import

3a90be8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

remove redundant typing import and fix SIM115

3c3c325

ahmedmuhsin force-pushed the durable-workflows-v2 branch from 5edfd45 to 3c3c325 Compare February 4, 2026 19:30

ahmedmuhsin added 2 commits February 4, 2026 14:00

fix latest breaking changes

d1c0dfa

fix mypy issues

8a34c28

larohra reviewed Feb 4, 2026

View reviewed changes

alliscode reviewed Feb 4, 2026

View reviewed changes

larohra reviewed Feb 4, 2026

View reviewed changes

		@@ -0,0 +1,378 @@
		# Copyright (c) Microsoft. All rights reserved.

		"""Serialization and deserialization utilities for workflow execution.

		# ============================================================================


		def reconstruct_agent_executor_request(data: dict[str, Any]) -> AgentExecutorRequest:

		# ============================================================================


		def _evaluate_edge_condition_sync(edge: Any, message: Any) -> bool:

	assistant_message = ChatMessage(role="assistant", text=final_text)
	assistant_message = ChatMessage(role=Role.ASSISTANT, text=final_text)

Conversation

ahmedmuhsin commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Description

Contribution Checklist

Uh oh!

markwallace-microsoft commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ahmedmuhsin commented Feb 2, 2026 •

edited

Loading

markwallace-microsoft commented Feb 3, 2026 •

edited

Loading