.NET: Forward agent response details in workflows

[Vincent Biret (baywet)]

Motivation & Context

.NET workflow agent hosts currently forward only sanitized ChatMessage instances to downstream executors. Custom executors that need response-level details, such as detecting ChatFinishReason.Length after a low MaxOutputTokens run, must observe workflow events externally and manually bridge that state back into the workflow.

This adds an opt-in workflow message that carries the complete AgentResponse to downstream executors while keeping the existing chat-message forwarding path unchanged by default.

Description & Review Guide

• What are the major changes?
  • Adds AIAgentHostResponse, a public workflow message envelope containing the producing executor ID, complete AgentResponse, portable full conversation, and sanitized forwarded response messages.
  • Adds AIAgentHostOptions.ForwardAgentResponse to opt into forwarding that envelope from AIAgentHostExecutor.
  • Updates AIAgentHostExecutor protocol metadata and adds unit coverage for forwarding response metadata and preserving default behavior.
• What is the impact of these changes?
  • Custom downstream executors can inspect response metadata such as finish reason, usage, response ID, and additional properties without replacing the built-in agent host executor.
  • Existing workflows continue to receive the same chat-message and turn-token flow unless the new option is enabled.
• What do you want reviewers to focus on?
  • Whether the new opt-in message shape exposes the right response details for custom downstream executors while preserving safe chat-message forwarding semantics.

Related Issue

Fixes #2148

No other open PR was found for this issue.

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 opt-in forwarding of complete .NET agent responses to downstream workflow executors while preserving default chat-message behavior.

Changes:

• Adds AIAgentHostResponse and ForwardAgentResponse.
• Sends response metadata with sanitized conversation messages.
• Adds unit and public API coverage.

Reviewed changes

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

Show a summary per file

File	Description
AIAgentHostExecutorTests.cs	Tests enabled and default forwarding behavior.
AIAgentHostExecutor.cs	Sends the optional response envelope.
AIAgentHostOptions.cs	Defines the option and envelope API.
PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt	Records the new API.
PublicAPI/net8.0/PublicAPI.Unshipped.txt	Records the new API.
PublicAPI/net9.0/PublicAPI.Unshipped.txt	Records the new API.
PublicAPI/net10.0/PublicAPI.Unshipped.txt	Records the new API.
PublicAPI/net472/PublicAPI.Unshipped.txt	Records the new API.

---

💡 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)): 2cabd71f53fc
Model: gpt-5.6-sol

Overview

The PR adds an opt-in envelope for complete agent responses while preserving the default chat-only behavior and filtering provider-specific artifacts from portable messages. Runtime type declarations, edge filtering, null guards, and tests constrain the new path. However, the framework does not register the new queued message with its default checkpoint serializer, so checkpointed workflows using the feature fail before downstream handling.

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

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

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall line coverage in commit e005213 in the feat/additional-deta... branch is 83%. Line coverage data for the main branch is not yet available.

Show a line coverage summary of the most covered files.

File	main	feat/additional-deta... e005213	+/-
/home/runner/wo...valConverter.cs	—	100%	—
/home/runner/wo...entsProvider.cs	—	99%	—
/home/runner/wo...nticAnalyzer.cs	—	94%	—
/home/runner/wo...tClientAgent.cs	—	91%	—
/home/runner/wo...putConverter.cs	—	90%	—
/home/runner/wo...kflowBuilder.cs	—	90%	—
/home/runner/wo...kflowSession.cs	—	87%	—
/home/runner/wo...SkillsSource.cs	—	86%	—
/home/runner/wo...onExtensions.cs	—	81%	—
/home/runner/wo...ctionVisitor.cs	—	70%	—

---

_{Updated September 01, 2026 17:37 UTC}

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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