Osservabilità agente

L'osservabilità è un aspetto chiave della creazione di sistemi affidabili e gestibili. Agent Framework offre il supporto predefinito per l'osservabilità, consentendo di monitorare il comportamento degli agenti.

Questa guida illustra i passaggi per abilitare l'osservabilità con Agent Framework per comprendere le prestazioni degli agenti e diagnosticare eventuali problemi che possono verificarsi.

Integrazione di OpenTelemetry

Agent Framework si integra con OpenTelemetry e, in particolare, Agent Framework genera tracce, log e metriche in base alle convenzioni semantiche di OpenTelemetry GenAI.

Abilitare Observability (C#)

Per abilitare l'osservabilità per il client di chat, è necessario creare il client di chat come indicato di seguito:

// Using the Azure OpenAI client as an example
var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
    .AsBuilder()
    .UseOpenTelemetry(sourceName: "MyApplication", configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Per abilitare l'osservabilità per l'agente, è necessario compilare l'agente nel modo seguente:

var agent = new ChatClientAgent(
    instrumentedChatClient,
    name: "OpenTelemetryDemoAgent",
    instructions: "You are a helpful assistant that provides concise and informative responses.",
    tools: [AIFunctionFactory.Create(GetWeatherAsync)]
).WithOpenTelemetry(sourceName: "MyApplication", enableSensitiveData: true);    // Enable OpenTelemetry instrumentation with sensitive data

Importante

Quando si abilita l'osservabilità per i client di chat e gli agenti, è possibile che vengano visualizzate informazioni duplicate, soprattutto quando sono abilitati i dati sensibili. Il contesto della chat (incluse le richieste e le risposte) acquisito sia dal client di chat che dall'agente verranno inclusi in entrambi gli intervalli. A seconda delle esigenze, è possibile scegliere di abilitare l'osservabilità solo sul client di chat o solo sull'agente per evitare la duplicazione. Per altri dettagli sugli attributi acquisiti per LLM e agenti, vedere Le convenzioni semantiche GenAI .

Annotazioni

Abilitare solo i dati sensibili negli ambienti di sviluppo o test, in quanto possono esporre le informazioni utente nei log e nelle tracce di produzione. I dati sensibili includono prompt, risposte, argomenti di chiamata di funzione e risultati.

Configurazione

Ora che il client di chat e l'agente sono instrumentati, è possibile configurare gli utilità di esportazione OpenTelemetry per inviare i dati di telemetria al back-end desiderato.

Tracce

Per esportare tracce nel back-end desiderato, è possibile configurare OpenTelemetry SDK nel codice di avvio dell'applicazione. Ad esempio, per esportare tracce in una risorsa di Monitoraggio di Azure:

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

var SourceName = "MyApplication";

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry
    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Suggerimento

A seconda del back-end, è possibile usare diversi strumenti di esportazione, vedere la documentazione di OpenTelemetry .NET per altre informazioni. Per lo sviluppo locale, è consigliabile usare il dashboard Di aspirare.

Metriche

Analogamente, per esportare le metriche nel back-end desiderato, è possibile configurare OpenTelemetry SDK nel codice di avvio dell'applicazione. Ad esempio, per esportare le metriche in una risorsa di Monitoraggio di Azure:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using System;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddMeter("*Microsoft.Agents.AI") // Agent Framework metrics
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Registrazioni

I log vengono acquisiti tramite il framework di registrazione in uso, ad esempio Microsoft.Extensions.Logging. Per esportare i log in una risorsa di Monitoraggio di Azure, è possibile configurare il provider di registrazione nel codice di avvio dell'applicazione:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Extensions.Logging;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter(options => options.ConnectionString = applicationInsightsConnectionString);
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    })
    .SetMinimumLevel(LogLevel.Debug);
});

// Create a logger instance for your application
var logger = loggerFactory.CreateLogger<Program>();

Dashboard Aspire

Prendere in considerazione l'uso del dashboard Di aspirare come modo rapido per visualizzare le tracce e le metriche durante lo sviluppo. Per altre informazioni, vedere La documentazione di Aspira dashboard. Il dashboard aspirabile riceve i dati tramite un agente di raccolta OpenTelemetry, che è possibile aggiungere al provider di traccia come indicato di seguito:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry
    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

Come iniziare

Vedere un esempio completo di un agente con OpenTelemetry abilitato nel repository di Agent Framework.

Abilitare Observability (Python)

