From a1af10d87056dbea4046ae80cd011f0365ff3775 Mon Sep 17 00:00:00 2001 From: Sam Julien Date: Thu, 16 Jul 2026 10:46:43 -0700 Subject: [PATCH 1/2] docs: add .NET SDK package and parity notes --- docs/sdk/dotnet/abstractions/overview.mdx | 34 ++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/sdk/dotnet/abstractions/overview.mdx b/docs/sdk/dotnet/abstractions/overview.mdx index 479d05304e..ebba8195ba 100644 --- a/docs/sdk/dotnet/abstractions/overview.mdx +++ b/docs/sdk/dotnet/abstractions/overview.mdx @@ -23,6 +23,39 @@ event stream and request payload. types are registered in the source-generated `AGUIJsonSerializerContext`. +## SDK packages + +The .NET SDK is split into small packages so protocol types, wire formats, +client code, and server code can be adopted independently. + +| Package | Use it for | +| --- | --- | +| `AGUI.Abstractions` | Protocol events, messages, tools, capabilities, interrupts, and JSON serialization. | +| `AGUI.Formatting` | Event-stream formatter abstractions and Server-Sent Events support. | +| `AGUI.Protobuf` | Protobuf event-stream formatting and binary protocol support. | +| `AGUI.Client` | HTTP client and `IChatClient` implementation for consuming AG-UI endpoints. | +| `AGUI.Server` | Framework-agnostic adapter from `ChatResponseUpdate` streams to AG-UI events. | + +## Wire formats and parity + +JSON over Server-Sent Events is the full-fidelity event stream. +`AGUI.Formatting` defines the event-stream formatter contract and SSE support. +`AGUI.Protobuf` adds binary event-stream formatting for the protocol subset +supported by the shared proto schema. + +Protocol parity starts in `AGUI.Abstractions`. When the TypeScript reference SDK +adds or changes a wire type, the matching .NET event, message, tool, or +capability type should update alongside `AGUIJsonSerializerContext` and the +compatibility fixtures. Public API tracking files should update whenever a +protocol change adds or changes .NET types. + +```bash +cd sdks/dotnet +dotnet test tests/AGUI.Abstractions.UnitTests/ +dotnet test tests/AGUI.Formatting.UnitTests/ +dotnet test tests/AGUI.Protobuf.UnitTests/ +``` + ## Types Core data structures that represent the building blocks of the protocol: @@ -87,4 +120,3 @@ Events power communication between agents and frontends: > Complete documentation of all event types in `AGUI.Abstractions` - From 00c429ae517b0fef8009e39319160a2ba437702c Mon Sep 17 00:00:00 2001 From: Sam Julien Date: Thu, 16 Jul 2026 10:46:43 -0700 Subject: [PATCH 2/2] docs: clarify .NET client and server verification --- docs/sdk/dotnet/client/overview.mdx | 19 +++++++++++++++++++ docs/sdk/dotnet/hosting/overview.mdx | 25 ++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/sdk/dotnet/client/overview.mdx b/docs/sdk/dotnet/client/overview.mdx index b1ad7875b5..62bd1467f3 100644 --- a/docs/sdk/dotnet/client/overview.mdx +++ b/docs/sdk/dotnet/client/overview.mdx @@ -80,3 +80,22 @@ event and as `AdditionalProperties["agui_thread_id"]`. For the protocol types carried over the wire, see the [.NET event reference](/sdk/dotnet/abstractions/events). + +## Client verification + +Client tests protect the conversion between `Microsoft.Extensions.AI` and +AG-UI. They verify that `ChatMessage` history becomes AG-UI messages, +`ChatOptions.Tools` becomes AG-UI tools, caller-supplied AG-UI context, +forwarded properties, and resume payloads are preserved, and `RUN_ERROR` +events become MEAI `ErrorContent` updates. + +They also protect the stateless conversation contract: thread and run +identifiers are preserved through AG-UI fields, returned updates clear +`ConversationId`, and server-side tool calls are marked informational so the +.NET client does not execute them locally. + +```bash +cd sdks/dotnet +dotnet test tests/AGUI.Client.UnitTests/ +dotnet test tests/AGUI.CrossLanguage.IntegrationTests/ +``` diff --git a/docs/sdk/dotnet/hosting/overview.mdx b/docs/sdk/dotnet/hosting/overview.mdx index e117189bb9..62744e5284 100644 --- a/docs/sdk/dotnet/hosting/overview.mdx +++ b/docs/sdk/dotnet/hosting/overview.mdx @@ -45,14 +45,37 @@ independent. The hosting layer handles the protocol details for you: - Converts `RunAgentInput.Messages` into `ChatMessage` values +- Translates `RunAgentInput.Resume` into MEAI approval and interrupt response + content - Installs client-declared tools on `ChatOptions` - Stores the original input under `ChatOptions.AdditionalProperties[AGUIConstants.RunAgentInputKey]` -- Emits `RUN_STARTED` and `RUN_FINISHED` +- Emits `RUN_STARTED` and terminal `RUN_FINISHED` outcomes - Maps text, reasoning, tool calls, tool results, state, raw events, and interrupts to AG-UI events - Streams the result as Server-Sent Events +## Verification and framework ownership + +Server tests verify that `RunAgentInput` becomes `ChatMessage` and +`ChatOptions`, resume payloads become standard MEAI response content, lifecycle +events are emitted, and streamed `ChatResponseUpdate` values become the +expected text, reasoning, tool, state, raw, custom, and interrupt events. Raw +AG-UI events, including `RUN_ERROR`, pass through when supplied on +`ChatResponseUpdate.RawRepresentation`. + +```bash +cd sdks/dotnet +dotnet test tests/AGUI.Server.UnitTests/ +dotnet test tests/AGUI.Hosting.AspNetCore.IntegrationTests/ +``` + +The SDK owns the shared AG-UI and `Microsoft.Extensions.AI` bridge. +Framework-specific mappings belong to the consuming framework. For example, +Microsoft Agent Framework can use `AGUI.Server` for the common bridge, then map +its own workflow, step, and agent events with `AGUIStreamOptions` or raw AG-UI +events. + ## Server and client together Use `AGUI.Server` when you are building an AG-UI server. Use