可观测性

可观测性是构建可靠且可维护的 Agent 系统的关键方面。Agent Framework 与 OpenTelemetry 集成，基于 OpenTelemetry GenAI 语义约定发出跟踪、日志和指标。

---

为聊天客户端启用

const string SourceName = "MyAgentApp";

var instrumentedChatClient = new AIProjectClient(
        new Uri(endpoint), new DefaultAzureCredential())
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName)
    .AsBuilder()
    .UseOpenTelemetry(
        sourceName: SourceName,
        configure: (cfg) =>
            cfg.EnableSensitiveData = true)
    .Build();

为代理启用

var agent = new ChatClientAgent(
        instrumentedChatClient,
        name: "OpenTelemetryDemoAgent",
        instructions: "You are a helpful assistant.",
        tools: [AIFunctionFactory.Create(GetWeatherAsync)])
    .WithOpenTelemetry(
        sourceName: SourceName,
        configure: (cfg) =>
            cfg.EnableSensitiveData = true);

为聊天客户端和代理都启用可观测性时，可能会看到重复信息。开启敏感数据时尤其明显——聊天上下文（提示和响应）会同时出现在两个范围中。根据需求选择仅启用聊天客户端或仅启用代理。

配置导出程序

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(SourceName)
    .ConfigureResource(r => r
        .AddService("MyAgentService"))
    .AddAzureMonitorTraceExporter(options =>
    {
        options.ConnectionString =
            "InstrumentationKey=your-key-here";
    })
    .Build();

安全注意事项

仅在开发或测试环境中启用敏感数据，因为它可能会在生产日志和跟踪中暴露用户信息。敏感数据包括提示、响应、函数调用参数和结果。

配置	范围	说明
EnableSensitiveData = false	生产	仅追踪元数据，不记录提示/响应内容
EnableSensitiveData = true	开发/测试	记录完整提示和响应用于调试

---

下一步：评估框架 — 衡量 Agent 质量和正确性。