.NET: Validate handoff request lifecycle before routing

[Roger Barreto (rogerbarreto)]

Motivation & Context

Handoff routing should distinguish unresolved requests from completed tool lifecycle events and preserve the identity of the agent producing each request. This keeps streamed tool updates consistent with workflow routing decisions.

Description & Review Guide

• What are the major changes? Validate the assistant role, agent identity, call identifier, and configured handoff declaration before retaining a routing candidate. Process completions in stream order and remove candidates with matching call identifiers. Keep tracking state local to each invocation. Add in-memory regression coverage and wait for the workflow halt boundary before restoring state in the checkpoint test sample.
• What is the impact of these changes? Valid unresolved handoff requests continue to route. Completed calls no longer remain routing candidates, and cancellation does not carry candidate state into the next invocation. Provider event projection and public API signatures are unchanged.
• What do you want reviewers to focus on? Request eligibility, completion matching, cancellation isolation, and the checkpoint sample's ordering between event consumption and state restoration.

Related Issue

N/A.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible. The affected Workflows and GitHub Copilot unit suites pass; the full repository suite was not run.
• 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]

Copilot review overview

🟢 Approval recommended

The lifecycle logic is consistent with the routing model and is covered by focused regression tests.

Review effort: Balanced
Findings: None

What changed in this PR

Validates handoff request lifecycle before routing and prevents completed or ineligible tool calls from triggering handoffs.

Changes:

• Tracks unresolved handoff calls by stream order, identity, role, declaration, and call ID.
• Adds regression coverage for completion matching, provenance, eligibility, and cancellation isolation.
• Waits for workflow halt before checkpoint restoration.

File	Description
dotnet/​src/​Microsoft.Agents.AI.Workflows/​Specialized/​HandoffAgentExecutor.cs	Validates and tracks routing candidates.
dotnet/​tests/​Microsoft.Agents.AI.Workflows.UnitTests/​HandoffAgentExecutorTests.cs	Covers updated lifecycle behavior.
dotnet/​tests/​Microsoft.Agents.AI.Workflows.UnitTests/​Sample/​05_Simple_Workflow_Checkpointing.cs	Synchronizes restoration with workflow halt.

---

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

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 932c4530dfb2
Model: gpt-5.6-sol-fast

Overview

The change makes handoff selection invocation-local, processes completions in stream order, and adds useful coverage for matching completions, unrelated completions, malformed provenance, and cancellation. However, it treats optional streaming metadata as mandatory on each delta, which breaks valid handoffs for supported agents/providers, and it matches completions by a globally unscoped call ID, allowing another producer's result to suppress routing.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (1 high, 1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall line coverage in commit faa1caa in the i128r643-handoff-val... branch is 85%. Line coverage data for the main branch is not yet available.

Show a line coverage summary of the most covered files.

File	main	i128r643-handoff-val... faa1caa	+/-
/home/runner/wo...valConverter.cs	—	100%	—
/home/runner/wo...entsProvider.cs	—	99%	—
/home/runner/wo...egatingAgent.cs	—	99%	—
/home/runner/wo...nticAnalyzer.cs	—	94%	—
/home/runner/wo...putConverter.cs	—	90%	—
/home/runner/wo...kflowBuilder.cs	—	90%	—
/home/runner/wo...SkillsSource.cs	—	89%	—
/home/runner/wo...onExtensions.cs	—	81%	—
/home/runner/wo...CopilotAgent.cs	—	76%	—
/home/runner/wo...ctionVisitor.cs	—	75%	—

---

_{Updated September 29, 2026 17:13 UTC}