Python: HITL respond-URL addressing from inside workflows

[ahmedmuhsin]

Motivation & Context

The durable function HITL flow pauses a workflow with request_info and waits for a human to POST a response to the /respond endpoint. The gap was that nothing inside the workflow could build that respond URL. An executor only receives its message payload, not the orchestration instanceId, and the requestId does not exist until request_info runs. So to email someone an approval link you had to pull both ids from the HTTP run response or poll the status endpoint from outside the app.

This came out of a real POC where someone wanted Agent B to email a reviewer when it finished, then resume to Agent C once approved, but had no way to address the running workflow from within it. This change lets a workflow build its own respond URL and notify a human from inside the graph with no caller plumbing of instanceId or requestId, and it works for nested sub workflows too.

Description & Review Guide

• What are the major changes?

  • The orchestrator now surfaces orchestration metadata (the addressable root instanceId, the workflow name, and for nested workflows the request path prefix) onto each executor through the durable runner context. There is no new core API.
  • A new WorkflowHitlContext helper in agent-framework-azurefunctions builds the canonical respond and status URLs from that metadata. It returns None in process so the same executor degrades gracefully when it is not on the durable host.
  • WorkflowHitlContext.pending_request_id(ctx) reads the id request_info just generated back off the context, so the user never mints an id by hand. It works on any host through the existing core runner context protocol.
  • For nested sub workflows the address context propagates down call_sub_orchestrator via a new SUBWORKFLOW_ADDRESS_KEY marker, so an executor at any depth builds a URL that targets the top level instance with a qualified request id. That marker is stripped from untrusted input alongside the existing input marker, so a top level caller cannot forge it.
  • Samples 12 and 13 show the two step pattern. The review executor reads the request id back and sends it to a downstream notify executor that builds the URL, so a retried activity never emails a dead link because only the committed attempt reaches the notifier.

• What is the impact of these changes?

  • Additive. No core change, nothing public removed, and top level behavior is unchanged when the helper is not used.
  • New unit tests cover the metadata round trip, the id read back, the nested ordinal and prefix agreement with the read side, marker stripping, and URL building. Integration tests assert that the URL the helper builds equals the server respondUrl and that posting to it resumes the run, for both the flat (12) and nested (13) samples.

• What do you want reviewers to focus on?

  • The per executor ordinal used to build the nested prefix at dispatch has to match the enumerate index the status and respond endpoints use when they resolve a nested request. That agreement is the one spot where a mistake would send an emailed URL to the wrong child or a 404.

Related Issue

No separate issue. This builds on the Durable Task multi-workflow and sub-workflow hosting work that landed on main in #6696, and now targets main directly.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azurefunctions/agent_framework_azurefunctions
_app.py	584	151	74%	82–83, 86–89, 317, 375, 417–418, 422–423, 425–427, 435–437, 439, 442, 452–453, 455–457, 459, 463, 466, 468, 470, 473, 492–494, 497–500, 506, 508, 510–511, 513, 533–535, 537, 543–544, 551, 553, 568–573, 586, 588, 603–604, 606–607, 612–614, 616–619, 623, 628–631, 635, 641, 694, 731, 737, 740, 743, 888–889, 997, 1005–1006, 1026–1028, 1034–1036, 1042–1044, 1077–1078, 1138–1139, 1188–1189, 1194, 1276, 1279, 1288–1290, 1292–1294, 1296, 1298, 1309–1312, 1314, 1316–1317, 1319, 1326–1327, 1329–1330, 1332–1333, 1335, 1339, 1349–1351, 1353–1354, 1356–1358, 1365, 1367–1368, 1370, 1391, 1396, 1408, 1480, 1570, 1585–1588, 1613
_hitl_context.py	61	1	98%	192
_routes.py	46	3	93%	57, 60, 63
packages/durabletask/agent_framework_durabletask/_workflows
activity.py	74	17	77%	62, 85–91, 110, 149–153, 159, 172–173
orchestrator.py	457	236	48%	209–211, 263–265, 283, 300–302, 341–342, 344–351, 353, 360, 375, 377–386, 388–389, 391, 488–489, 491–492, 494–497, 500–502, 504–505, 507–512, 514–517, 519, 521–525, 534–536, 538, 540–541, 543–548, 550–551, 553–554, 556–557, 559, 572–576, 583, 596, 603–605, 607–608, 610, 628–629, 650, 745, 749, 787, 793, 818, 822, 828–835, 837–838, 897, 929–930, 933–934, 944–945, 947–950, 959, 1021, 1024–1025, 1032, 1039, 1043, 1056, 1058–1061, 1063, 1066–1074, 1076, 1083–1085, 1089–1092, 1098–1100, 1102, 1106, 1108–1110, 1113, 1120–1124, 1127–1129, 1135–1139, 1141–1148, 1152–1153, 1155–1157, 1160–1164, 1166–1168, 1171–1172, 1175–1176, 1179, 1181, 1186–1187, 1190–1191, 1193, 1207, 1213–1214, 1216–1217, 1224–1229, 1235–1237, 1242, 1244–1245, 1250, 1252, 1254, 1258–1259, 1263–1265
runner_context.py	81	23	71%	59–60, 68, 73, 85, 88, 93, 96, 99, 110, 113, 116, 121, 124–127, 130, 133, 162, 167–168, 171
serialization.py	101	4	96%	243, 358–360
TOTAL	44595	5215	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9046	33 💤	0 ❌	0 🔥	2m 33s ⏱️

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 91% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by ahmedmuhsin's agents

