ag-ui-protocol / ag-ui-protocol/ag-ui

[Feature]: Add a typed .NET helper for AG-UI thread/run continuation

Offen
#2,453 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Python
Sterne
15.9k
Forks
1.4k
Ø Merge
1 T. 17 Std.
Gemergte PRs (30 T.)
163

Beschreibung

## Pre-flight Checklist

- [x] I have searched existing issues and this hasn't been requested yet.

## Problem or Motivation

In the .NET AG-UI client, continuing a multi-turn protocol thread currently requires callers to manually:

1. inspect each `ChatResponseUpdate.RawRepresentation` for a `RunStartedEvent`;
2. retain its `ThreadId` and `RunId`;
3. create the next turn's `ChatOptions.RawRepresentationFactory`; and
4. return a `RunAgentInput` containing the retained `ThreadId` and the previous `RunId` as `ParentRunId`.

This is the correct semantic model, but it is easy to get wrong and currently requires protocol-specific boilerplate in every consumer.

The distinction from MEAI conversation state is important: an AG-UI `threadId` does not imply service-managed chat history and therefore should not be mapped to `ChatResponseUpdate.ConversationId`. That behavior and the supported manual continuation pattern were clarified in microsoft/agent-framework#7629.

The same manual pattern is now present in both the Microsoft Agent Framework AG-UI client sample and its session-persistence integration tests:

- https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/05-end-to-end/AGUIClientServer/AGUIClient/Program.cs
- https://github.com/microsoft/agent-framework/blob/main/dotnet/tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/SessionPersistenceTests.cs

## Proposed Solution

Add a small typed continuation abstraction to the .NET AG-UI client surface, tentatively something such as `AGUIContinuationState`, that can:

- capture `ThreadId` and `RunId` from a `RunStartedEvent` surfaced through a `ChatResponseUpdate`;
- retain the latest run ID as the parent run ID for the next request; and
- apply that protocol-specific continuation state to `ChatOptions` / `RawRepresentationFactory`.

The exact API shape is open for discussion. For example, the helper might expose operations conceptually similar to:

```csharp
continuation.TryUpdate(update);
ChatOptions nextOptions = continuation.ApplyTo(options);
```

The helper should live at the `Microsoft.Extensions.AI.ChatOptions` / `AGUI.Client` layer rather than return a Microsoft Agent Framework-specific `ChatClientAgentRunOptions`.

It should also compose safely with an existing `RawRepresentationFactory`, preserving caller-supplied `RunAgentInput` fields such as tools, state, context, forwarded properties, resume data, and messages.

## Non-goals

- Do not map AG-UI `ThreadId` to MEAI `ConversationId`.
- Do not change local-versus-service-managed history semantics.
- Do not introduce a wire-protocol change.
- Do not make the helper depend on Microsoft Agent Framework types.

## Alternatives Considered

The current manual pattern is functional and should remain possible. However, repeating it in each caller makes it easier to accidentally map identifiers incorrectly, omit `ParentRunId`, or overwrite an existing `RawRepresentationFactory`.

A helper could instead be implemented only in Microsoft Agent Framework, but MAF now consumes the external `AGUI.*` .NET SDK as the protocol/client source of truth. A framework-neutral helper in `AGUI.Client` would also be usable by other MEAI consumers.

## Additional Context

Related:

- microsoft/agent-framework#7629
- microsoft/agent-framework#6653
- ag-ui-protocol/ag-ui#2148 (related `parentRunId` semantics for in-flight steering, but a different scenario)
- ag-ui-protocol/ag-ui#2151 (caller-supplied `RunAgentInput` forwarding, but not a continuation helper)

I'd be happy to implement this once the maintainers confirm the ownership and preferred API shape. @ag-ui-protocol/copilotkit, would this direction fit the .NET SDK surface, and may I take it on?

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.