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

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

Đang mở
#2,453 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Python
Star
15.9k
Fork
1.4k
Merge trung bình
1 ngày 17 giờ
Pull request đã merge (30 ngày)
163

Mô tả

## 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?

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.