Skip to content

.NET: Add decorator for structured output support - #3694

Merged
SergeyMenshykh merged 4 commits into
microsoft:feature-sofrom
SergeyMenshykh:add-so-decorator
Feb 5, 2026
Merged

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

Conversation

@SergeyMenshykh

@SergeyMenshykhSergeyMenshykh commented Feb 5, 2026

Copy link
Copy Markdown
Contributor

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.

CopilotAI review requested due to automatic review settings February 5, 2026 11:41
@SergeyMenshykhSergeyMenshykh self-assigned this Feb 5, 2026
@markwallace-microsoftMark Wallace (markwallace-microsoft) added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net labels Feb 5, 2026
@SergeyMenshykhSergeyMenshykh moved this to In Review in Agent FrameworkFeb 5, 2026
CopilotAI reviewed Feb 5, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
FileDescription
dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.csCore decorator implementing structured output transformation using a chat client
dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.csResponse wrapper preserving both structured output and original agent response
dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentOptions.csConfiguration options for system message and chat options
dotnet/src/Microsoft.Agents.AI/StructuredOutput/AIAgentBuilderExtensions.csBuilder extension method following established patterns for middleware registration
dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse{T}.csNew constructor accepting ChatResponse for broader response type support
dotnet/tests/Microsoft.Agents.AI.UnitTests/StructuredOutput/StructuredOutputAgentTests.csComprehensive unit tests covering constructor validation, response format handling, invocation flow, and error scenarios
dotnet/tests/Microsoft.Agents.AI.UnitTests/StructuredOutput/StructuredOutputAgentResponseTests.csUnit tests validating response wrapper behavior and property access
dotnet/tests/Microsoft.Agents.AI.UnitTests/StructuredOutput/AIAgentBuilderExtensionsTests.csUnit tests for builder extension methods and service resolution
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.csRefactored sample demonstrating four approaches to structured output
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/README.mdDocumentation explaining sample prerequisites and expected behavior

Comment threaddotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs
westey-m
westey (westey-m) reviewed Feb 5, 2026
View reviewed changes
Comment threaddotnet/src/Microsoft.Agents.AI/StructuredOutput/AIAgentBuilderExtensions.cs Outdated
westey-m
westey (westey-m) reviewed Feb 5, 2026
View reviewed changes
Comment threaddotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentOptions.cs Outdated
westey-m
westey (westey-m) reviewed Feb 5, 2026
View reviewed changes
Comment threaddotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.cs Outdated
@SergeyMenshykh@westey-m
Update dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutp…
e849bb4
…utAgentResponse.cs
Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
CopilotAI review requested due to automatic review settings February 5, 2026 14:16
westey-m
westey (westey-m) reviewed Feb 5, 2026
View reviewed changes
Comment threaddotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs Outdated
CopilotAI reviewed Feb 5, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Comment threaddotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.cs
Comment threaddotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgent.cs Outdated
@SergeyMenshykh@westey-m
Update dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOu…
0725aae
…tput/Program.cs
Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
CopilotAI review requested due to automatic review settings February 5, 2026 14:37
CopilotAI reviewed Feb 5, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Comment threaddotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs
@SergeyMenshykh
SergeyMenshykh merged commit 9991eb6 into microsoft:feature-soFeb 5, 2026
10 checks passed
@github-project-automationgithub-project-automationBot moved this from In Review to Done in Agent FrameworkFeb 5, 2026
github-merge-queueBot pushed a commit that referenced this pull request Feb 13, 2026
@SergeyMenshykh@westey-m
.NET: [Breaking] Structured Output improvements (#3761)
9506fb2
* .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>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@peibekwePeter Ibekwe (peibekwe)peibekwe approved these changes
@westey-mwestey (westey-m)westey-m approved these changes

Assignees

@SergeyMenshykhSergeyMenshykh

Labels

documentationUsage: [Issues, PRs], Target: documentation in the code base and learn docs.NETUsage: [Issues, PRs], Target: .Net

Projects

Agent Framework
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@SergeyMenshykh@peibekwe@westey-m@markwallace-microsoft