Python: [BREAKING] consolidate workflow run APIs

[moonbox3]

Motivation and Context

Summary

Consolidates workflow execution APIs from 6 methods into 2 unified methods with enhanced checkpoint storage capabilities.

Breaking Changes

• Removed methods: run_from_checkpoint(), run_stream_from_checkpoint(), send_responses(), send_responses_streaming()
• Unified API: All execution scenarios now use run() or run_stream() with optional parameters

New Capabilities

• Runtime checkpoint storage: Pass checkpoint_storage parameter to enable/override checkpointing at runtime
• Unified parameters: message, checkpoint_id, checkpoint_storage, responses support all execution scenarios
• Flexible configuration: Checkpoint storage can be configured at build-time, runtime, or both (runtime overrides build-time)

API Changes

# Before (3 separate methods for streaming)
workflow.run_stream(message)
workflow.run_stream_from_checkpoint(checkpoint_id)
workflow.send_responses_streaming(responses)

# After (1 unified method)
workflow.run_stream(message)
workflow.run_stream(checkpoint_id=checkpoint_id, checkpoint_storage=storage)
workflow.run_stream(responses=responses)
workflow.run_stream(message, checkpoint_storage=runtime_storage)  # NEW: runtime override

Implementation
Updated InProcRunnerContext to support runtime checkpoint storage override
Updated all internal consumers: WorkflowAgent, WorkflowExecutor, MagenticWorkflow
Updated all tests to use new API
Added comprehensive test coverage for runtime checkpoint scenarios across all workflow builders

TODO: will update Learn site docs.

Description

• Closes Python: Workflow API: Support runtime checkpoint management in run_stream() #1536

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.

[Copilot]

Pull Request Overview

This PR consolidates workflow execution APIs by removing 4 methods (run_from_checkpoint, run_stream_from_checkpoint, send_responses, send_responses_streaming) and enhancing the existing run() and run_stream() methods to handle all execution scenarios through optional parameters. The change introduces runtime checkpoint storage configuration, allowing checkpointing to be enabled or overridden at execution time rather than only at build time.

Key Changes:

• Unified run() and run_stream() methods now accept message, checkpoint_id, checkpoint_storage, and responses parameters
• Runtime checkpoint storage can override build-time configuration
• All sample code and tests updated to use the new unified API

Reviewed Changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_workflow.py	Consolidated 6 execution methods into 2 unified methods with enhanced parameter handling and runtime checkpoint storage support
python/packages/core/agent_framework/_workflows/_runner_context.py	Added runtime checkpoint storage override capability with set_runtime_checkpoint_storage() and clear_runtime_checkpoint_storage() methods
python/packages/core/agent_framework/_workflows/_magentic.py	Removed delegating methods that are now handled by base Workflow class
python/packages/core/agent_framework/_workflows/_workflow_executor.py	Updated to use run() with responses parameter
python/packages/core/agent_framework/_workflows/_agent.py	Updated to use run_stream() with responses parameter
python/packages/core/tests/workflow/test_workflow.py	Updated tests to use new API and added runtime checkpoint configuration tests
python/packages/core/tests/workflow/test_sequential.py	Added runtime checkpoint tests for sequential workflows
python/packages/core/tests/workflow/test_magentic.py	Updated tests and added runtime checkpoint configuration tests
python/packages/core/tests/workflow/test_sub_workflow.py	Updated to use run() with responses parameter
python/packages/core/tests/workflow/test_handoff.py	Updated to use run_stream() with responses parameter
python/packages/core/tests/workflow/test_group_chat.py	Added runtime checkpoint configuration tests
python/packages/core/tests/workflow/test_concurrent.py	Added runtime checkpoint configuration tests
python/packages/core/tests/workflow/test_checkpoint_validation.py	Updated to use run_stream() with checkpoint_id parameter
python/samples/*	Updated all sample code to use new unified API

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent.py	228	40	82%	54, 62–65, 93–94, 243, 284–287, 293, 299, 303–304, 307–313, 317–318, 357, 364, 370–371, 377, 389, 421, 428, 449, 456, 460, 462–464, 471
_magentic.py	930	264	71%	69–78, 83, 87–98, 322, 327, 344, 346, 361, 369–378, 457, 461, 475, 481, 496, 576, 589, 606, 615–616, 618–620, 622, 633, 700–704, 707–711, 791–794, 797–801, 803–805, 812, 851, 898, 934–936, 938, 1005, 1078, 1080–1081, 1089, 1125, 1134–1136, 1155, 1166, 1176–1177, 1179–1180, 1199, 1252, 1272, 1275, 1303, 1306, 1311, 1319–1323, 1329, 1357–1359, 1361, 1363, 1371–1374, 1376, 1380–1381, 1384–1387, 1389–1390, 1396–1398, 1401–1402, 1407–1408, 1416, 1424, 1439, 1451, 1463–1466, 1495–1496, 1501–1503, 1534, 1560, 1575, 1591, 1613, 1683, 1689–1690, 1704, 1706, 1709, 1711–1712, 1715–1716, 1720, 1723, 1744, 1781–1782, 1784, 1788–1790, 1806, 1817, 1827, 1871, 1876–1877, 2203–2204, 2208, 2223, 2228, 2231, 2291, 2302, 2313–2315, 2328–2329, 2334, 2345–2347, 2358–2360, 2372–2379, 2381–2382, 2390, 2398–2399, 2401–2403, 2405–2408, 2412–2420, 2424–2425, 2428–2432, 2434–2435, 2437–2439, 2441–2444, 2446–2448, 2450–2451, 2453–2455, 2470–2473, 2484–2487, 2499–2502, 2506
_runner_context.py	122	2	98%	295, 314
_workflow.py	269	24	91%	95, 262–264, 266–267, 285, 309, 311, 538, 551, 555, 693, 701, 705, 723, 736, 740, 776, 791–793, 806, 871
_workflow_executor.py	248	100	59%	305–306, 341–342, 379, 390–395, 398, 401–402, 409, 412, 415, 426, 450, 453, 459, 463, 476, 480, 505–506, 509–511, 517–518, 520–524, 526–529, 531–535, 537–542, 544, 551–554, 556–563, 565–566, 572–574, 576–579, 581–591, 596, 598–602, 604–606, 608–611, 616, 618, 651
TOTAL	12279	1993	83%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
1417	98 💤	0 ❌	0 🔥	28.831s ⏱️

[TaoChenOSU]

I am wondering if it is possible to have this PR reviewed and merged before this one because there is a major refactoring for the request & response pattern. That PR should be ready by the end of today.

[alliscode]

This usage will also result in enabling checkpointing for this run, right?

[moonbox3]

Yeah, the options are:

1. Enable checkpointing on the builder - will apply to every workflow run for that checkpoint instance (can still be useful)
2. Checkpointing is now allowed (and enabled) on a per-run basis, and will take precedence over the workflow level config.

[alliscode]

Curious why call out RequestInfoEvent here when there are a lot of WorkflowEvents. Maybe this could link to a readme or something where they are all documented?

[moonbox3]

I can remove the callout to RequestInfoEvent - especially because it'll be gone in Tao's PR. The goal is to get Tao's HIL refactor PR in first, then I'll bring in changes here and clean this up.

[moonbox3]

Waiting for #1466 to go in first, then will bring in changes to this PR.