Pozorovatelnost agenta

Pozorovatelnost je klíčovým aspektem vytváření spolehlivých a udržovatelných systémů. Agent Framework poskytuje integrovanou podporu pozorovatelnosti, která umožňuje monitorovat chování vašich agentů.

Tato příručka vás provede postupem, jak povolit pozorovatelnost pomocí rozhraní Agent Framework, abyste pochopili, jak vaši agenti fungují, a diagnostikovat případné problémy, které mohou nastat.

Integrace OpenTelemetry

Agent Framework se integruje s OpenTelemetry a konkrétněji Agent Framework generuje trasování, protokoly a metriky podle sémantických konvencí OpenTelemetry GenAI.

Povolení pozorovatelnosti (C#)

Pokud chcete chatovacímu klientovi povolit pozorovatelnost, je potřeba vytvořit chatovacího klienta následujícím způsobem:

// 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();

Pokud chcete pro svého agenta povolit pozorovatelnost, musíte agenta sestavit následujícím způsobem:

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

Důležité

Když povolíte pozorovatelnost pro chatovací klienty a agenty, může se zobrazit duplicitní informace, zejména pokud jsou povolena citlivá data. Kontext chatu (včetně výzev a odpovědí), který zachytí jak chatovací klient, tak agent, bude zahrnut do obou rozsahů. V závislosti na vašich potřebách se můžete rozhodnout povolit pozorovatelnost pouze v chatovacím klientovi nebo jenom v agentu, abyste se vyhnuli duplikaci. Další podrobnosti o atributech zachycených pro LLM a agenty najdete v sémantických konvencích GenAI .

Poznámka:

Povolit citlivá data pouze ve vývojových nebo testovacích prostředích, protože můžou zveřejnit informace o uživatelích v produkčních protokolech a trasování. Citlivá data zahrnují výzvy, odpovědi, argumenty volání funkce a výsledky.

Konfigurace

Teď, když je váš chatovací klient a agent instrumentovaný, můžete nakonfigurovat exportéry OpenTelemetry tak, aby odesílaly telemetrická data do požadovaného back-endu.

Trasování

Pokud chcete exportovat trasování do požadovaného back-endu, můžete v spouštěcím kódu aplikace nakonfigurovat sadu OpenTelemetry SDK. Pokud chcete například exportovat trasování do prostředku služby Azure Monitor:

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();

Návod

V závislosti na vašem back-endu můžete použít různé vývozce, další informace najdete v dokumentaci OpenTelemetry .NET . Pro místní vývoj zvažte použití řídicího panelu Aspire.

Metrics

Podobně můžete k exportu metrik do požadovaného back-endu nakonfigurovat sadu OpenTelemetry SDK ve spouštěcím kódu aplikace. Pokud chcete například exportovat metriky do prostředku služby Azure Monitor:

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();

Záznamy

Protokoly se zaznamenávají prostřednictvím rozhraní protokolování, které používáte, například Microsoft.Extensions.Logging. Pokud chcete exportovat protokoly do prostředku služby Azure Monitor, můžete nakonfigurovat zprostředkovatele protokolování ve spouštěcím kódu aplikace:

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>();

Aspire Dashboard

Zvažte použití řídicího panelu Aspire jako rychlého způsobu vizualizace trasování a metrik během vývoje. Další informace najdete v dokumentaci k řídicímu panelu Aspire. Řídicí panel Aspire přijímá data prostřednictvím kolekce OpenTelemetry, kterou můžete přidat k poskytovateli traceru následujícím způsobem:

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();

Začínáme

Podívejte se na úplný příklad agenta s povoleným OpenTelemetry v úložišti Agent Framework.

Povolení pozorovatelnosti (Python)

Pokud chcete povolit pozorovatelnost v aplikaci Pythonu, ve většině případů nemusíte instalovat nic dalšího, ve výchozím nastavení se nainstaluje následující balíček:

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

Nejjednodušší způsob, jak povolit pozorovatelnost, je nastavit pomocí následujících proměnných prostředí. Po nastavení těchto možností stačí volat na začátku programu:

from agent_framework.observability import setup_observability

setup_observability()

To vezme v úvahu proměnné prostředí a odpovídajícím způsobem nastaví pozorovatelnost, nastaví globálního zprostředkovatele trasování a poskytovatele měřiče, takže ho můžete začít okamžitě používat, například vytvořit vlastní rozsahy nebo metriky:

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"})

Jedná se o obálky rozhraní OpenTelemetry API, které vrátí trasovací nástroj nebo měřič od globálního poskytovatele, ale s nastaveným agent_framework názvem knihovny instrumentace, pokud název nepřepíšete.

V otlp_endpointspřípadě , budou vytvořeny jako OTLPExporter, jeden pro rozsah, metriky a protokoly. Pro connection_string Application Insights se použije k vytvoření služby AzureMonitorTraceExporter, AzureMonitorMetricExporter a AzureMonitorLogExporter.

Proměnné prostředí

Nejjednodušší způsob, jak pro vaši aplikaci povolit pozorovatelnost, je nastavit následující proměnné prostředí:

ENABLE_OTEL Default je falsenastavena na true povolení OpenTelemetry To je potřeba pro základní nastavení, ale také pro vizualizaci pracovních postupů.
ENABLE_SENSITIVE_DATA Default je falsenastavená na true povolení protokolování citlivých dat, jako jsou výzvy, odpovědi, argumenty volání funkce a výsledky. To je potřeba, pokud chcete zobrazit skutečné výzvy a odpovědi v trasování. Při tomto nastavení buďte opatrní, protože může v protokolech vystavit citlivá data.
OTLP_ENDPOINT Default je Nonenastaveno na hostitele pro otel, často: http://localhost:4317 To lze použít pro jakýkoli kompatibilní koncový bod OTLP, jako je OpenTelemetry Collector, Aspire Dashboard nebo jakýkoli jiný koncový bod kompatibilní s OTLP.
APPLICATIONINSIGHTS_CONNECTION_STRING Výchozí hodnota je Nonenastavená na připojovací řetězec Application Insights pro export do služby Azure Monitor. Připojovací řetězec najdete na webu Azure Portal v části Přehled vašeho prostředku Application Insights. To bude vyžadovat azure-monitor-opentelemetry-exporter instalaci balíčku.
VS_CODE_EXTENSION_PORT Výchozí je 4317nastavená na port, na kterém běží rozšíření AI Toolkit nebo AzureAI Foundry VS Code.

Programové nastavení

Pokud chcete nastavit pozorovatelnost programově, můžete to udělat voláním setup_observability funkce s požadovanými možnostmi konfigurace:

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
)

