.NET: Fix AG-UI "Unknown chat role: reasoning" on follow-up turns by atty57 · Pull Request #8465 · microsoft/agent-framework

Atharva Vichare (atty57) · 2026-09-17T13:44:23Z

Motivation & Context

With a reasoning-enabled agent hosted via MapAGUIServer and a CopilotKit web chat, the first turn works, but every follow-up turn fails with HTTP 500:

System.InvalidOperationException: Unknown chat role: reasoning
   at AGUI.Abstractions.AGUIChatMessageExtensions.MapChatRole(String role)
   at AGUI.Abstractions.AGUIChatMessageExtensions.AsChatMessages(...)
   at AGUI.Server.RunAgentInputExtensions.ToChatRequestContext(...)

CopilotKit sends the earlier reasoning message back in messages. AGUI.Abstractions 0.0.6 deserializes it into an AGUIReasoningMessage, but MapChatRole has no mapping for the reasoning role and throws. The conversation can't continue after that.

Description & Review Guide

What are the major changes?
- Added an internal helper, AGUIEndpointRouteBuilderExtensions.RemoveReasoningMessages(RunAgentInput), which removes AGUIReasoningMessage entries from the request history. The endpoint calls it just before ToChatRequestContext.
- Added a unit test that deserializes a CopilotKit-style follow-up request (user → reasoning → assistant → user). It first confirms that the unmodified request still throws, then confirms that after the helper runs the conversion succeeds and the other messages stay in order.
What is the impact of these changes? Follow-up turns no longer fail when the client sends reasoning back. Reasoning from earlier turns is not passed to the agent. It never reached the agent before this change either, because those requests failed. There are no public API changes.
What do you want reviewers to focus on?

Maintainers, I'd like your opinion on the approach before this is marked ready. The change is small, but it makes a design decision, and I'm happy to rework it:
1. Fix it in the AG-UI .NET SDK (AGUI.Abstractions). The reasoning role is part of the AG-UI protocol, so MapChatRole / AsChatMessages arguably should handle it there. This PR could then be closed, or kept as a short-term workaround until a new package version ships.
2. Keep the reasoning instead of dropping it. Convert each AGUIReasoningMessage into TextReasoningContent on the assistant message it belongs to. That keeps reasoning context across turns, which may matter for Responses API reasoning continuity. The open questions are how to attach it to the right message and whether every provider accepts it.
3. Drop reasoning history (this PR). It's the smallest fix and the least likely to break anything, but reasoning from earlier turns is lost.
Should the chosen behavior be configurable (for example through AGUIStreamOptions), or just fixed?

Related Issue

Fixes #8462

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.

…crosoft#8462)

Copilot

🔵 Needs a closer look

Discarding reasoning history is a protocol-level design choice requiring maintainer review, and the endpoint behavior lacks integration coverage.

Pull request overview

Filters AG-UI reasoning messages from follow-up request history to prevent conversion failures.

Changes:

Removes reasoning messages before request conversion.
Adds a focused deserialization/conversion unit test.

File summaries

File	Description
`AGUIEndpointRouteBuilderExtensions.cs`	Filters unsupported reasoning messages.
`AGUIEndpointRouteBuilderExtensionsTests.cs`	Tests filtering and preserved ordering.

Review details

Files reviewed: 2/2 changed files
Comments generated: 1
Review effort level: Balanced

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

Copilot

🔵 Needs a closer look

The HTTP endpoint regression needs integration coverage to verify the filtering is wired into the request pipeline.

0 open findings

1 resolved since last review

The regression is in the mapped HTTP endpoint, but the new test calls the helper directly. It would…

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

Vincent Biret (baywet) · 2026-10-08T12:29:15Z

            var streamOptions = context.GetEndpoint()?.Metadata.GetMetadata<AGUIStreamOptions>()
                ?? context.RequestServices.GetService<IOptions<AGUIStreamOptions>>()?.Value;

+            RemoveReasoningMessages(input);


this will be disruptive to other clients, we should instead introduce additional options for the Map method, and that option could introduce a filtering callback for the messages. Then your code could provide that callback.

Makes sense , defaulting to drop reasoning messages for everyone is too heavy-handed. I'll put it behind options on MapAGUIServer instead:

public sealed class AGUIServerOptions { public Func<IEnumerable<AGUIMessage>, IEnumerable<AGUIMessage>>? MessageFilter { get; set; } }

