agui-dotnet-shared-state

AG-UI .NET — shared state

Goal: keep a structured object (a form, a document, a plan, a recipe) in sync between the client and the agent — the client provides the current state, the agent updates it, and the new state streams back next to the assistant's text.

State travels on the wire inside RunAgentInput.State (inbound) and as StateSnapshotEvent / StateDeltaEvent (outbound). In Microsoft.Extensions.AI terms, inbound state rides on the request's raw representation and outbound state rides on a ChatResponseUpdate's raw representation.

Client: seed the state and read it back

Send the starting state with the request, and watch for snapshots in the response:

using System.Text.Json;
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

var initialState = JsonSerializer.SerializeToElement(new
{
    recipe = new { title = "", ingredients = Array.Empty<string>(), steps = Array.Empty<string>() }
});

var options = new ChatOptions
{
    RawRepresentationFactory = _ => new RunAgentInput { State = initialState },
};

var messages = new List<ChatMessage> { new(ChatRole.User, "Suggest an Italian pasta recipe") };

JsonElement? latestState = null;
await foreach (var update in client.GetStreamingResponseAsync(messages, options))
{
    if (update.RawRepresentation is StateSnapshotEvent snapshot)
    {
        latestState = snapshot.Snapshot;   // the full updated state object
    }
    Console.Write(update.Text);            // the assistant's summary streams as usual
}

State updates are content-less — they arrive on update.RawRepresentation, not as update.Text.

Server: read inbound state and emit the new state

Add a DelegatingChatClient to the pipeline that reads RunAgentInput.State, produces the new state, and yields it as a StateSnapshotEvent:

using System.Runtime.CompilerServices;
using System.Text.Json;
using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.Extensions.AI;

internal sealed class RecipeStateChatClient(IChatClient inner, JsonSerializerOptions jso)
    : DelegatingChatClient(inner)
{
    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        if (options?.TryGetRunAgentInput(out var input) is true
            && input!.State is { ValueKind: JsonValueKind.Object } incoming)
        {
            var newState = await BuildStateAsync(messages, incoming, ct);   // your logic / an LLM call

            yield return new ChatResponseUpdate
            {
                RawRepresentation = new StateSnapshotEvent
                {
                    Snapshot = JsonSerializer.SerializeToElement(newState, jso.GetTypeInfo(typeof(AgentState))),
                },
            };
        }

        await foreach (var update in base.GetStreamingResponseAsync(messages, options, ct))
        {
            yield return update;   // the assistant's text summary
        }
    }
}