跳到主要内容

AGUIChatClient

消费 AG-UI 端点的 IChatClient 实现。

AGUIChatClient

AGUIChatClient 是 AG-UI 的 IChatClient 实现。它把 ChatMessage 与 ChatOptions 转换为 RunAgentInput,发送到 AG-UI 端点,再把返回的事件流转换为 ChatResponseUpdate。

using AGUI.Client;
using Microsoft.Extensions.AI;

.NET 客户端不提供 AbstractAgent 的对应物,集成点是 Microsoft.Extensions.AI.IChatClient。

构造

从 AGUIChatClientOptions 创建客户端。最简单的形式用 HttpClient 与端点 URL 构建内置 HTTP 传输:

using AGUI.Client;
using Microsoft.Extensions.AI;

HttpClient httpClient = new();
IChatClient client = new AGUIChatClient(new(httpClient, "https://api.example.com/agent"));

AGUIChatClient 只有一个构造函数,接收 AGUIChatClientOptions:

new AGUIChatClient(AGUIChatClientOptions options);
public sealed class AGUIChatClientOptions
{
    public AGUIChatClientOptions();
    public AGUIChatClientOptions(HttpClient httpClient, string endpoint); // 构建 HTTP 传输
    public required IAGUITransport Transport { get; init; }
    public JsonSerializerOptions? JsonSerializerOptions { get; init; }
}

测试或其它线路协议需要自定义传输时,直接设置 Transport。配置的 JsonSerializerOptions 也用于转换 MEAI 消息内容,包括 AIContent.AdditionalProperties 中的自定义 CLR 值。

流式响应

GetStreamingResponseAsync 把 AG-UI 输出流式呈现为 MEAI 的 ChatResponseUpdate:

using AGUI.Client;
using Microsoft.Extensions.AI;

using HttpClient httpClient = new();
IChatClient client = new AGUIChatClient(new(httpClient, "https://api.example.com/agent"));

List<ChatMessage> messages =
[
    new(ChatRole.User, "用一段话解释 AG-UI"),
];

await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync(
    messages,
    options: null,
    cancellationToken: CancellationToken.None))
{
    if (!string.IsNullOrEmpty(update.Text))
    {
        Console.Write(update.Text);
    }
}

内部把 AG-UI 事件流转换回 ChatResponseUpdate:文本事件变成文本增量,工具调用事件变成 MEAI 工具调用内容,生命周期事件可通过 RawRepresentation 获取。

非流式响应

GetResponseAsync 同样实现,它消费流式响应并返回最终的 ChatResponse:

ChatResponse response = await client.GetResponseAsync(
    messages,
    cancellationToken: CancellationToken.None);

Console.WriteLine(response.Text);

无状态与 ConversationId

AGUIChatClient 是无状态的:每轮发送完整消息历史,且从不在返回的更新上暴露 ConversationId。

这是有意的。在 Microsoft.Extensions.AI 中,非空的 ConversationId 表示由服务管理的会话,智能体包装层可能在下一轮只发送新增消息——面对无状态的 AG-UI 服务端,这会截断历史。

请改用这些标识符:

  • ChatResponseUpdate.ResponseId 是 AG-UI 的运行 id
  • update.RawRepresentation as RunStartedEvent 暴露 RUN_STARTED 中的 ThreadId 与 RunId
  • update.AdditionalProperties["agui_thread_id"] 同样包含解析出的 AG-UI 线程 id
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

static (string? ThreadId, string? RunId) GetAGUIIds(
    IEnumerable<ChatResponseUpdate> updates)
{
    RunStartedEvent? started = updates
        .Select(update => update.RawRepresentation)
        .OfType<RunStartedEvent>()
        .FirstOrDefault();

    return (started?.ThreadId, started?.RunId);
}

警告: 不要把 ConversationId 当作 AG-UI 会话状态。每轮传完整消息历史,用 AG-UI 的线程/运行 id 做线路级关联。