Per abilitare l'osservabilità nell'applicazione Python, nella maggior parte dei casi non è necessario installare elementi aggiuntivi, per impostazione predefinita viene installato il pacchetto seguente:

"opentelemetry-api",
"opentelemetry-sdk",
"opentelemetry-exporter-otlp-proto-grpc",
"opentelemetry-semantic-conventions-ai",

Il modo più semplice per abilitare l'osservabilità consiste nel configurare usando le variabili di ambiente seguenti. Dopo aver impostato questi elementi, è sufficiente chiamare all'inizio del programma:

from agent_framework.observability import setup_observability

setup_observability()

In questo modo le variabili di ambiente prenderanno in considerazione e impostano di conseguenza l'osservabilità, il provider di traccia globale e il provider di contatori, in modo da iniziare subito a usarlo, ad esempio per creare intervalli o metriche personalizzati:

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # do something
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Si tratta di wrapper dell'API OpenTelemetry, che restituirà un traccia o un contatore dal provider globale, ma con agent_framework impostato come nome della libreria di strumentazione, a meno che non si esegua l'override del nome.

Per otlp_endpoints, questi verranno creati come OTLPExporter, uno per span, metriche e log. Per connection_string Application Insights verrà usato per creare azureMonitorTraceExporter, AzureMonitorMetricExporter e AzureMonitorLogExporter.

Variabili di ambiente

Il modo più semplice per abilitare l'osservabilità per l'applicazione consiste nell'impostare le variabili di ambiente seguenti:

• ENABLE_OTEL Il valore predefinito è false, impostato su true per abilitare OpenTelemetry Questo è necessario per la configurazione di base, ma anche per visualizzare i flussi di lavoro.
• ENABLE_SENSITIVE_DATA Valore predefinito è false, impostato su true per abilitare la registrazione dei dati sensibili, ad esempio richieste, risposte, argomenti e risultati delle chiamate di funzione. Questa operazione è necessaria se si vogliono visualizzare le richieste e le risposte effettive nelle tracce. Prestare attenzione a questa impostazione, perché può esporre dati sensibili nei log.
• OTLP_ENDPOINT Valore predefinito è None, impostato sul proprio host per intune, spesso: http://localhost:4317 può essere usato per qualsiasi endpoint OTLP conforme, ad esempio OpenTelemetry Collector, Aspire Dashboard o qualsiasi altro endpoint conforme a OTLP.
• APPLICATIONINSIGHTS_CONNECTION_STRING Valore predefinito è None, impostare sulla stringa di connessione di Application Insights da esportare in Monitoraggio di Azure. È possibile trovare la stringa di connessione nel portale di Azure, nella sezione "Panoramica" della risorsa di Application Insights. Questo richiederà l'installazione del azure-monitor-opentelemetry-exporter pacchetto.
• VS_CODE_EXTENSION_PORT Il valore predefinito è 4317, impostare sulla porta in cui è in esecuzione l'estensione AI Toolkit o AzureAI Foundry VS Code.

Configurazione a livello di codice

Se si preferisce configurare l'osservabilità a livello di codice, è possibile farlo chiamando la setup_observability funzione con le opzioni di configurazione desiderate:

from agent_framework.observability import setup_observability

setup_observability(
    enable_sensitive_data=True,
    otlp_endpoint="http://localhost:4317",
    applicationinsights_connection_string="InstrumentationKey=your_instrumentation_key",
    vs_code_extension_port=4317
)

In questo modo verranno applicate le opzioni di configurazione fornite e verrà configurata di conseguenza l'osservabilità. Si presuppone che si intenda abilitare la traccia, quindi enable_otel è impostato in modo implicito su True. Se sono impostati anche endpoint o stringhe di connessione tramite variabili di ambiente, verranno creati anche questi endpoint e si verificherà se non è presente alcun raddoppio.

Esportazioni personalizzate

Se si desidera avere diversi esportatori, quelli standard sopra o se si vuole personalizzare ulteriormente la configurazione, è possibile farlo creando il proprio provider di traccia e provider di contatori e quindi passando quelli alla setup_observability funzione, ad esempio:

from agent_framework.observability import setup_observability
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

custom_span_exporter = OTLPSpanExporter(endpoint="http://localhost:4317", timeout=5, compression=Compression.Gzip)

setup_observability(exporters=[custom_span_exporter])

Configurazione di Azure AI Foundry

Azure AI Foundry offre il supporto predefinito per la traccia, con una visualizzazione davvero ottimale per gli intervalli di tempo.

