AG-UI .NET 应用可观测性实战:Step14_Telemetry 与 OpenTelemetry 全链路追踪

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

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 写入,核心行为有两个值得注意的点:

  1. 零开销设计:只有当存在订阅者监听该 ActivitySource 时(ActivitySource.HasListeners()),才会启动 agui.run 跨度;否则完全不产生追踪开销。这意味着生产环境不配置遥测时,AG-UI 服务不会因这段代码付出额外成本。
  2. 标签体系:跨度启动时设置 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,产生客户端 GenAI chat 跨度作为出站 HTTP 请求的父跨度;HttpClient 插桩把 W3C traceparent 头带到服务端,服务端 ASP.NET 插桩继续该 trace,于是"agent conversation"下层层嵌套到服务端 agui.run,两端合并为一条完整的 trace。

客户端工程文件 Step14_Telemetry.Client.csproj 引用了 OpenTelemetry、OpenTelemetry.Instrumentation.Http、OpenTelemetry.Exporter.Console 与 OpenTelemetry.Exporter.OpenTelemetryProtocol。

前端工具与后端工具在跨度树中的位置

SampleClient.cs 展示了三种调用形态,正好对应三种跨度形态:

  1. 后端工具:get_weather 在服务端执行,其 execute_tool 跨度出现在服务端 agui.run 之下;
  2. 混合工具:通过 ChatOptions { Tools = [location] } 注册前端工具 get_user_location,模型同时调用后端工具与前端工具,execute_tool 跨度分别出现在服务端与客户端进程,但共享同一条 trace;
  3. 人机协同: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)为按会话维度的查询与排障提供了统一的元数据基础。

相关资源可继续深入:

登录后查看全文
ag-ui