线程连续性

要维持稳定的 AG-UI 线程,跨轮复用同一个 ChatOptions 实例。客户端会把解析出的线程 id 固定到该选项实例上,而不设置 ConversationId。

需要显式续接或分支时,通过 ChatOptions.RawRepresentationFactory 设置 RunAgentInput.ThreadId 与 RunAgentInput.ParentRunId——这是控制线路字段的 AG-UI 原生方式:

using AGUI.Abstractions;
using Microsoft.Extensions.AI;

List<ChatResponseUpdate> firstTurn = [];
await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync(
    [new ChatMessage(ChatRole.User, "你好,介绍一下序列化")],
    cancellationToken: CancellationToken.None))
{
    firstTurn.Add(update);
    Console.Write(update.Text);
}

RunStartedEvent? runStarted = firstTurn
    .Select(update => update.RawRepresentation)
    .OfType<RunStartedEvent>()
    .FirstOrDefault();

ChatOptions followUpOptions = new()
{
    RawRepresentationFactory = _ => new RunAgentInput
    {
        ThreadId = runStarted?.ThreadId ?? string.Empty,
        ParentRunId = runStarted?.RunId,
    },
};

await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync(
    [new ChatMessage(ChatRole.User, "再讲讲事件压缩")],
    followUpOptions,
    CancellationToken.None))
{
    Console.Write(update.Text);
}

提示: 想让下一个请求从上次运行分支时用 ParentRunId;只需在同一线程继续时省略它。

中断与审批

当 AG-UI 服务端以中断结果结束运行时,客户端把暂停呈现为 MEAI 内容:

  • 工具调用审批变成 ToolApprovalRequestContent
  • 其它中断变成 InterruptRequestContent

调用方追加一条响应消息并发送下一个请求。客户端从最新消息中提取 ToolApprovalResponseContent 与 InterruptResponseContent,作为 RunAgentInput.Resume 发出。

using AGUI.Abstractions;
using Microsoft.Extensions.AI;

List<ChatMessage> messages =
[
    new(ChatRole.User, "删除生成的文件"),
];

ChatResponse firstResponse = await client.GetResponseAsync(
    messages,
    cancellationToken: CancellationToken.None);

ToolApprovalRequestContent? approval = firstResponse.Messages
    .SelectMany(message => message.Contents)
    .OfType<ToolApprovalRequestContent>()
    .FirstOrDefault();

if (approval?.ToolCall is FunctionCallContent toolCall)
{
    messages.AddRange(firstResponse.Messages);
    messages.Add(new ChatMessage(ChatRole.User,
    [
        new ToolApprovalResponseContent(approval.RequestId, approved: true, toolCall),
    ]));

    ChatResponse resumed = await client.GetResponseAsync(
        messages,
        cancellationToken: CancellationToken.None);

    Console.WriteLine(resumed.Text);
}

非工具中断用 InterruptResponseContent 响应:

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

static ChatMessage CreateInterruptResponse(InterruptRequestContent request)
{
    using JsonDocument payload = JsonDocument.Parse("""{"approved":true}""");

    return new ChatMessage(ChatRole.User,
    [
        new InterruptResponseContent(request.RequestId)
        {
            Payload = payload.RootElement.Clone(),
        },
    ]);
}

InterruptResponseContent.Metadata 可选地携带关于响应的信封数据——证明决定未被篡改的签名、路由键——与 Payload(智能体所问的答案)不同。客户端把它复制到 resume 条目的 metadata,托管层再把它交回服务端管线;规则见 Metadata。

new InterruptResponseContent(request.RequestId)
{
    Payload = payload.RootElement.Clone(),
    Metadata = JsonDocument.Parse(
        """{"definitionId":"review-plan","key":"afterModel-review"}""")
        .RootElement.Clone(),
}

Type to search…

↑↓ navigate↵ selectEsc close