AG-UI .NET 故障排查指南:从症状定位根因到修复验证的完整实践

原创2026-09-21 11:30:231,972 阅读
文章标签:人工智能AI AgentAgent 框架API设计后端前端MCP 服务AI 技能

AG-UI .NET 故障排查指南:从症状定位根因到修复验证的完整实践

本指南面向基于 AG-UI .NET SDK 构建的应用,系统梳理流式对话、工具调用、状态同步、中断恢复与传输层中最常见的故障症状,逐一给出根因解释、修复方案与验证方法。读完本文,你将掌握如何诊断“Agent 遗忘历史”“ConversationId 恒为空”“状态事件不抵达”“工具运行时报错”“未知工具中断运行”“406 Not Acceptable”以及“中断无法恢复”等问题,并学会用 curl 与 RawEvent 直接观察线上原始事件流。

背景:先理解 AG-UI .NET 的几个关键事实

在排查之前,先建立三个与故障直接相关的底层认知,它们全部有源码依据:

  • 服务端无状态:AG-UI 协议的服务端在轮次之间不保留任何状态,客户端必须在每一轮重发完整历史。这是 AGUIChatClient 设计的前提。
  • SDK 永不暴露服务端会话 ID:update.ConversationId 被刻意置空。原因在 AGUIChatClient.cs 的注释中有明确说明:若 ConversationId 非空,Microsoft.Extensions.AI(MEAI)的 agent 包装器会认为会话由服务端管理,下一轮只发送增量(delta),而这会截断无状态服务端所需的历史(issue #4869)。所以非空 ConversationId 反而会引入历史截断 bug。
  • 内容无关的更新会丢失:状态(state)、推理(reasoning)、生命周期(lifecycle)事件搭乘的是“无文本内容”的更新,只能通过 update.RawRepresentation(如 StateSnapshotEvent、RunStartedEvent、RawEvent)看到;非流式的 GetResponseAsync 聚合过程会丢弃这些不含消息内容的更新。

下面逐项展开八个典型故障场景。

一、Agent 遗忘早期轮次 / 历史被截断

症状:Agent 记不住几轮之前的对话内容,回答像“失忆”一样与上下文脱节。

根因:AG-UI 服务端无状态,不保存轮次间状态,客户端必须每轮重发完整历史。如果只发送最新一条消息,模型就失去了所有先前上下文。

修复:维护一个持续增长的 List<ChatMessage>,每轮把 assistant 的回复追加进去(history.AddMessages(updates.ToChatResponse())),然后把整个列表重新发送。对于需要保持同一会话的服务端,通过复用同一个 ChatOptions 实例来保持 thread id 稳定。

源码佐证:AGUIChatClient.cs 中,客户端在发送前会清理 ConversationId,并将其作为 AG-UI 的 thread id 写入 AdditionalProperties;而在 AGUIChatClient.cs 中,首次更新到达时会把解析出的 thread id “钉”回调用方的 ChatOptions.AdditionalProperties——这正是“复用同一 ChatOptions 即可保持稳定 thread id”的底层机制。

二、update.ConversationId 恒为 null

症状:无论怎么调用,更新上的 ConversationId 始终是 null,用它做会话追踪全部失效。

根因:这是设计行为,不是 bug。SDK 从不暴露服务端会话 ID。非空 ConversationId 会使 MEAI 包装器只发送增量,在无状态服务端面前截断历史(见前文背景)。

修复:不要用 ConversationId 追踪会话。改用 RUN_STARTED 事件里的 thread id(update.RawRepresentation as RunStartedEvent),或者直接复用同一个 ChatOptions 保持单一稳定线程。

源码佐证:客户端 handler 在 AGUIChatClient.cs 中,每当遇到 RunStartedEvent 就把 thread id 放入 update.AdditionalProperties;并在 AGUIChatClient.cs 处显式 update.ConversationId = null,确保下游 FunctionInvokingChatClient 始终发送完整历史。

三、状态、推理或生命周期更新永不抵达

症状:UI 上状态面板不动、推理过程不可见、RUN_STARTED / RUN_FINISHED 等生命周期事件缺失。

根因:这些更新是**无内容(content-less)**的——它们存在于 update.RawRepresentation(StateSnapshotEvent、RunStartedEvent、RawEvent 等)中,本身没有文本。非流式 GetResponseAsync 聚合会丢弃所有不含消息内容的更新。

修复:改用流式 API,在循环内检查 update.RawRepresentation / update.Contents,而不是聚合到单个 ChatResponse:

await foreach (var update in client.GetStreamingResponseAsync(messages, options))
{
    if (update.RawRepresentation is StateSnapshotEvent snapshot)
    {
        // 处理完整状态快照 snapshot.Snapshot
    }
}

源码佐证:AGUIChatClient.cs 显示 GetResponseAsync 本身就是把流式结果 ToChatResponseAsync 聚合而来,聚合自然丢掉无内容更新;而流式路径 AGUIChatClient.cs 逐条 yield return,保留全部事件。StateSnapshotEvent 携带完整的 Snapshot(AGUIEvents.g.cs),StateDeltaEvent 则携带 RFC 6902 增量补丁(AGUIEvents.g.cs)。

四、工具在运行时抛错或产生 AOT/trim 警告

症状:工具函数执行时报序列化异常,或在 Native AOT / trimming 构建下出现 “unable to resolve metadata” 类警告。

根因:参数或返回类型为非原始类型(复杂对象)的工具,需要**源生成的序列化(source-generated serialization)**支持;在 Native AOT 与 trimming 环境下,反射式 schema 解析与参数绑定会失败。

修复:把工具的参数类型与结果类型放入一个 JsonSerializerContext,注册到宿主上,并把上下文选项传给 AIFunctionFactory.Create:

// 1. 定义上下文(可放在 Program 文件或单独类中)
[JsonSerializable(typeof(MyToolArgs))]
[JsonSerializable(typeof(MyToolResult))]
internal partial class AppJsonSerializerContext : JsonSerializerContext { }

// 2. 注册到 ASP.NET Core 的 JSON 选项
builder.Services.ConfigureHttpJsonOptions(o =>
    o.SerializerOptions.TypeInfoResolverChain.Add(AppJsonSerializerContext.Default));

// 3. 创建 AIFunction 时传入上下文选项
var tool = AIFunctionFactory.Create(
    MyToolMethod,
    serializerOptions: AppJsonSerializerContext.Default.Options);

延伸建议:复杂工具类型的序列化元数据同样会影响客户端与服务端的 schema 传递,保持两端使用同一套 JsonSerializerOptions 可避免“schema 不一致导致参数绑定失败”的次级问题。

五、未知工具调用在运行中途报错

症状:客户端声明了一个服务端不拥有的工具,运行过程中服务端尝试执行它并抛错,整个 run 中断。

根因:服务端的函数调用客户端(FunctionInvokingChatClient)会尝试执行它看到的每一个工具调用;当调用属于客户端(前端)工具时,服务端没有实现,自然失败——除非明确告诉它“这个调用不属于我”。

修复:为服务端聊天客户端注册 .UseFunctionInvocation(fic => fic.TerminateOnUnknownCalls = true)。这样未知的(客户端)工具会干净地结束服务端轮次,并转发给客户端执行。

源码佐证:该配置在仓库中广泛使用——例如 Step01 服务端示例、Step03 前端工具示例以及 Step13 Protobuf 示例。集成测试 MixedToolInvocationIntegrationTest.cs 也验证了服务端与客户端工具混用时的正确转发行为。配套技能文档 agui-dotnet-client-tools 明确说明:服务端必须用 UseFunctionInvocation + TerminateOnUnknownCalls 把未知工具转发给客户端,而不是尝试本地执行。

六、端点返回 406 Not Acceptable

症状:POST 请求直接返回 406 Not Acceptable,流式对话无法建立。

根因:传输层是**内容协商(content-negotiated)**的。406 意味着请求的 Accept 头要求了服务端无法产出的格式——例如要求 protobuf 但服务端没有注册 protobuf formatter,或 Accept 中排除了 text/event-stream。

修复:让客户端接受服务端能够提供的格式:

  • SSE:允许 text/event-stream(或 */*);
  • protobuf:在服务端注册 ProtobufEventStreamFormatter,并在客户端的 AGUIEventStreamHandler 中列出该格式。

源码佐证:ProtobufEventStreamFormatter 的媒体类型常量是 application/vnd.ag-ui.event+proto(见 PublicAPI.Unshipped.txt)。服务端注册方式见 Step13 示例:builder.Services.AddSingleton<IAGUIEventStreamFormatter, ProtobufEventStreamFormatter>();客户端按 <a href="https://link.gitcode.com/i/0c743d8e6d0a3e68f71b291964f0b575" target="_blank">new ProtobufEventStreamFormatter(), new SseEventStreamFormatter()] 顺序配置([Step13 客户端),实现 protobuf 优先、SSE 兜底的协商。架构文档 architecture.md 也确认:negotiating endpoint 会检查请求 Accept 头,按已注册的 IAGUIEventStreamFormatter 决定编码方式。

七、中断(interrupt)或审批(approval)无法恢复

症状:运行因工具审批或输入中断而暂停,再次流式发送却无法恢复,或恢复后表现异常。

根因:恢复一个暂停的 run 需要请求与对应的响应同时出现在恢复的消息列表中,且共享同一个 id——SDK 靠配对关系重连到被暂停的调用。只发送响应而不带原始请求,就没有可配对的对象。

修复:两者都追加——在 assistant 消息上放 ToolApprovalRequestContent(或 InterruptRequestContent),在 user 消息上放对应的 CreateResponse(...) / InterruptResponseContent(requestId),然后重新流式发送。单独发送响应是无法恢复的。

源码佐证:客户端在 AGUIChatClient.cs 中会从最后一条消息提取 ToolApprovalResponseContent / InterruptResponseContent,并从消息列表中剥离审批/中断内容对,再经 AdditionalProperties 传入;BuildRunAgentInput 将其转换为 AGUIResume(携带 InterruptId 与 ResumeStatus.Resolved),随 input.Resume 发送给服务端。这印证了“请求 + 响应配对成 resume 载荷”的设计。

八、检查线上原始事件流(Wire 层观察)

当以上修复都不奏效时,直接看线上到底传了什么。

用 curl 查看 SSE 原始帧

curl -N -X POST http://localhost:5000/ \
  -H "Content-Type: application/json" -H "Accept: text/event-stream" \
  -d '{"threadId":"t1","runId":"r1","messages":[{"id":"m1","role":"user","content":"Hi"}]}'

健康 run 的事件序列大致为:RUN_STARTED → TEXT_MESSAGE_CONTENT → RUN_FINISHED;暂停的 run 以 RUN_FINISHED { outcome: interrupt } 结束;工具 run 会依次出现 TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT。

在代码中观察 RawEvent

遥测和自定义服务端事件会以 RawEvent 形式出现在更新上:

if (update.RawRepresentation is RawEvent { Source: var source, Event: var payload })
{
    Console.WriteLine($"[{source}] {payload.GetRawText()}");
}

源码佐证:RawEvent 定义于 AGUIEvents.g.cs,携带 Source(来源 provider/框架)与 Event(provider 原生事件,任意 JSON 值);它是协议为“协议未建模的应用自有事件”预留的扩展点。BaseEvent 上还有通用的 RawEvent 字段可供整体透传(BaseEvent.g.cs)。事件的反序列化分派逻辑见 BaseEventJsonConverter.cs。

九、修复后的验证方法

应用任何修复后,请按以下流程确认症状真正消失:

  1. 重放原始提示词:用同样的输入重新触发一次 run,不要更换消息内容;
  2. 对照 wire 流验证:基于第八节的观察方法,确认——
    • 历史问题:第二轮请求体中确实携带了第一轮的完整消息(包括 assistant 回复);
    • 状态问题:流式循环中 StateSnapshotEvent 已到达;
    • 406 问题:响应 Content-Type 已与协商的传输格式匹配(SSE 的 text/event-stream 或 protobuf 媒体类型)。

十、预防性清单(从源码与示例中提炼)

  • 历史:始终维护完整 List<ChatMessage> 并整表重发,复用同一 ChatOptions 保持 thread id 稳定;
  • 会话追踪:用 RUN_STARTED 事件的 thread id 或 ChatOptions.AdditionalProperties,绝不依赖 ConversationId;
  • 状态/生命周期:统一走 GetStreamingResponseAsync 流式路径,在循环内检查 RawRepresentation;
  • AOT:所有非原始类型的工具参数/结果都纳入 JsonSerializerContext 并透传到 AIFunctionFactory.Create;
  • 客户端工具:服务端保持 TerminateOnUnknownCalls = true,让客户端工具干净转发;
  • 传输:客户端 Accept 与服务端注册的 formatter 保持对齐(SSE 至少允许 text/event-stream);
  • 中断恢复:请求与响应成对发送,id 一致。

参考资源

登录后查看全文
ag-ui