Python [BREAKING]: support magentic agent tool call approvals and plan stalling HITL behavior

[moonbox3]

Motivation and Context

There are two areas of improvement related to HITL + Magentic workflows:

1. Right now, there's no way to provide HITL feedback as part of invoking an agent. To handle this, a dev can provide a tool with @ai_function(approval_mode="always_require"). This will then allow the dev to handle a RequestInfoEvent for a tool approval. The input is provided via MagenticHumanInterventionReply.

2. If a plan begins to fall off track, we have the option to do an auto replan, depending upon how the max_stall_count is configured. There's a new API that, instead of simply running auto replan, allows one to configure .with_human_input_on_stall() which will then kick it back to the human to help get the agents back on track.

As part of this work, the Magentic standard manager's chat client was updated to use the agent protocol. This aligns better with the pattern in the group chat orchestration, where it also accepts an agent.

Description

• Closes Python: magentic plan review does not trigger a RequestInfoEvent to allow for HITL #2261

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/_workflows
_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, 2290–2291, 2470–2471, 2473, 2487, 2492, 2495, 2551, 2562, 2573–2575, 2588–2589, 2594, 2605–2607, 2618–2620, 2632–2639, 2641–2642, 2650, 2658–2659, 2661–2663, 2665–2668, 2672–2680, 2684–2685, 2688–2692, 2694–2695, 2697–2700, 2702–2705, 2707–2709, 2711–2712, 2714–2716, 2731–2734, 2745–2748, 2760–2763, 2767
TOTAL	16022	2505	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2282	130 💤	0 ❌	0 🔥	57.953s ⏱️

[Copilot]

Pull request overview

This PR introduces breaking changes to support Human-in-the-Loop (HITL) capabilities in Magentic workflows, unifying the intervention mechanism and changing the StandardMagenticManager API.

Key Changes:

• Unified human intervention types (MagenticHumanInterventionRequest/Reply) replace separate plan review types, supporting plan review, tool approvals, and stall interventions
• StandardMagenticManager now accepts an agent parameter instead of chat_client, allowing the agent's configured options (temperature, seed, instructions) to be applied
• New .with_human_input_on_stall() builder method enables human intervention when workflows stall instead of automatic replanning

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_magentic.py	Core implementation: unified intervention types, StandardMagenticManager refactored to use AgentProtocol, MagenticOrchestratorExecutor adds stall intervention, MagenticAgentExecutor adds tool approval handling
python/packages/core/agent_framework/_workflows/init.py	Updated exports: removed old plan review types, added new unified intervention types and backward compatibility aliases
python/packages/core/tests/workflow/test_magentic.py	Updated test stubs and assertions to use new unified types and agent-based StandardMagenticManager
python/samples/getting_started/workflows/orchestration/magentic_human_replan.py	New sample demonstrating stall intervention with .with_human_input_on_stall()
python/samples/getting_started/workflows/orchestration/magentic_agent_clarification.py	New sample showing agent tool call approvals via @ai_function(approval_mode="always_require")
python/samples/getting_started/workflows/orchestration/magentic_human_plan_update.py	Updated to use unified intervention types with extended decision options (approve with comments, edit plan)
python/samples/getting_started/workflows/orchestration/magentic_checkpoint.py	Updated to use agent parameter and unified intervention types
python/samples/getting_started/workflows/orchestration/magentic.py	Updated to use agent parameter for StandardMagenticManager
python/samples/getting_started/workflows/agents/magentic_workflow_as_agent.py	Updated to use agent parameter for StandardMagenticManager
python/samples/semantic-kernel-migration/orchestrations/magentic.py	Updated to use agent parameter for StandardMagenticManager
python/samples/getting_started/workflows/README.md	Added documentation entries for the two new sample files

---

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.