ag-ui-protocol / ag-ui-protocol/ag-ui
[Feature]: Add a typed .NET helper for AG-UI thread/run continuation
- Lenguaje dominante
- Python
- Estrellas
- 15.9k
- Forks
- 1.4k
- Merge medio
- 1 d 17 h
- PR fusionados (30 d)
- 163
Descripción
## 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?
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.