Python: extend HITL support for all orchestration patterns

[moonbox3]

Motivation and Context

The high-level orchestration builders lacked a consistent human-in-the-loop (HITL) API. Developers needed different approaches for each pattern to intercept agent responses and request human input mid-workflow.

Added HumanInputHookMixin support to SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, and HandoffBuilder. All patterns now expose a unified .with_human_input_hook() method that accepts a callback invoked after each agent response, enabling workflows to pause and request human input when needed.

MagenticBuilder retains its specialized HITL mechanisms (with_plan_review(), with_human_input_on_stall()) due to internal message type constraints.

Description

• HITL APIs for orchestration patterns.
• Add samples to also show how to handle tool approvals with the orchestration patterns.

Important

I will update the Learn Site docs once this PR goes in.

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? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
observability.py	609	101	83%	238, 264–266, 268, 270–274, 282–283, 288–289, 294–299, 322–324, 326–327, 333, 417, 427, 449, 455, 474–476, 484–486, 508–510, 520–522, 655, 657, 744–748, 751–755, 764–767, 777–780, 782, 1049, 1127–1129, 1199–1201, 1359, 1367, 1371, 1375, 1381, 1383, 1385, 1393, 1403, 1431–1432, 1445–1448, 1467–1469, 1471–1474, 1476–1477, 1481, 1484, 1542, 1558, 1562, 1696, 1698
packages/core/agent_framework/_workflows
_base_group_chat_orchestrator.py	78	7	91%	18, 87, 178, 188, 195, 251, 278
_concurrent.py	146	31	78%	51, 60–61, 69–70, 89–90, 95, 100, 125, 130, 135–136, 142, 164, 174, 181, 257–261, 263, 291, 295, 319–320, 347, 359–361
_group_chat.py	604	107	82%	113, 145, 156, 380–390, 409, 436–437, 442, 504, 518, 525, 529–531, 534, 586–587, 589–591, 615–616, 672–681, 690–691, 694, 739, 753–755, 759, 761–765, 770, 772, 778, 782–784, 789–794, 800, 815, 838, 847, 870, 879, 884–885, 1047, 1066, 1070, 1124, 1174, 1192, 1200, 1225–1227, 1466, 1472, 1631, 1645, 1712–1713, 1715–1716, 1718, 1720, 1722–1723, 1959, 2031–2034, 2044, 2055, 2064–2066
_handoff.py	549	140	74%	60, 73–75, 82–83, 85, 87, 161, 169–174, 177–178, 192, 201, 220–223, 232–234, 245, 248, 258–269, 271, 277, 283, 318, 334, 336, 339, 341, 389, 482, 491–496, 498–499, 510, 527, 545, 560, 572, 600, 612–614, 620, 644–646, 649–652, 654–656, 901, 907, 911, 917, 921, 933, 983, 986, 1074, 1079, 1089, 1095–1098, 1106–1107, 1111–1113, 1115–1125, 1127–1128, 1130, 1132, 1147–1148, 1151–1152, 1155, 1175–1181, 1183, 1189, 1223–1224, 1277–1278, 1363, 1570, 1578, 1674, 1686, 1697, 1701, 1706–1707
_magentic.py	995	342	65%	47, 52, 74–83, 88, 92–103, 276, 281, 298, 300, 315, 323–332, 482, 486, 500, 506, 521, 601, 614, 631, 640–641, 643–645, 647, 658, 796–800, 805, 844, 891, 927–929, 931, 939–942, 946–949, 1083–1084, 1101, 1103–1104, 1112, 1148, 1157–1159, 1179, 1232, 1252, 1255, 1287, 1290, 1294–1295, 1308, 1318–1322, 1328, 1354–1358, 1366–1370, 1374–1375, 1378–1383, 1389–1391, 1394–1395, 1399–1400, 1411–1412, 1414–1415, 1420–1422, 1426–1427, 1429–1430, 1434–1435, 1437–1441, 1445–1447, 1451–1452, 1460, 1468, 1483, 1495, 1507–1510, 1533–1540, 1542–1545, 1555–1556, 1565–1566, 1571–1573, 1604, 1630, 1644, 1660, 1676, 1748, 1755, 1758, 1760–1761, 1764–1765, 1769, 1772, 1793, 1829, 1834–1835, 1837, 1841–1843, 1874–1876, 1882–1884, 1887–1889, 1891, 1893, 1897, 1901, 1904, 1909, 1912–1917, 1920, 1922, 1927, 1931, 1934–1935, 1937–1939, 1942, 1946, 1951, 1954, 1959–1960, 2018–2019, 2024, 2028, 2030–2034, 2037–2039, 2042, 2045, 2052–2054, 2068, 2073–2074, 2301–2302, 2481–2482, 2484, 2498, 2503, 2506, 2562, 2573, 2584–2586, 2599–2600, 2605, 2616–2618, 2629–2631, 2643–2650, 2652–2653, 2661, 2669–2670, 2672–2674, 2676–2679, 2683–2691, 2695–2696, 2699–2703, 2705–2706, 2708–2711, 2713–2716, 2718–2720, 2722–2723, 2725–2727, 2742–2745, 2756–2759, 2771–2774, 2778
_orchestration_request_info.py	113	20	82%	60, 156, 213–215, 241–243, 245, 251, 279–283, 290, 294–295, 328–329
_orchestrator_helpers.py	53	5	90%	96–97, 127, 129, 205
_sequential.py	89	13	85%	72, 80, 90, 155, 161, 207, 209–211, 226, 248, 252–253
TOTAL	16504	2596	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2346	130 💤	0 ❌	0 🔥	1m 1s ⏱️

