Python: include checkpoint_id on AG-UI interrupt metadata (#8150) by FOWEPJF255 · Pull Request #8163 · microsoft/agent-framework

lsmlhi_25 (FOWEPJF255) · 2026-09-08T17:45:26Z

Motivation & Context

AG-UI workflow interrupts need a durable pause checkpoint_id so multi-worker clients can resume via forwardedProps.checkpoint_id without a side-channel lookup (Option A from #8150).

Description & Review Guide

What are the major changes?
- Attach the pause checkpoint_id to each interrupt's metadata.agent_framework when AG-UI workflow runs finish with interrupts and checkpoint storage is active.
- Prefer this runner's last-saved pause checkpoint over shared get_latest(workflow_name=...) (avoids cross-owner races / stale ids).
- Resolve builder-configured checkpoint storage via the workflow runner when run_workflow_stream does not pass checkpoint_storage.
- Skip storage work when interrupts is empty; remove the unused checkpoint_id kwarg on _workflow_interrupt_metadata.
What is the impact of these changes?
- Clients can round-trip the pause checkpoint id from interrupt metadata for durable resume across workers.
What do you want reviewers to focus on?
- Correctness of pause-id selection vs shared get_latest, builder-only storage path, and empty-interrupt short-circuit.

Related Issue

Fixes #8150

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.

…8150) Attach the pause workflow checkpoint id to RUN_FINISHED interrupt metadata.agent_framework so multi-worker clients can resume via forwardedProps.checkpoint_id without a side channel.

Copilot

🟡 Changes recommended

Checkpoint selection can advertise a stale or different request owner’s checkpoint ID.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds checkpoint IDs to AG-UI workflow interrupt metadata for durable multi-worker resume.

Changes:

Resolves and attaches pause checkpoint IDs to interrupts.
Adds helper and checkpoint-resume coverage.

File summaries

File	Description
`_workflow_run.py`	Adds checkpoint lookup and interrupt metadata enrichment.
`test_workflow_run.py`	Tests attachment and checkpoint ID propagation.

Review details

Files reviewed: 2/2 changed files
Comments generated: 3
Review effort level: Balanced

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

…oft#8150)

lsmlhi_25 (FOWEPJF255) · 2026-09-09T02:26:24Z

Addressed review feedback:

Stop using shared get_latest(workflow_name=...) (races across owners / stale ids). Prefer this runner's _previous_checkpoint_id and only advertise it when the checkpoint's pending request set covers the interrupt ids.
Resolve builder-configured storage via the workflow runner when run_workflow_stream does not pass checkpoint_storage.
Skip storage work when interrupts is empty; remove the unused checkpoint_id kwarg on _workflow_interrupt_metadata.
Added regression tests for competing shared latest + builder-only storage.

Evan Mattson (moonbox3) · 2026-09-09T03:01:43Z

lsmlhi_25 (@FOWEPJF255):

Please update the PR body to use our approved template: https://github.com/microsoft/agent-framework/blob/main/.github/pull_request_template.md
Per our contributing guidelines, please respond to all open PR comments as to whether they're addressed or not. Then resolve the threads once done.
Please also fix the failing code quality checks.

lsmlhi_25 (FOWEPJF255) · 2026-09-09T07:15:20Z

Evan Mattson (@moonbox3) Thanks 鈥?addressed your checklist:

PR body updated to the approved template.
Replied on each review thread and resolved them.
Pushed a follow-up for the failing code quality checks: ruff I001 (import blank line) and ty ignores on the new yield_output("done") test helpers.

Move pause-checkpoint selection into Workflow and require a run-scoped baseline so leftover runner ids are not advertised across runs.

lsmlhi_25 (FOWEPJF255) · 2026-09-09T09:23:54Z

Evan Mattson (@moonbox3) Follow-up for the run-scoped / core-helper review:

Workflow.get_last_checkpoint_id() + Workflow.resolve_pause_checkpoint_id(...) in core (storage precedence, pending-request coverage, run-scoped baseline filter).
AG-UI captures the baseline before workflow.run() and no longer digs into Runner private fields for pause-id selection.
Regression tests in core test_pause_checkpoint_resolve.py and AG-UI run-scoped coverage.

Commit: 68f5abe.

Unblocks Package Checks / merge-gatekeeper on PR microsoft#8163.

Evan Mattson (moonbox3) · 2026-09-10T08:29:27Z

+        candidates: list[str] = []
+        if runner_candidate is not None:
+            candidates.append(runner_candidate)
+        if known_checkpoint_id is not None and known_checkpoint_id not in candidates:
+            candidates.append(str(known_checkpoint_id))
+
+        if storage is None and not use_context_storage:
+            # Without storage we cannot prove coverage; only advertise a run-scoped runner id.
+            return runner_candidate
+
+        for candidate in candidates:
+            try:
+                if storage is not None:
+                    checkpoint = await storage.load(candidate)
+                else:
+                    checkpoint = await self._runner.context.load_checkpoint(candidate)
+            except Exception:  # pragma: no cover - storage/type drift
+                logger.debug("Could not load pause checkpoint candidate %s", candidate, exc_info=True)
+                continue
+            if checkpoint is None:
+                continue
+            pending = checkpoint.pending_request_info_events or {}
+            if ids.issubset({str(key) for key in dict(pending)}):
+                return candidate


Following up on the run-scoping feedback: could we exclude the incoming restored checkpoint from these candidates after execution resumes? A supported response handler can reissue the same request ID, and if the new pause save fails, known_checkpoint_id still loads the old checkpoint and the key-only coverage check at _workflow.py:1344-1346 accepts it. The emitted ID then restores pre-response state, so tracking the checkpoint successfully created by this run rather than the restored ID would avoid replaying stale work.

Evan Mattson (moonbox3) · 2026-09-10T08:29:27Z

+    def get_last_checkpoint_id(self) -> str | None:
+        """Return the checkpoint id last persisted or restored by this workflow runner.
+
+        Capture this value before ``run()`` when a host needs a run-scoped pause id:
+        after the run, only a different id indicates *this* run advanced the chain.
+        """
+        checkpoint_id = self._runner._previous_checkpoint_id  # pyright: ignore[reportPrivateUsage]
+        return str(checkpoint_id) if checkpoint_id is not None else None
+
+    async def resolve_pause_checkpoint_id(
+        self,
+        request_ids: Collection[str],
+        *,
+        checkpoint_storage: CheckpointStorage | None = None,
+        known_checkpoint_id: str | None = None,
+        baseline_checkpoint_id: str | None = None,
+    ) -> str | None:


Would it make sense for Workflow to own the run boundary used by resolve_pause_checkpoint_id()? Every caller now has to call get_last_checkpoint_id() before run(), retain it across every exit path, and pass it back as baseline_checkpoint_id; mistiming that sequence lets a restored checkpoint look newly persisted. Tracking the checkpoint created by the most recent run inside Workflow would remove that ordering protocol while preserving the AG-UI behavior.

Python: include checkpoint_id on AG-UI interrupt metadata (microsoft#…

5c44073

…8150) Attach the pause workflow checkpoint id to RUN_FINISHED interrupt metadata.agent_framework so multi-worker clients can resume via forwardedProps.checkpoint_id without a side channel.

Copilot AI balanced review requested due to automatic review settings September 8, 2026 17:45

lsmlhi_25 (FOWEPJF255) requested review from chetantoshniwal, Eduard van Valkenburg (eavanvalkenburg), Giles Odigwe (giles17) and Evan Mattson (moonbox3) as code owners September 8, 2026 17:45

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 8, 2026 17:45 — with GitHub Actions Active

agent-framework-automation Bot added the python Usage: [Issues, PRs], Target: Python label Sep 8, 2026

Copilot started reviewing on behalf of lsmlhi_25 (FOWEPJF255) September 8, 2026 17:46 View session

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 8, 2026 17:46 — with GitHub Actions Active

Copilot AI reviewed Sep 8, 2026

View reviewed changes

Comment thread python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py Outdated

Comment thread python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py Outdated

Comment thread python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py Outdated

Evan Mattson (moonbox3) reviewed Sep 9, 2026

View reviewed changes

Comment thread python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py Outdated

Python: Prefer runner pause checkpoint over shared get_latest (micros…

8e36bd4

…oft#8150)

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 9, 2026 02:26 — with GitHub Actions Active

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 9, 2026 05:10 — with GitHub Actions Active

Python: Fix ag-ui lint and ty ignores for microsoft#8150 tests

c6f10d8

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 9, 2026 07:15 — with GitHub Actions Active

Evan Mattson (moonbox3) reviewed Sep 9, 2026

View reviewed changes

Comment thread python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py Outdated

Comment thread python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py Outdated

Python: Core resolve_pause_checkpoint_id for AG-UI (microsoft#8150)

68f5abe

Move pause-checkpoint selection into Workflow and require a run-scoped baseline so leftover runner ids are not advertised across runs.

lsmlhi_25 (FOWEPJF255) requested review from Tao Chen (TaoChenOSU) and Jose Alvarez (jpalvarezl) as code owners September 9, 2026 09:23

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 9, 2026 09:23 — with GitHub Actions Active

fix(python): resolve pyright failures in pause checkpoint lookup

d4b60eb

Unblocks Package Checks / merge-gatekeeper on PR microsoft#8163.

lsmlhi_25 (FOWEPJF255) deployed to github-app-auth September 9, 2026 17:11 — with GitHub Actions Active

Evan Mattson (moonbox3) reviewed Sep 10, 2026

View reviewed changes

Navigation Menu

Uh oh!

Python: include checkpoint_id on AG-UI interrupt metadata (#8150) - #8163

Python: include checkpoint_id on AG-UI interrupt metadata (#8150)#8163
lsmlhi_25 (FOWEPJF255) wants to merge 5 commits into
microsoft:mainfrom
FOWEPJF255:fix/ag-ui-interrupt-checkpoint-8150

lsmlhi_25 (FOWEPJF255) commented Sep 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lsmlhi_25 (FOWEPJF255) commented Sep 9, 2026

Uh oh!

Evan Mattson (moonbox3) commented Sep 9, 2026 •

edited

Loading

Uh oh!

lsmlhi_25 (FOWEPJF255) commented Sep 9, 2026

Uh oh!

Uh oh!

Uh oh!

lsmlhi_25 (FOWEPJF255) commented Sep 9, 2026

Uh oh!

Evan Mattson (moonbox3) Sep 10, 2026

Uh oh!

Evan Mattson (moonbox3) Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

lsmlhi_25 (FOWEPJF255) commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation & Context

Description & Review Guide

Related Issue

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lsmlhi_25 (FOWEPJF255) commented Sep 9, 2026

Uh oh!

Evan Mattson (moonbox3) commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lsmlhi_25 (FOWEPJF255) commented Sep 9, 2026

Uh oh!

Uh oh!

Uh oh!

lsmlhi_25 (FOWEPJF255) commented Sep 9, 2026

Uh oh!

Evan Mattson (moonbox3) Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

Evan Mattson (moonbox3) Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lsmlhi_25 (FOWEPJF255) commented Sep 8, 2026 •

edited

Loading

Evan Mattson (moonbox3) commented Sep 9, 2026 •

edited

Loading