.NET: Add regression tests and sample guidance for stable agent IDs in checkpointed workflows

[peibekwe]

Motivation & Context

When a workflow is hosted as an agent and later rebuilt (for example, agents registered as scoped in dependency injection), its inner agents get brand-new random IDs unless you set them explicitly. Because a workflow's saved checkpoint is tied to those IDs, resuming the session on a later request fails with InvalidDataException: The specified checkpoint is not compatible with the workflow.... This is the problem reported in #4793.

The fix is already available today: give each inner agent a stable, unique ChatClientAgentOptions.Id (and, if you set a Name, keep it stable too). This PR doesn't change product behavior; it adds coverage and guidance, so the pattern is clear and protected.

The samples also expose tagged snippet regions so the documentation can reference them directly.

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 regression coverage and sample guidance to ensure checkpointed workflows hosted as agents can be resumed across reconstruction by keeping inner agent executor identities stable (via stable ChatClientAgentOptions.Id / Name), addressing the scenario described in #4793.

Changes:

• Adds unit tests validating that workflow-as-agent sessions resume across reconstruction only when inner agents have stable IDs.
• Updates the Handoff orchestration sample to assign stable agent IDs (and exposes a snippet region for docs).
• Adds guidance/snippet region to the checkpoint rehydration sample explaining identity/topology requirements for resume.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowAgentCheckpointIdentityTests.cs	New regression tests covering checkpoint resume behavior with stable vs random inner agent IDs.
dotnet/samples/03-workflows/Orchestration/Handoff/AgentRegistry.cs	Updates sample agents to use explicit stable ChatClientAgentOptions.Id and adds a documentation snippet region.
dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs	Adds in-sample guidance (tagged snippet) about preserving executor identities/topology when rehydrating from checkpoints.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 92%

✓ Correctness

This PR adds regression tests and sample guidance for stable agent IDs in checkpointed workflows. All API usage is verified correct: ChatClientAgentOptions.Id property exists, the AsAIAgent overload accepting options is valid, FunctionCallContent constructor parameter order (callId, name) is correct, and the RunAsync(string, AgentSession?) overload exists. The migration from the old positional-parameter API to the new ChatClientAgentOptions-based API in the Handoff sample correctly maps instructions→ChatOptions.Instructions and name→Name while adding the new stable Id property. No correctness issues found.

✓ Security Reliability

This PR adds regression tests and sample guidance for stable agent IDs in checkpointed workflows. The changes are documentation comments, hardcoded stable ID strings in samples, and well-structured unit tests. No security or reliability issues found. The null-forgiving operator on handoffTool in test code is safe because the handoff workflow framework guarantees the tool is always present. No resources are leaked since neither AIAgent nor AgentSession implement IDisposable.

✓ Test Coverage

The new tests are well-structured with meaningful assertions and appropriate mocks, covering both the happy path (stable IDs resume correctly) and failure path (random IDs fail on resume). The only notable coverage gap is that the test class docstring explicitly claims Name stability is also required (verified at AIAgentExtensions.cs:15 where executor identity = '{Name}_{Id}' when Name is set), but no test verifies that changing the Name while keeping the Id stable causes a failure.

✓ Failure Modes

This PR adds regression tests and sample guidance for stable agent IDs in checkpointed workflows. The changes are well-structured: documentation comments, sample refactoring from positional-argument API to explicit ChatClientAgentOptions with stable Ids, and two clear regression tests. No silent failure modes, swallowed exceptions, lost errors, or operational issues were found in the diff.

✓ Design Approach

I did not find a design-approach issue in this diff. The new regression test exercises the actual checkpoint compatibility gate in InProcessRunner, and the sample guidance matches the implementation: local AIAgent instances default to random IDs, while workflow executor IDs are derived from both agent Id and, when present, Name via GetDescriptiveId(), so preserving stable inner-agent identity is the right problem to document and protect here.

Suggestions

• Consider adding a test that sets stable Ids but changes the Name between reconstruction cycles, to cover the documented claim that 'if an agent also sets a Name, that name must stay stable because the executor id includes it'. The code at AIAgentExtensions.cs:15 confirms this ($"{agent.Name}_{agent.Id}"), but the test suite currently only varies Id, not Name.

---

Automated review by peibekwe's agents

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 94%

✓ Correctness

The PR adds well-structured regression tests and sample guidance for stable agent IDs in checkpointed workflows. The tests correctly exercise the three key scenarios (stable IDs succeed, random IDs fail, changed names fail) based on the executor identity derivation in GetDescriptiveId which combines Name and Id. The sample migration from the old AsAIAgent(instructions, name) API to the new ChatClientAgentOptions-based API is correct. The previously flaged null-safety issue with handoffTool has been properly resolved with a null-coalescing throw pattern. No correctness issues found.

✓ Security Reliability

This PR adds regression tests and sample guidance for stable agent IDs in checkpointed workflows. The changes are documentation, sample updates, and test-only code with no product behavior modifications. The null-handling pattern at line 151-153 of the test file (previously flaged and resolved) is correctly implemented using the ?? throw idiom. The StatelessMockChatClient test mock is appropriately minimal with no resource leaks. The stable ID pattern in the sample (AgentRegistry.cs) correctly assigns fixed string IDs to all agents. No security or reliability issues found.

✓ Test Coverage

The test coverage for the stable agent ID regression scenario is strong. Three tests cover the critical matrix: stable IDs succeed, unstable IDs fail, and stable IDs with changed names fail. Assertions verify both first-turn behavior and reconstruction behavior, and the negative tests assert specific exception types and messages rather than just 'any exception'. The StatelessMockChatClient is appropriate and consistent with existing mock patterns in the project. The previously flaged null-safety issue for the handoff tool lookup is resolved with an explicit guard. No blocking test coverage gaps found.

✓ Failure Modes

This PR adds well-structured regression tests and sample guidance for stable agent IDs in checkpointed workflows. The test file correctly exercises three scenarios: stable IDs resuming successfully, random IDs failing on reconstruction, and stable IDs with changed names failing. The sample changes correctly migrate from the old positional AsAIAgent API to the ChatClientAgentOptions API with explicit stable Ids. The previously-flaged null-safety issue for the handoff tool lookup is already addressed with ?? throw new InvalidOperationException(...). No silent failures, swallowed exceptions, lost errors, or operational failure modes were identified.

✗ Design Approach

The new guidance and negative-path tests line up with the workflow checkpoint contract, but the positive regression test does not actually prove that a serialized session resumed. Because the mock specialist returns the same fixed reply on every turn, the test would still pass if deserialization accidentally produced a fresh compatible session instead of restoring checkpointed state.

Flagged Issues

• The success-case regression test in WorkflowAgentCheckpointIdentityTests.cs only checks for a repeated canned reply, so it does not distinguish a real checkpoint resume from a fresh run. The mock at lines 158-160 and assertion at lines 49-54 would both succeed in either case. The repo already has a stronger resume-proof pattern in CountingWorkflow.cs (lines 10-13, 31-36) where the second turn must observe checkpointed state to distinguish resume from restart.

---

Automated review by peibekwe's agents

[github-actions]

Flagged issue

The success-case regression test in WorkflowAgentCheckpointIdentityTests.cs only checks for a repeated canned reply, so it does not distinguish a real checkpoint resume from a fresh run. The mock at lines 158-160 and assertion at lines 49-54 would both succeed in either case. The repo already has a stronger resume-proof pattern in CountingWorkflow.cs (lines 10-13, 31-36) where the second turn must observe checkpointed state to distinguish resume from restart.

---

Source: automated DevFlow PR review

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 46% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by moonbox3's agents