[Copilot]

Pull request overview

This PR enables Python Durable Functions workflows (including nested sub-workflows) to construct canonical HITL /respond (and /status) URLs from inside executors, by surfacing orchestration addressing metadata onto the runner context and adding a small helper (WorkflowHitlContext) in agent-framework-azurefunctions.

Changes:

• Surface durable-host orchestration metadata (root instance/workflow + nested request-path prefix) to executors via durabletask runner context host_metadata.
• Add WorkflowHitlContext helper to build respond/status URLs and to read back the latest request_info-generated request id from the runner context.
• Update samples + add unit/integration tests, including nested sub-workflow address propagation and marker-stripping security coverage.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/samples/04-hosting/azure_functions/13_subworkflow_hitl/README.md	Documents in-subworkflow notification pattern using WorkflowHitlContext.
python/samples/04-hosting/azure_functions/13_subworkflow_hitl/function_app.py	Adds inner-workflow notifier executor and wires it into the nested HITL sample.
python/samples/04-hosting/azure_functions/12_workflow_hitl/README.md	Documents in-workflow reviewer notification + respond URL building.
python/samples/04-hosting/azure_functions/12_workflow_hitl/function_app.py	Adds notifier executor and routes approval result explicitly to publish step.
python/packages/durabletask/tests/test_workflow_serialization.py	Adds tests ensuring subworkflow address marker is stripped from untrusted input.
python/packages/durabletask/tests/test_workflow_activity.py	Adds tests asserting host_context is surfaced as runner_context.host_metadata.
python/packages/durabletask/tests/test_subworkflow_orchestration.py	Adds tests for address resolution + per-superstep subworkflow ordinal/prefix agreement.
python/packages/durabletask/agent_framework_durabletask/_workflows/serialization.py	Introduces SUBWORKFLOW_ADDRESS_KEY and strips it alongside SUBWORKFLOW_INPUT_KEY.
python/packages/durabletask/agent_framework_durabletask/_workflows/runner_context.py	Adds host_metadata plumbing to the durable activity runner context.
python/packages/durabletask/agent_framework_durabletask/_workflows/orchestrator.py	Threads address context into activity/subworkflow dispatch and propagates nested prefix.
python/packages/durabletask/agent_framework_durabletask/_workflows/activity.py	Reads host_context and sets it on the runner context for executor access.
python/packages/core/agent_framework/azure/init.pyi	Re-exports WorkflowHitlContext from the agent_framework.azure facade typings.
python/packages/core/agent_framework/azure/init.py	Adds lazy export mapping for WorkflowHitlContext.
python/packages/azurefunctions/tests/test_hitl_context.py	New unit tests for WorkflowHitlContext URL building/base URL resolution/pending id.
python/packages/azurefunctions/tests/integration_tests/test_13_workflow_subworkflow_hitl.py	Integration test asserts helper-built URL matches server qualified respondUrl (nested).
python/packages/azurefunctions/tests/integration_tests/test_12_workflow_hitl.py	Integration test asserts helper-built URL matches server respondUrl (flat).
python/packages/azurefunctions/agent_framework_azurefunctions/_hitl_context.py	New helper implementation for HITL URL construction + pending request id read-back.
python/packages/azurefunctions/agent_framework_azurefunctions/init.py	Exports WorkflowHitlContext from the package public surface.

[larohra]

A few notes on the HITL addressing mechanism -- 2 likely must-fix URL-correctness bugs (hardcoded route prefix, loopback scheme), 2 cheap de-risking refactors (respond/status URL dedup, the cross-package host_context key contract), and 1 optional hardening note on the sub-workflow ordinal. Details inline. Nothing here blocks the durable use case; the first two just affect whether generated links resolve in non-default setups.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 89% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by ahmedmuhsin's agents

[kshyju]

Thorough review of all 18 files. The architecture is clean — address context propagation through the orchestration tree, security-conscious marker stripping, and the retry-safe two-step notify pattern are all well done. The critical per-executor ordinal / enumerate agreement is correct and well-tested. LGTM.

Minor (non-blocking): In _hitl_context.py ~L192, the comment says "An override may already include a scheme" but at that point base_url_override is already falsy (returned early). The comment should reference WEBSITE_HOSTNAME instead, e.g.: "WEBSITE_HOSTNAME may include a scheme (unusual but possible); otherwise infer one (http for local loopback, https otherwise)."

[kshyju]

Thorough review of all 18 files. The architecture is clean — address context propagation through the orchestration tree, security-conscious marker stripping, and the retry-safe two-step notify pattern are all well done. The critical per-executor ordinal / enumerate agreement is correct and well-tested. LGTM.

Minor (non-blocking): In _hitl_context.py ~L192, the comment says "An override may already include a scheme" but at that point base_url_override is already falsy (returned early). The comment should reference WEBSITE_HOSTNAME instead, e.g.: "WEBSITE_HOSTNAME may include a scheme (unusual but possible); otherwise infer one (http for local loopback, https otherwise)."

From GHCP review ^

[ahmedmuhsin]

Thanks for the thorough review. I fixed the base_url comment in 348da78 to reference WEBSITE_HOSTNAME instead of an override, since the override returns early above.