The endpoint runs options.MessageFilter (identity when it's unset) before ToChatRequestContext, and the reasoning-message filter ships as an opt-in callback people can pass in.

One thing I want your call on for the default path. With no filter configured, a follow-up turn that carries a reasoning message still hits Unknown chat role: reasoning and 500s which is the original #8462 report. Two ways to go:

Keep it throwing, so filtering stays purely opt-in.

Teach the converter to handle the reasoning role itself (map it to a reasoning content part, or just skip it), so the 500 goes away no matter what options are set.

Either way I'll add the endpoint-level test Copilot asked for, hitting this through MapAGUIServer rather than the helper directly.

westey (@westey-m) what would you think here about either:

having a set of default options for copilot/AGUI SDK, etc...

having a set of overloads MapAGUIForCopilot....

To make it easier to nudge people to use the correct default configuration?

My preference is the second one a dedicated MapAGUIForCopilot-style overload over changing or loading defaults on the general Map path , It would keep the general Map path unopinionated and non-breaking for other AG-UI clients also It makes the Copilot-specific behavior (dropping reasoning history on follow-up turns) explicit and discoverable right at the call site, instead of buried in a default that people have to know to override.

Thank you for the additional information.

I'd also like westey (@westey-m) input here

.NET: Fix AG-UI "Unknown chat role: reasoning" on follow-up turns (mi…

a107a61

…crosoft#8462)

Copilot AI balanced review requested due to automatic review settings September 17, 2026 13:44

Atharva Vichare (atty57) deployed to github-app-auth September 17, 2026 13:44 — with GitHub Actions Active

agent-framework-automation Bot added the .NET Usage: [Issues, PRs], Target: .Net label Sep 17, 2026

Copilot started reviewing on behalf of Atharva Vichare (atty57) September 17, 2026 13:44 View session

Atharva Vichare (atty57) deployed to github-app-auth September 17, 2026 13:45 — with GitHub Actions Active

Copilot AI reviewed Sep 17, 2026

View reviewed changes

Comment thread dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/AGUIEndpointRouteBuilderExtensions.cs

Merge branch 'main' into fix/agui-reasoning-role-8462

1a1a255

Atharva Vichare (atty57) deployed to github-app-auth September 29, 2026 17:22 — with GitHub Actions Active

Merge branch 'main' into fix/agui-reasoning-role-8462

b4c24f6

Atharva Vichare (atty57) deployed to github-app-auth October 7, 2026 21:01 — with GitHub Actions Active

Atharva Vichare (atty57) marked this pull request as ready for review October 7, 2026 21:01

Atharva Vichare (atty57) requested review from SergeyMenshykh, Vincent Biret (baywet), Eduard van Valkenburg (eavanvalkenburg), Evan Mattson (moonbox3), Peter Ibekwe (peibekwe), Roger Barreto (rogerbarreto) and westey (westey-m) as code owners October 7, 2026 21:01

Atharva Vichare (atty57) deployed to github-app-auth October 7, 2026 21:02 — with GitHub Actions Active

Vincent Biret (baywet) requested a balanced review from Copilot October 8, 2026 12:12

Atharva Vichare (atty57) deployed to integration October 8, 2026 12:12 — with GitHub Actions Active

Copilot started reviewing on behalf of Vincent Biret (baywet) October 8, 2026 12:13 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Vincent Biret (baywet) requested changes Oct 8, 2026

View reviewed changes

Navigation Menu

Repository navigation

.NET: Fix AG-UI "Unknown chat role: reasoning" on follow-up turns - #8465

.NET: Fix AG-UI "Unknown chat role: reasoning" on follow-up turns#8465
Atharva Vichare (atty57) wants to merge 3 commits into
microsoft:mainfrom
atty57:fix/agui-reasoning-role-8462

Atharva Vichare (atty57) commented Sep 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Vincent Biret (baywet) Oct 8, 2026

Uh oh!

Atharva Vichare (atty57) Oct 8, 2026

Uh oh!

Vincent Biret (baywet) Oct 8, 2026

Uh oh!

Atharva Vichare (atty57) Oct 8, 2026

Uh oh!

Vincent Biret (baywet) Oct 8, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Atharva Vichare (atty57) commented Sep 17, 2026

Motivation & Context

Description & Review Guide

Related Issue

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Vincent Biret (baywet) Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Atharva Vichare (atty57) Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Vincent Biret (baywet) Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Atharva Vichare (atty57) Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Vincent Biret (baywet) Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants