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

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

未關閉
#2,453 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
主要語言
Python
星號
15.9k
分支
1.4k
平均合併
1 天 17 小時
30 天內合併 PR
163

描述

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

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。