Quando si dispone di una configurazione di un progetto Azure AI Foundry con una risorsa di Application Insights, è possibile eseguire le operazioni seguenti:

1. Installare il pacchetto azure-monitor-opentelemetry-exporter:

pip install azure-monitor-opentelemetry-exporter>=1.0.0b41 --pre

2. È quindi possibile configurare l'osservabilità per il progetto Azure AI Foundry come indicato di seguito:

from agent_framework.azure import AzureAIAgentClient
from agent_framework.observability import setup_observability
from azure.ai.projects.aio import AIProjectClient
from azure.identity import AzureCliCredential

async def main():
     async with AIProjectClient(credential=AzureCliCredential(), project_endpoint="https://<your-project>.foundry.azure.com") as project_client:
        try:
            conn_string = await project_client.telemetry.get_application_insights_connection_string()
            setup_observability(applicationinsights_connection_string=conn_string, enable_sensitive_data=True)
        except ResourceNotFoundError:
            print("No Application Insights connection string found for the Azure AI Project.")

Si tratta di un metodo pratico, che userà il client del progetto, per ottenere la stringa di connessione di Application Insights e quindi chiamare setup_observability con tale stringa di connessione, ignorando qualsiasi stringa di connessione esistente impostata tramite la variabile di ambiente.

Strumentazione senza codice

Poiché si usa lo standard OpenTelemetry SDK, è anche possibile usare la strumentazione zero-code per instrumentare l'applicazione, eseguire il codice simile al seguente:

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name your-service-name \
    --exporter_otlp_endpoint 0.0.0.0:4317 \
    python agent_framework_app.py

Per altre informazioni e dettagli sulle variabili di ambiente usate, vedere la documentazione di Python openTelemetry Zero-code Python .

Intervalli e metriche

Una volta configurati tutti gli elementi, si inizierà a visualizzare intervalli e metriche creati automaticamente, gli intervalli sono:

• invoke_agent <agent_name>: questo è l'intervallo di primo livello per ogni chiamata dell'agente, che conterrà tutti gli altri intervalli come elementi figlio.
• chat <model_name>: questo intervallo viene creato quando l'agente chiama il modello di chat sottostante, conterrà la richiesta e la risposta come attributi, se enable_sensitive_data è impostato su True.
• execute_tool <function_name>: questo intervallo viene creato quando l'agente chiama uno strumento di funzione, conterrà gli argomenti della funzione e il risultato come attributi, se enable_sensitive_data è impostato su True.

Le metriche create sono:

• Per il client e chat le operazioni di chat:

  • gen_ai.client.operation.duration (istogramma): questa metrica misura la durata di ogni operazione, in secondi.
  • gen_ai.client.token.usage (istogramma): questa metrica misura l'utilizzo del token, in numero di token.

• Per la chiamata di funzione durante le execute_tool operazioni:

  • agent_framework.function.invocation.duration (istogramma): questa metrica misura la durata di ogni esecuzione della funzione, in secondi.

Output di traccia di esempio

Quando si esegue un agente con osservabilità abilitata, verranno visualizzati dati di traccia simili all'output della console seguente:

{
    "name": "invoke_agent Joker",
    "context": {
        "trace_id": "0xf2258b51421fe9cf4c0bd428c87b1ae4",
        "span_id": "0x2cad6fc139dcf01d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-09-25T11:00:48.663688Z",
    "end_time": "2025-09-25T11:00:57.271389Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.system": "openai",
        "gen_ai.agent.id": "Joker",
        "gen_ai.agent.name": "Joker",
        "gen_ai.request.instructions": "You are good at telling jokes.",
        "gen_ai.response.id": "chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5",
        "gen_ai.usage.input_tokens": 26,
        "gen_ai.usage.output_tokens": 29
    }
}

Questa traccia mostra:

• Identificatori di traccia e intervallo: per correlare le operazioni correlate
• Informazioni sull'intervallo: all'avvio e alla fine dell'operazione
• Metadati dell'agente: ID agente, nome e istruzioni
• Informazioni sul modello: il sistema di intelligenza artificiale usato (OpenAI) e l'ID risposta
• Utilizzo dei token: conteggi dei token di input e output per il rilevamento dei costi

Samples

Nel repository sono disponibili diversi esempi che illustrano queste funzionalità, vedere la cartella degli esempi di osservabilità in Github. Sono inclusi anche esempi per l'uso di dati di telemetria con codice zero.

Passaggi successivi

Risposte in background