Python: Support checkpoint hydration and new input in a single workflow run (#7863)

[Shivani . (Shivani767)]

Motivation & Context

Resuming a multi-turn workflow from a persisted checkpoint previously required two workflow.run calls: hydrate from the checkpoint, then submit the new user input. That adds an unnecessary round trip, can surface intermediate hydrate events to adapters, and complicates HTTP/hosted request handlers that receive one logical request (#7863).

Description & Review Guide

• What are the major changes?

  • Allow Workflow.run(message=..., checkpoint_id=...) (and the functional-workflow mirror): restore/validate first, then seed start-executor input in the same run.
  • Skip the leftover in-flight-message guard when checkpoint_id is present, because restore replaces the runner context before the new message is applied.
  • Collapse WorkflowAgent’s restore-then-run path into one workflow.run when both checkpoint and input are provided (HITL uses responses + checkpoint_id; idle turns use message + checkpoint_id).
  • Keep AG-UI pure checkpoint resume behavior (messages still map through HITL responses); clarify the branch comments.
  • Add unit tests for graph + functional workflows, including “invalid checkpoint does not execute message”.
  • Add runnable sample: python/samples/03-workflows/checkpoint/checkpoint_hydrate_with_input.py.

• What is the impact of these changes?

  • Hosts can hydrate and continue in one lifecycle (tracing, cancellation, streaming).
  • Existing two-step usage and checkpoint_id + responses remain supported.
  • Foundry hosting still uses its two-step path when restore/save storages can differ; that adapter can adopt the single-call API in a follow-up.

• What do you want reviewers to focus on?

  • Semantics of restore-then-seed vs restore-only.
  • Whether WorkflowAgent peeking checkpoint.pending_request_info_events is the right HITL vs idle discriminator.

Related Issue

Fixes #7863

Related: #7809

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.

[Copilot]

Pull request overview

Adds single-call checkpoint hydration plus new input for Python workflows.

Changes:

• Supports message with checkpoint_id in graph and functional workflows.
• Updates workflow adapters and adds checkpoint-resume coverage.
• Adds a runnable hydration sample.

Reviewed changes

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

Show a summary per file

File	Description
python/samples/03-workflows/checkpoint/checkpoint_hydrate_with_input.py	Demonstrates combined hydration and input.
python/packages/core/tests/workflow/test_workflow.py	Updates parameter validation tests.
python/packages/core/tests/workflow/test_functional_workflow.py	Tests functional combined runs.
python/packages/core/tests/workflow/test_checkpoint.py	Tests graph hydration, streaming, and validation failure.
python/packages/core/agent_framework/_workflows/_workflow.py	Implements graph restore-then-seed behavior.
python/packages/core/agent_framework/_workflows/_functional.py	Enables the functional API combination.
python/packages/core/agent_framework/_workflows/_agent.py	Consolidates agent checkpoint continuation.
python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py	Clarifies AG-UI checkpoint routing.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Evan Mattson (moonbox3)]

We appreciate you taking this on, Shivani . (@Shivani767). This is going to require some deeper design from the team first, before we go and work on the implementation. Closing so I can take this over.

[Shivani . (Shivani767)]

Understood — Evan Mattson (@moonbox3)'s note on #7863 says any community PRs for this will be closed so the MAF team can own the design, so I am not opening a replacement for #7910. Leaving the design with you.

When the design does land, these were the two things worth carrying over from this attempt:

1. Don't restore the step replay cache on a message-plus-checkpoint run. _run_core imports the checkpoint's _step_cache, and step-cache keys are only step name + call index (_functional.py:322-329). After a completed run, a different new message therefore bypasses each @step and returns the prior turn's cached results. Restore user state, but not the replay cache, for message+checkpoint; keep cache restoration for checkpoint-only / HITL continuation.

2. Ordering: restore must complete before fresh-turn bookkeeping, with message seeding after restore. In the graph workflow the combined path restored after _run_workflow_with_tracing had already reset the iteration counter and written fresh per-run kwargs (_workflow.py:541-566), so restore_from_checkpoint reinstated the checkpoint's iteration/state and undid both. Repeated hydrate-plus-message turns could then hit max_iterations without processing the new message, and new invocation/client kwargs were replaced by stale checkpoint values.

Also worth noting for whoever implements it: Workflow.run currently documents message as not allowed with checkpoint_id (_workflow.py:279), and checkpoint_id + responses is already the supported single-call HITL path — so the change is mainly about letting message join that combination.

Happy to rebase this sample/tests against the team's implementation, or to review, when it is ready — just ping me here or on #7863.