AG-UI .NET 故障排查指南:从症状定位根因到修复验证的完整实践
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。
九、修复后的验证方法
应用任何修复后,请按以下流程确认症状真正消失:
- 重放原始提示词:用同样的输入重新触发一次 run,不要更换消息内容;
- 对照 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 一致。
参考资源
- 客户端核心实现:AGUIChatClient.cs
- 事件模型:AGUIEvents.g.cs
- 端到端示例(从入门到并行工具、Protobuf、原始事件、遥测):GettingStarted 示例目录
- 架构与设计说明:architecture.md
- 配套技能文档:agui-dotnet-server-tools、agui-dotnet-client-tools、agui-dotnet-protobuf