Tím se použijí poskytnuté možnosti konfigurace a odpovídajícím způsobem nastaví pozorovatelnost. Předpokládá se, že chcete povolit trasování, takže enable_otel je implicitně nastaven na True. Pokud máte také koncové body nebo připojovací řetězce nastavené prostřednictvím proměnných prostředí, vytvoří se také ty, které zkontrolujeme, jestli neexistuje žádné zdvojnásobení.

Vlastní exportéry

Pokud chcete mít jiné vývozce, pak standardní výše uvedené nebo pokud chcete nastavení dále přizpůsobit, můžete to udělat tak, že vytvoříte vlastního poskytovatele trasování a poskytovatele měřiče a pak je setup_observability předáte funkci, například:

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])

Nastavení Azure AI Foundry

Azure AI Foundry má integrovanou podporu trasování s opravdu skvělou vizualizací pro vaše rozsahy.

Pokud máte nastavení projektu Azure AI Foundry s prostředkem Application Insights, můžete udělat toto:

Nainstalujte balíček azure-monitor-opentelemetry-exporter:

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

Pak můžete nastavit pozorovatelnost projektu Azure AI Foundry následujícím způsobem:

from agent_framework.azure import AzureAIAgentClient
from azure.identity import AzureCliCredential

agent_client = AzureAIAgentClient(credential=AzureCliCredential(), project_endpoint="https://<your-project>.foundry.azure.com")

await agent_client.setup_azure_ai_observability()

Jedná se o metodu pohodlí, která použije klienta projektu, k získání připojovacího řetězce Application Insights a následné volání setup_observability s tímto připojovacím řetězcem, přepsání existujícího připojovacího řetězce nastaveného prostřednictvím proměnné prostředí.

Instrumentace s nulovým kódem

Vzhledem k tomu, že používáme standardní sadu OpenTelemetry SDK, můžete k instrumentaci aplikace použít také instrumentaci s nulovým kódem, spustit kód takto:

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

Další informace a podrobnosti o použitých proměnných prostředí najdete v dokumentaci OpenTelemetry Zero-code Pythonu .

Rozsahy a metriky

Jakmile je všechno nastavené, začnete automaticky zobrazovat rozsahy a metriky, které se pro vás vytvářejí, rozsahy jsou:

invoke_agent <agent_name>: Toto je rozsah nejvyšší úrovně pro každé vyvolání agenta, bude obsahovat všechny ostatní rozsahy jako podřízené položky.
chat <model_name>: Toto rozpětí se vytvoří, když agent volá základní model chatu, bude obsahovat výzvu a odpověď jako atributy, pokud enable_sensitive_data je nastavena na True.
execute_tool <function_name>: Toto rozpětí se vytvoří, když agent volá nástroj funkce, bude obsahovat argumenty funkce a výsledek jako atributy, pokud enable_sensitive_data je nastavena na True.

Vytvořené metriky:

Pro chatovacího klienta a chat operace:
- gen_ai.client.operation.duration (histogram): Tato metrika měří dobu trvání každé operace v sekundách.
- gen_ai.client.token.usage (histogram): Tato metrika měří využití tokenu v počtu tokenů.
Volání funkce během execute_tool operací:
- agent_framework.function.invocation.duration (histogram): Tato metrika měří dobu trvání každého spuštění funkce v sekundách.

Příklad výstupu trasování

Když spustíte agenta s povolenou pozorovatelností, zobrazí se data trasování podobná následujícímu výstupu konzoly:

{
    "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
    }
}

Toto trasování ukazuje:

Trasování a identifikátory rozsahu: Pro korelaci souvisejících operací
Informace o časování: Kdy byla operace spuštěna a ukončena
Metadata agenta: ID, název a pokyny agenta
Informace o modelu: Použitý systém AI (OpenAI) a ID odpovědi
Využití tokenů: Počty vstupních a výstupních tokenů pro sledování nákladů

Samples

V našem úložišti máme řadu ukázek, které ukazují tyto možnosti, viz složka s ukázkami pozorovatelnosti na GitHubu. To zahrnuje i ukázky pro použití telemetrie s nulovým kódem.

Další kroky

Odpovědi na pozadí

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-19