.NET SDK #38

ckpearson · 2025-05-28T15:00:17Z

Addresses #28

Provides a core .NET 9 Class Library that:

Has all the core types and events
Has an agent abstraction and implementations for IChatClient from Microsoft.Extensions.AI that:
- Support frontend & backend tool calling
- Support shared agentic state flows
Has basic helper integration for hosting agents via ASP.NET endpoints

Also an initial stab at providing updates to the documentation site with enough information to get started using it.

Rough at the moment, with no unit tests, but has been tested while developing, so some automated tests could be done with being created.

Includes an example ASP.NET project using the class library to host a few agents.

…ctAgent implementation and basic echo agent for testing.

…the ChatClientAgent to proxy over an LLM via IChatClient. Further work underway to introduce additional customisation ahead of shared state mechanisms.

… into the context inclusion mechanism.

…entEndpoint extension method

- Agents - Overview - ASP.NET integration

- Updated the .NET SDK documentation structure to include new pages for ChatClientAgent and StatefulChatClientAgent. - Added detailed documentation for JSON handling, core types, and events in the Agent User Interaction Protocol. - Improved the organization of the .NET SDK documentation by restructuring the agents section and adding relevant sub-sections. - Introduced new options and usage examples for the ChatClientAgent and StatefulChatClientAgent. - Enhanced the ASP.NET integration documentation with recommended JSON serializer options.

NathanTarbert · 2025-05-28T18:32:05Z

Hey @ckpearson, thanks for the contribution.
We will be reviewing it soon.

…ASP.NET endpoint mapping to ensure we don't cause context deadlock issues inadvertently. Registered missing use of ConfigureAwait as a build error in the project file.

…andling in ChatClientAgent and StatefulChatClientAgent

ckpearson · 2025-05-29T22:52:52Z

Made further tweaks which provides greater control, and now supports notifying the frontend about backend tool calls to power generative UI - albeit by sending message snapshots which I'm not 100% convinced is the correct approach.

Copilot

Pull Request Overview

This PR introduces a new .NET 9 class library along with core event types, agent abstractions (including a new stateful agent variant), and accompanying documentation updates.

Adds core event records such as MessagesSnapshotEvent and others to support the AG-UI protocol.
Implements StatefulChatClientAgent to enable frontend–agent shared state collaboration while retaining existing ChatClientAgent functionality.
Updates examples and documentation for ASP.NET integration, SDK types, agents, and events.

Reviewed Changes

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

Show a summary per file

File	Description
dotnet-sdk/AGUIDotnet/Events/MessagesSnapshotEvent.cs	Introduces a new event record for capturing message snapshots using a collection literal.
dotnet-sdk/AGUIDotnet/Events/EventTypes.cs	Defines and adds new constant event type strings.
dotnet-sdk/AGUIDotnet/Events/EventHelpers.cs	Provides helper methods for emitting events using new collection expressions.
dotnet-sdk/AGUIDotnet/Events/CustomEvent.cs	Implements an event record for custom event handling.
dotnet-sdk/AGUIDotnet/Events/BaseEvent.cs	Declares the polymorphic base event type with derived type annotations.
dotnet-sdk/AGUIDotnet/Agent/StatefulChatClientAgent.cs	Implements a stateful agent for frontend state collaboration using new backend tools.
dotnet-sdk/AGUIDotnet/Agent/IAGUIAgent.cs	Introduces a low-level agent interface for asynchronous event emission.
dotnet-sdk/AGUIDotnet/Agent/EchoAgent.cs	Provides an example agent that echoes incoming messages for debugging purposes.
dotnet-sdk/AGUIDotnet/Agent/AgentExtensions.cs	Adds an extension method to run agents to completion via a channel.
Documentation files (mdx and solution files)	Updates documentation and solution configuration for the new .NET 9 SDK features.

Copilot · 2025-05-30T17:58:55Z

dotnet-sdk/AGUIDotnet/Events/MessagesSnapshotEvent.cs