[Copilot]

Pull request overview

This PR extends Human-In-The-Loop (HITL) support to all major orchestration patterns by introducing a unified .with_human_input_hook() API. The implementation adds a new HumanInputHookMixin that enables SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, and HandoffBuilder to pause workflows and request arbitrary human feedback mid-execution, while MagenticBuilder retains its specialized HITL mechanisms due to internal architectural constraints.

Key Changes:

• Introduced HumanInputRequest data type and HumanInputHookMixin for builder-agnostic human input hooks
• Added _HumanInputInterceptor executor that intercepts agent responses and invokes configurable hooks
• Extended all high-level builders (except MagenticBuilder) with the mixin for consistent HITL API

Reviewed changes

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

Show a summary per file

File	Description
_human_input.py	New module providing HumanInputRequest, HumanInputHookMixin, and _HumanInputInterceptor for unified HITL support
_sequential.py	Added HumanInputHookMixin to SequentialBuilder, inserting interceptors between agents and response converters
_concurrent.py	Added HumanInputHookMixin to ConcurrentBuilder, inserting interceptor between fan-in and aggregator
_group_chat.py	Added HumanInputHookMixin to GroupChatBuilder, wrapping participant pipelines with interceptors and extracting trailing user messages
_handoff.py	Added HumanInputHookMixin to HandoffBuilder with agent ID extraction logic for interceptor prefixes
_magentic.py	Added documentation explaining MagenticBuilder's specialized HITL mechanisms; accidental regex change detected
__init__.py	Exported new public API: HumanInputHook, HumanInputHookMixin, HumanInputHookResult, HumanInputRequest
test_human_input_hook.py	Unit tests for HumanInputRequest, HumanInputHookMixin, and _HumanInputInterceptor
test_handoff.py	Tests verifying HandoffBuilder supports human input hook with method chaining
test_magentic.py	Test confirming MagenticBuilder correctly lacks generic human input hook
sequential_builder_tool_approval.py	Sample demonstrating tool approval with SequentialBuilder using @ai_function decorator
concurrent_builder_tool_approval.py	Sample demonstrating tool approval with ConcurrentBuilder across parallel agents
group_chat_builder_tool_approval.py	Sample demonstrating tool approval with GroupChatBuilder in multi-agent collaboration
sequential_human_input_hook.py	Sample demonstrating custom human input hook with SequentialBuilder for mid-workflow feedback
concurrent_human_input_hook.py	Sample demonstrating human input hook with ConcurrentBuilder for reviewing concurrent outputs
group_chat_human_input_hook.py	Sample demonstrating human input hook with GroupChatBuilder for steering group discussions
README.md	Updated with new HITL and tool-approval sample sections
SAMPLE_GUIDELINES.md	Updated guideline to place sample docstrings underneath imports rather than at top of file