.NET: Propagate AgentRunOptions to underlying workflow agents

[Saibernard]

Motivation & Context

Workflows exposed through AsAgent() currently discard the caller's AgentRunOptions. As a result, per-run settings such as chat options and additional properties do not reach agents executed by the workflow.

Description & Review Guide

• What are the major changes? Propagates AgentRunOptions through workflow sessions and turn tokens for sequential, concurrent, group chat, handoff, Magentic, custom ChatProtocolExecutor implementations, and nested workflows. The current invocation options are restored after checkpoint recovery without serializing them.
• What is the impact of these changes? Agents inside a hosted workflow receive the caller's per-run options. Existing ChatProtocolExecutor implementations remain compatible, and handoff instructions and tools are preserved when options are combined.
• What do you want reviewers to focus on? The option flow through checkpoint recovery and the handoff option merge.

Related Issue

Fixes #3679

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.

[Copilot]

Pull request overview

Fixes #3679 by propagating per-invocation AgentRunOptions through hosted workflows, nested workflows, and checkpoint recovery.

Changes:

• Carries run options through workflow contexts and TurnToken.
• Merges handoff-specific tools and instructions with caller options.
• Adds orchestration and recovery coverage across workflow types.

Reviewed changes

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

Show a summary per file

File	Description
dotnet/src/Microsoft.Agents.AI.Workflows/ChatProtocolExecutor.cs	Exposes full turn tokens to derived executors.
dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowContext.cs	Adds an internal run-options context contract.
dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowContextExtensions.cs	Resolves invocation options with fallback behavior.
dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessExecutionEnvironment.cs	Starts and resumes runs with invocation options.
dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunner.cs	Applies current options to restored turn tokens.
dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunnerContext.cs	Stores per-run options in execution context.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/AIAgentHostExecutor.cs	Passes options to hosted agents and continuations.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/GroupChatHost.cs	Forwards options to group-chat participants.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs	Merges caller and handoff options.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffStartExecutor.cs	Preserves the full token in handoff state.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticManager.cs	Passes options to manager-agent calls.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticOrchestrator.cs	Propagates options through Magentic turns.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/WorkflowHostExecutor.cs	Propagates options into nested workflows.
dotnet/src/Microsoft.Agents.AI.Workflows/TurnToken.cs	Adds nonserialized run options to turn tokens.
dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowHostAgent.cs	Supplies caller options to workflow sessions.
dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowSession.cs	Carries options through run creation and recovery.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/ChatProtocolExecutorTests.cs	Tests token forwarding and recovery.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/GroupChatOrchestrationTests.cs	Tests group-chat propagation.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/HandoffOrchestrationTests.cs	Tests handoff option merging.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/MagenticOrchestrationTests.cs	Tests Magentic propagation and recovery.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/OrchestrationTestHelpers.cs	Adds checkpoint test support.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/RecordingEchoAgent.cs	Records received options for assertions.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/RecordingReplayAgent.cs	Records replay-agent options.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/12_HandOff_HostAsAgent.cs	Records handoff-agent options.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowHostSmokeTests.cs	Covers sequential, concurrent, nested, and continuation flows.

---

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

[Copilot]

Pull request overview

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