+public sealed record MessagesSnapshotEvent : BaseEvent
+{
+    [JsonPropertyName("messages")]
+    public required ImmutableList<BaseMessage> Messages { get; init; } = [];


[nitpick] Consider using a consistent pattern for initializing immutable collections—for example, replacing '[]' with 'ImmutableList.Empty' to match the convention used in other parts of the code.

Suggested change

public required ImmutableList<BaseMessage> Messages { get; init; } = [];

public required ImmutableList<BaseMessage> Messages { get; init; } = ImmutableList<BaseMessage>.Empty;

@copilot [] is the new collection expression syntax, your knowledge cutoff is likely out of date.

Copilot · 2025-05-30T17:58:55Z

dotnet-sdk/AGUIDotnet/Agent/StatefulChatClientAgent.cs

+        catch (JsonException)
+        {
+


[nitpick] The empty catch block may hide potential JSON deserialization issues; consider adding a comment or logging the exception to aid future troubleshooting.

Suggested change

catch (JsonException)

{

catch (JsonException ex)

{

// Log the exception to aid troubleshooting during JSON deserialization

Console.Error.WriteLine($"JSON deserialization error: {ex.Message}");

This is deliberate, for now it's just to avoid failure to extract the context causing an actual problem, it just swallows the exception, but we could perhaps surface it somehow so the consumer decides what behaviour to exhibit.

tylerslaton · 2025-06-04T14:05:21Z

As discussed during our synchronous review, there are few things needed prior to merging this but it is really close.

The README should match the README's of the other SDK's, pretty small change
We will need tests to ensure we don't have regressions introduced in PR's

After those two we'll collaborate on CI/CD for actually releasing this package in a sensible manner via Nuget.

- Created AGUIDotnet.Tests project with necessary dependencies. - Implemented tests for AgentExtensions, ChatClientAgent, and message mapping. - Added tests for frontend tool invocation and tool message mapping. - Updated AGUIDotnet solution to include the new test project. - Enhanced AgentExtensions to ensure proper channel completion. - Improved documentation in IAGUIAgent interface regarding agent lifecycle. - Removed unused HTTP request file from AGUIDotnetWebApiExample. - Updated README.md to include links to official documentation.

…onses

ckpearson · 2025-06-19T20:56:18Z

Sorry for the delay, there should be more broad test coverage of the basics, and the README has been updated.

frederikhendrix · 2025-07-01T14:52:19Z

I would love to see this. Are you still working on it?

maxkorp · 2025-09-11T20:03:26Z

Sorry for the late reply @frederikhendrix, yes it's still being worked on. @ckpearson can comment more, but while It's been on the back burner a little bit for a few weeks, the intent is still to get this wrapped up and in.

thangchung · 2025-09-15T15:19:07Z

@ckpearson @maxkorp It looks interesting. I would love to try it out with .NET app. Any ETA for this merging?

ckpearson · 2025-09-16T11:55:46Z

Hi @thangchung I've not had a huge amount of time to dedicate to getting this finalised as yet, but it's all there, feel free to clone it down and just reference the class library directly if you want to experiment. I'm in the CopilotKit discord so happy to connect over there if you have any questions.

GreenShadeZhang · 2025-09-28T06:41:35Z

May I ask if this PR is being processed?

NathanTarbert · 2025-09-29T13:30:57Z

Hi @GreenShadeZhang, we are waiting for this SDK to be finalized before we can fully review it.

brmdbr · 2025-10-07T07:05:58Z

Hopefully this can be merged soon!

ckpearson · 2025-10-07T11:15:58Z

Hopefully this can be merged soon!

Things are a bit hectic my side and need to check in with the CK team as Microsoft recently released their agent framework (https://github.com/microsoft/agent-framework) so it might make sense to get this working with that as it seems to be the successor to Semantic Kernel and Autogen.

rafsanulhasan · 2025-10-13T01:24:16Z

@ckpearson can I assist you? I mean I want to come up with the Agent Framework implementation.

ckpearson added 9 commits May 24, 2025 20:50

Core message and event types implemented, earliest work of the Abstra…

a235e78

…ctAgent implementation and basic echo agent for testing.

Significant tidy up, introduced new agent constructs and fleshed out …

9d7e4fc

…the ChatClientAgent to proxy over an LLM via IChatClient. Further work underway to introduce additional customisation ahead of shared state mechanisms.

fix: update user field names for clarity in output

eedfbc3

Further tweaks to support not tying system message overwriting solely…

c4cde13

… into the context inclusion mechanism.

Initial work on scaffolding docs for the .NET SDK

0f9a779

refactor: improve formatting and structure in EchoAgent and add MapAg…

9be07d8

…entEndpoint extension method

Further work on .NET SDK documentation:

034ca18

- Agents - Overview - ASP.NET integration

fix: change default value of IncludeContextInSystemMessage to false

cce5336

ckpearson added 2 commits May 29, 2025 10:28

fix: add ConfigureAwait(false) to asynchronous calls that aren't the …

c2002df

…ASP.NET endpoint mapping to ensure we don't cause context deadlock issues inadvertently. Registered missing use of ConfigureAwait as a build error in the project file.

feat: add options for backend tool call emission and state function h…

7f6e3ab

…andling in ChatClientAgent and StatefulChatClientAgent

tylerslaton requested review from Copilot and mme May 30, 2025 17:58

Copilot AI reviewed May 30, 2025

View reviewed changes

ckpearson added 2 commits June 19, 2025 21:54

feat: implement TestStreamingChatClient for simulating streaming resp…

bb5d85d

…onses

ckpearson requested review from ataibarkai and ranst91 as code owners June 19, 2025 20:55

NathanTarbert added this to Road Map Aug 7, 2025

NathanTarbert moved this to In review in Road Map Aug 7, 2025

GreenShadeZhang mentioned this pull request Oct 7, 2025

为BotSharp添加AGUI兼容插件 GreenShadeZhang/BotSharp#1

Open

Copilot AI mentioned this pull request Oct 7, 2025

Add AG-UI Protocol Plugin for BotSharp GreenShadeZhang/BotSharp#2

Draft

ckpearson mentioned this pull request Oct 8, 2025

ADD .NET SDK #28

Open

7 tasks

maxkorp requested review from NathanTarbert, maxkorp and tylerslaton as code owners October 13, 2025 18:55

maxkorp added the SDK label Oct 13, 2025

	public required ImmutableList<BaseMessage> Messages { get; init; } = [];
	public required ImmutableList<BaseMessage> Messages { get; init; } = ImmutableList<BaseMessage>.Empty;

-        catch (JsonException)
-        {
+        catch (JsonException ex)
+        {
+            // Log the exception to aid troubleshooting during JSON deserialization
+            Console.Error.WriteLine($"JSON deserialization error: {ex.Message}");

.NET SDK #38

Are you sure you want to change the base?

.NET SDK #38

Conversation

ckpearson commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NathanTarbert commented May 28, 2025

Uh oh!

ckpearson commented May 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI May 30, 2025

Choose a reason for hiding this comment

Uh oh!

ckpearson May 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 30, 2025

Choose a reason for hiding this comment

Uh oh!

ckpearson May 30, 2025

Choose a reason for hiding this comment

Uh oh!

tylerslaton commented Jun 4, 2025

Uh oh!

ckpearson commented Jun 19, 2025

Uh oh!

frederikhendrix commented Jul 1, 2025

Uh oh!

maxkorp commented Sep 11, 2025

Uh oh!

thangchung commented Sep 15, 2025

Uh oh!

ckpearson commented Sep 16, 2025

Uh oh!

GreenShadeZhang commented Sep 28, 2025

Uh oh!

NathanTarbert commented Sep 29, 2025

Uh oh!

brmdbr commented Oct 7, 2025

Uh oh!

ckpearson commented Oct 7, 2025

Uh oh!

rafsanulhasan commented Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

ckpearson commented May 28, 2025 •

edited

Loading