.NET: Add decorator for structured output support by SergeyMenshykh · Pull Request #3694 · microsoft/agent-framework

SergeyMenshykh · 2026-02-05T11:41:40Z

Motivation and Context

Currently, some of AF's AI agents don't support structured output. This is either because it's not part of the protocol, like with the A2A agent, or because the agents use LLMs without structured output capabilities. AF needs a solution to address this gap and provide structured output support for these agents.

Description

This PR:

Adds the StructuredOutputAgent decorator that obtains text from a decorated agent and delegates it to the configured chat client for JSON transformation.
Adds the UseStructuredOutput extension method for the AIAgentBuilder, allowing easy registration of the decorator during the agent configuration step.
Restructures the structured output sample to showcase different ways of working with structured output in AF.

…t natively support it.

Copilot

Pull request overview

This PR adds structured output support for AI agents that don't natively support it, enabling text responses to be transformed into structured JSON format via a chat client.

Changes:

Introduces StructuredOutputAgent decorator that wraps agents and delegates text-to-JSON transformation to a configured chat client
Adds UseStructuredOutput extension method for AIAgentBuilder to enable easy integration
Adds AgentResponse<T> constructor accepting ChatResponse for enhanced interoperability
Refactors structured output sample to demonstrate four different approaches: ResponseFormat, generic RunAsync, streaming, and middleware-based

Reviewed changes

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

Show a summary per file

File	Description
dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.cs	Core decorator implementing structured output transformation using a chat client
dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.cs	Response wrapper preserving both structured output and original agent response
dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentOptions.cs	Configuration options for system message and chat options
dotnet/src/Microsoft.Agents.AI/StructuredOutput/AIAgentBuilderExtensions.cs	Builder extension method following established patterns for middleware registration
dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse{T}.cs	New constructor accepting ChatResponse for broader response type support
dotnet/tests/Microsoft.Agents.AI.UnitTests/StructuredOutput/StructuredOutputAgentTests.cs	Comprehensive unit tests covering constructor validation, response format handling, invocation flow, and error scenarios
dotnet/tests/Microsoft.Agents.AI.UnitTests/StructuredOutput/StructuredOutputAgentResponseTests.cs	Unit tests validating response wrapper behavior and property access
dotnet/tests/Microsoft.Agents.AI.UnitTests/StructuredOutput/AIAgentBuilderExtensionsTests.cs	Unit tests for builder extension methods and service resolution
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs	Refactored sample demonstrating four approaches to structured output
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/README.md	Documentation explaining sample prerequisites and expected behavior

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs

dotnet/src/Microsoft.Agents.AI/StructuredOutput/AIAgentBuilderExtensions.cs

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentOptions.cs

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.cs

…utAgentResponse.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.cs

…tput/Program.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

Copilot

Pull request overview

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

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs

* .NET: Delete AgentResponse.{Try}Deserialize<T> methods (#3518) * delete deserialize method of agent response * order usings * Update dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/Program.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/AGUIClientServer/AGUIDojoServer/SharedState/SharedStateAgent.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/M365Agent/Agents/WeatherForecastAgent.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * .NET:[Breaking] Add support for structured output (#3658) * add support for so * restore lost xml comment part * fix using ordering * Update dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgentStructuredOutput.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgentStructuredOutput.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_SO_WithFormatResponseTests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * addressw pr review comments * address pr review feedback * address pr review comments * fix compilation issues after the latest merge with main * remove unnecessry options * remove RunAsync<object> methods * address code review feedback * address pr review feedback * make copy constructor protected * address pr review feedback --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * .NET: Add decorator for structured output support (#3694) * add decorator that adds structured output support to agents that don't natively support it. * Update dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com> * Update dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com> * address pr review feedback --------- Co-authored-by: westey <164392973+westey-m@users.noreply.github.com> * .NET: Support primitives and arrays for SO (#3696) * wrap primitives and arrays * fix file encoding * address review comments * add adr * add missed change * fix compilation issue * address review comments * rename adr file name * reflect decision to have SO decorator as a reference implementation in samples * .NET: Move SO agent to samples (#3820) * move SO agent to samples * change file encoding * fix files encoding * .NET: Preserve caller context (#3803) * fix stuck orchestration * add previously removed RunAsync<T> method to DurableAIAgent * suppress IDE0005 warning * update changelog and remove unused constructor of AgentResponse<T> * updatge the changelog * address PR review feedback * .NET: Disable irrelevant integration test (#3913) * disable irrelevant integration test * Update dotnet/tests/AzureAI.IntegrationTests/AIProjectClientAgentStructuredOutputRunTests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * forgotten change * address pr review feedback * disable intermittently failing integration test. --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

add decorator that adds structured output support to agents that don'…

34be0ef

…t natively support it.

Copilot AI review requested due to automatic review settings February 5, 2026 11:41

SergeyMenshykh self-assigned this Feb 5, 2026

markwallace-microsoft added documentation Improvements or additions to documentation .NET labels Feb 5, 2026

SergeyMenshykh added this to Agent Framework Feb 5, 2026

SergeyMenshykh moved this to In Review in Agent Framework Feb 5, 2026

Copilot started reviewing on behalf of SergeyMenshykh February 5, 2026 11:42 View session

SergeyMenshykh temporarily deployed to integration February 5, 2026 11:43 — with GitHub Actions Inactive

Copilot AI reviewed Feb 5, 2026

View reviewed changes

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs Show resolved Hide resolved

westey-m reviewed Feb 5, 2026

View reviewed changes

dotnet/src/Microsoft.Agents.AI/StructuredOutput/AIAgentBuilderExtensions.cs Outdated Show resolved Hide resolved

westey-m reviewed Feb 5, 2026

View reviewed changes

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentOptions.cs Outdated Show resolved Hide resolved

westey-m reviewed Feb 5, 2026

View reviewed changes

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.cs Outdated Show resolved Hide resolved

Update dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutp…

e849bb4

…utAgentResponse.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 5, 2026 14:16

Copilot started reviewing on behalf of SergeyMenshykh February 5, 2026 14:17 View session

SergeyMenshykh temporarily deployed to integration February 5, 2026 14:18 — with GitHub Actions Inactive

westey-m reviewed Feb 5, 2026

View reviewed changes

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs Outdated Show resolved Hide resolved

westey-m approved these changes Feb 5, 2026

View reviewed changes

Copilot AI reviewed Feb 5, 2026

View reviewed changes

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.cs Show resolved Hide resolved

dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.cs Outdated Show resolved Hide resolved

Update dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOu…

0725aae

…tput/Program.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 5, 2026 14:37

SergeyMenshykh temporarily deployed to integration February 5, 2026 14:37 — with GitHub Actions Inactive

Copilot started reviewing on behalf of SergeyMenshykh February 5, 2026 14:37 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs Show resolved Hide resolved

address pr review feedback

8102b8d

SergeyMenshykh temporarily deployed to integration February 5, 2026 15:05 — with GitHub Actions Inactive

peibekwe approved these changes Feb 5, 2026

View reviewed changes

SergeyMenshykh merged commit 9991eb6 into microsoft:feature-so Feb 5, 2026
10 checks passed

github-project-automation bot moved this from In Review to Done in Agent Framework Feb 5, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.NET: Add decorator for structured output support#3694

.NET: Add decorator for structured output support#3694
SergeyMenshykh merged 4 commits intomicrosoft:feature-sofrom
SergeyMenshykh:add-so-decorator

SergeyMenshykh commented Feb 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

SergeyMenshykh commented Feb 5, 2026

Motivation and Context

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants