AG-UI .NET 应用可观测性实战:Step14_Telemetry 与 OpenTelemetry 全链路追踪
AG-UI .NET 应用可观测性实战:Step14_Telemetry 与 OpenTelemetry 全链路追踪
本指南围绕 AG-UI(Agent-User Interaction Protocol).NET SDK 的 Step14_Telemetry 示例展开,讲解如何在不改动协议的前提下,用 OpenTelemetry 为 AG-UI 服务端与前端客户端接入标准化追踪:涵盖 agui.run 运行跨度、客户端 execute_tool 跨度、GenAI 跨度以及 W3C traceparent 跨进程链路串联。阅读完本文,你将掌握 AG-UI 应用的可观测性接入方法、三种导出方式(Console / OTLP / dotnet-counters)以及人机协同(Human-in-the-Loop)场景下中断与恢复的追踪形态。
一、为什么 AG-UI 需要 OpenTelemetry
AG-UI 是一种将 Agent 引入前端应用的交互协议,一次完整交互往往跨越浏览器端、客户端进程与服务端进程,涉及模型调用、服务端工具执行、前端工具执行、中断与恢复等多个阶段。仅仅靠日志很难回答三个核心问题:
- 一次用户请求从客户端到服务端经历了哪些阶段?
- 模型究竟调用了哪些工具、工具在哪个进程执行、耗时多少?
- 当发生中断(interrupt)并恢复(resume)时,两段运行如何关联成一个完整故事?
Step14 示例给出的答案是:协议本身不需要任何改动,只需组合标准中间件并订阅三个 ActivitySource:
| ActivitySource | 产生的跨度 | 说明 |
|---|---|---|
Experimental.AGUI.Server |
agui.run |
服务端每次 run 一个跨度,携带 agui.thread_id、agui.run_id、agui.parent_run_id(恢复时)、agui.run.outcome、agui.events.count |
Experimental.AGUI.Client |
execute_tool |
AGUIChatClient 在前端进程内本地调用客户端工具的跨度 |
Experimental.Microsoft.Extensions.AI |
chat、execute_tool、orchestrate_tools |
由 UseOpenTelemetry() 产生的 GenAI 跨度,嵌套在 agui.run 之下 |
服务端同时启用 ASP.NET Core 插桩,客户端启用 HttpClient 插桩,于是 W3C traceparent 请求头沿请求链路传递,客户端与服务端合为同一条 trace。
二、运行示例:零外部依赖体验追踪
Step14 由两个工程组成:Step14_Telemetry.Server 与 Step14_Telemetry.Client,位于 sdks/dotnet/samples/GettingStarted/Step14_Telemetry 目录下。默认情况下两个进程都把跨度打印到各自的控制台,无需任何外部依赖。
# 终端 1 — 服务端(http://localhost:5014)
dotnet run --project Step14_Telemetry.Server
# 终端 2 — 客户端
dotnet run --project Step14_Telemetry.Client
服务端监听端口由 launchSettings.json 固定为 http://localhost:5014。客户端通过命令行参数覆盖服务端地址(默认即为 http://localhost:5014):
var baseUrl = args.Length > 0 ? args[0] : "http://localhost:5014";
客户端会依次发起三个问题:询问天气(触发服务端后端工具 get_weather)、询问附近可玩项目(同时触发后端工具与前端工具)、删除文件(触发需审批的工具,产生中断)。运行后观察两个控制台,跨度会随请求实时出现。
离线确定性模型的设计
服务端没有真实 LLM,而是使用 FakeChatClient.cs 中的确定性模型:它根据用户消息关键词返回工具调用指令——包含 "near me" 时同时调用 get_weather 与 get_user_location,包含 "delete" 时调用 delete_file,其余情况调用 get_weather;一旦消息流中出现 FunctionResultContent(工具已执行),则生成最终文本回复。这种设计让示例完全离线可运行,同时能稳定复现三类有代表性的跨度树。
三、服务端配置:run 跨度与 GenAI 跨度
服务端 Program.cs 展示了完整的 AG-UI + OpenTelemetry 装配流程。
3.1 AG-UI 服务与模型管线
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUI();
// 后端工具在服务端执行
var getWeather = AIFunctionFactory.Create(GetWeather, "get_weather", "Gets the current weather for a city.");
// ApprovalRequiredAIFunction 让 run 暂停等待人工审批(HITL 场景)
var deleteFile = new ApprovalRequiredAIFunction(
AIFunctionFactory.Create((string path) => $"deleted {path}", "delete_file", "Deletes a file."));
builder.Services.AddSingleton<FakeChatClient>();
builder.Services.AddChatClient(sp => sp.GetRequiredService<FakeChatClient>())
.ConfigureOptions(o =>
{
o.Tools ??= [];
o.Tools.Add(getWeather);
o.Tools.Add(deleteFile);
})
.UseFunctionInvocation(configure: fic => fic.TerminateOnUnknownCalls = true)
.UseOpenTelemetry();
要点:
AddAGUI()注册 AG-UI 服务端核心;- 两个后端工具通过
AIFunctionFactory.Create创建,其中delete_file被ApprovalRequiredAIFunction包装,从而在调用时暂停 run 等待人工审批,这正是人机协同场景的来源; .UseOpenTelemetry()为Microsoft.Extensions.AI管线启用 GenAI 遥测,产生chat、execute_tool、orchestrate_tools等跨度。
3.2 OpenTelemetry 追踪装配
var useOtlp = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT"));
builder.Services.AddOpenTelemetry()
.ConfigureResource(resource => resource.AddService("agui-telemetry-server"))
.WithTracing(tracing =>
{
tracing
.AddSource(AGUIServerInstrumentation.ActivitySourceName)
.AddSource("Experimental.Microsoft.Extensions.AI")
.AddAspNetCoreInstrumentation();
if (useOtlp)
{
tracing.AddOtlpExporter();
}
else
{
tracing.AddConsoleExporter();
}
});
var app = builder.Build();
app.MapAGUI("/");
app.Run();
配置逻辑清晰可复用:
- 订阅源(AddSource):
AGUIServerInstrumentation.ActivitySourceName(即Experimental.AGUI.Server)负责agui.run跨度;Experimental.Microsoft.Extensions.AI负责 GenAI 跨度;AddAspNetCoreInstrumentation()负责 ASP.NET Core 请求跨度。 - 导出器切换:是否设置环境变量
OTEL_EXPORTER_OTLP_ENDPOINT决定走 OTLP 导出器还是控制台导出器——这正是后续"发送到无头后端"的基础。 - 服务标识:通过
ConfigureResource将服务命名为agui-telemetry-server,便于在追踪后端中区分进程。
对应工程文件 Step14_Telemetry.Server.csproj 引用了 OpenTelemetry.Extensions.Hosting、OpenTelemetry.Instrumentation.AspNetCore、OpenTelemetry.Exporter.Console 与 OpenTelemetry.Exporter.OpenTelemetryProtocol 等包。
3.3 run 跨度的源码级细节
agui.run 跨度由 AGUIServerInstrumentation.cs 定义,其 ActivitySourceName 常量为 Experimental.AGUI.Server。跨度属性由 ChatResponseUpdateAGUIExtensions.cs 写入,核心行为有两个值得注意的点:
- 零开销设计:只有当存在订阅者监听该 ActivitySource 时(
ActivitySource.HasListeners()),才会启动agui.run跨度;否则完全不产生追踪开销。这意味着生产环境不配置遥测时,AG-UI 服务不会因这段代码付出额外成本。 - 标签体系:跨度启动时设置
agui.thread_id、agui.run_id,若存在父 run(恢复场景)则额外设置agui.parent_run_id;结束时根据执行结果写入agui.run.outcome(取值为success/interrupt/error/canceled)与agui.events.count(本次 run 产生的事件数量)。
这些标签构成 AG-UI 运行时的统一查询维度,配合追踪后端即可按会话(thread)、运行(run)、结果类型与事件量进行筛选。
四、客户端配置:本地工具跨度与跨进程链路
客户端 Program.cs 展示了对称的追踪装配:
internal static readonly ActivitySource ActivitySource = new("Step14.Telemetry.Client");
var useOtlp = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT"));
var tracing = Sdk.CreateTracerProviderBuilder()
.ConfigureResource(resource => resource.AddService("agui-telemetry-client"))
.AddSource(ActivitySource.Name)
.AddSource("Experimental.AGUI.Client")
.AddSource("Experimental.Microsoft.Extensions.AI")
.AddHttpClientInstrumentation();
tracing = useOtlp ? tracing.AddOtlpExporter() : tracing.AddConsoleExporter();
using var tracerProvider = tracing.Build();
using var httpClient = new HttpClient { BaseAddress = new Uri(baseUrl) };
// 为 AG-UI 客户端包裹 UseOpenTelemetry,使客户端侧也发出 GenAI chat 跨度(出站 HTTP 请求的父跨度),与服务端对称
IChatClient aguiClient = new AGUIChatClient(new(httpClient, baseUrl))
.AsBuilder()
.UseOpenTelemetry()
.Build();
// 一个客户端 activity 覆盖整个对话,使客户端 HTTP 跨度与服务端 run 跨度共享同一条 trace
using var conversation = ActivitySource.StartActivity("agent conversation");
await SampleClient.RunAsync(aguiClient, Console.Out).ConfigureAwait(false);
这里有几个关键设计:
- 客户端自定义 ActivitySource:
Step14.Telemetry.Client用于包裹"agent conversation"对话级跨度,它是整个 trace 的根。示例代码还用它标记三个独立场景(scenario: backend tool、scenario: mixed tools、scenario: human-in-the-loop),让每个场景的跨度树边界清晰可辨。 - 客户端工具跨度源:
Experimental.AGUI.Client由 AGUIClientInstrumentation.cs 定义,AGUIChatClient在前端进程内本地调用工具(frontend tool)时会发出execute_tool跨度。 - 链路串联原理:客户端用
UseOpenTelemetry()包裹AGUIChatClient,产生客户端 GenAIchat跨度作为出站 HTTP 请求的父跨度;HttpClient 插桩把 W3Ctraceparent头带到服务端,服务端 ASP.NET 插桩继续该 trace,于是"agent conversation"下层层嵌套到服务端agui.run,两端合并为一条完整的 trace。
客户端工程文件 Step14_Telemetry.Client.csproj 引用了 OpenTelemetry、OpenTelemetry.Instrumentation.Http、OpenTelemetry.Exporter.Console 与 OpenTelemetry.Exporter.OpenTelemetryProtocol。
前端工具与后端工具在跨度树中的位置
SampleClient.cs 展示了三种调用形态,正好对应三种跨度形态:
- 后端工具:
get_weather在服务端执行,其execute_tool跨度出现在服务端agui.run之下; - 混合工具:通过
ChatOptions { Tools = [location] }注册前端工具get_user_location,模型同时调用后端工具与前端工具,execute_tool跨度分别出现在服务端与客户端进程,但共享同一条 trace; - 人机协同:
delete_file被审批门控,首次调用产生ToolApprovalRequestContent,客户端捕获后模拟人工批准(approval.CreateResponse(approved: true))并恢复对话。
五、把追踪发送到无头后端
控制台导出器适合本地验证,生产环境则需要把跨度发送到集中式后端。Step14 的切换方式非常统一:在两个进程都设置 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量,即可从控制台导出器切换到 OTLP 导出器。任何兼容 OTLP 的后端都可以对接。
5.1 Aspire Dashboard
Aspire Dashboard 提供 Web UI 与 OTLP 端点,最省事的启动方式:
npx -y @microsoft/aspire-cli dashboard run # 或使用 mcr.microsoft.com/dotnet/aspire-dashboard 镜像
- Dashboard UI 端口:
:18888 - OTLP 接收端口:
:4317
随后在两个终端分别设置环境变量并重新运行(PowerShell 语法):
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4317"
注意两端导出目标要一致,否则服务端与客户端的 trace 无法在同一后端中聚合。
5.2 OpenTelemetry Collector
使用带 debug exporter 的 OpenTelemetry Collector 时,收到底的跨度会打印到 Collector 的标准输出。只需把 OTEL_EXPORTER_OTLP_ENDPOINT 指向 Collector 的 OTLP 端口即可,适合在无 UI 的容器或 CI 环境中做管道验证。
5.3 dotnet-counters 实时指标
Experimental.Microsoft.Extensions.AI 不仅产生跨度,还暴露 GenAI 指标(meter)。用 dotnet-counters 可以实时观察服务端的模型调用指标:
dotnet-counters monitor -n Step14_Telemetry.Server --counters Experimental.Microsoft.Extensions.AI
-n 参数指定进程名,--counters 指定要监控的指标提供者。
六、完整追踪形态解读
一次普通天气查询,客户端与服务端合起来形成如下的 trace:
agent conversation (client)
└─ chat (client GenAI span — 包裹整次往返)
└─ POST http://localhost:5014/ (client HttpClient span) ── traceparent ──▶
└─ POST / (server ASP.NET request)
└─ agui.run {agui.thread_id, agui.run_id, agui.run.outcome=success, agui.events.count}
└─ orchestrate_tools
├─ chat (gen_ai.operation.name=chat) — 模型请求工具
├─ execute_tool get_weather (gen_ai.tool.name=get_weather) — 工具在服务端执行
└─ chat (gen_ai.operation.name=chat) — 模型作答
可以按层次读出完整业务语义:
- 最外层
agent conversation标识一次完整对话; - 客户端
chat跨度包裹 HTTP 往返,traceparent头沿请求传递; - 服务端
agui.run携带agui.thread_id、agui.run_id、agui.run.outcome=success与agui.events.count,标识一次 AG-UI 运行; orchestrate_tools之下的两个chat与一个execute_tool get_weather分别对应"模型请求工具 → 工具在服务端执行 → 模型作答"的完整闭环。
七、人机协同场景:中断与恢复如何呈现
对于 Human-in-the-Loop 流程,AG-UI 的中断与恢复体现为两次独立的 run,追踪上同样有明确的标识:
- 恢复(resume)的
agui.run携带agui.parent_run_id,指向第一次 run(即被中断的那次); - 当客户端在同一个 activity 下驱动两轮对话时(示例中
scenario: human-in-the-loop正是这样:先收集首次响应,捕获ToolApprovalRequestContent,模拟批准后再流式恢复),两次 run 共享同一条 trace。
因此,无论中断发生在服务端审批、还是等待用户输入,其恢复流程都会与首次 run 渲染在同一张 trace 图上,便于直接观察"暂停点 → 人工决策 → 继续执行"的完整时间线。若需要将父 run 信息用于关联查询,直接使用 agui.parent_run_id 标签即可。
八、小结与延伸阅读
Step14_Telemetry 展示了一条清晰的 AG-UI 可观测性接入路径:不修改协议,通过订阅 Experimental.AGUI.Server、Experimental.AGUI.Client 与 Experimental.Microsoft.Extensions.AI 三个 ActivitySource,配合 ASP.NET Core 与 HttpClient 标准插桩,即可获得覆盖客户端与服务端的单条 trace,并借助 OTLP 导出到 Aspire Dashboard、Collector 等后端,用 dotnet-counters 观测实时指标。agui.run 的标签体系(thread、run、parent_run、outcome、events count)为按会话维度的查询与排障提供了统一的元数据基础。
相关资源可继续深入:
- 示例完整源码:Step14_Telemetry 目录
- 服务端插桩实现:AGUIServerInstrumentation.cs、ChatResponseUpdateAGUIExtensions.cs
- 客户端插桩实现:AGUIClientInstrumentation.cs
- 本教程的上一阶段(协议层能力):Step13_Protobuf,了解 AG-UI 的 Protobuf 编码能力