Povolení sledovatelnosti pro agenty

V tomto kurzu se dozvíte, jak povolit OpenTelemetry pro agenta, aby se interakce s agentem automaticky protokolovaly a exportovaly. V tomto kurzu se výstup zapíše do konzoly pomocí exportéru konzoly OpenTelemetry.

Poznámka:

Další informace o standardech, které dodržuje Microsoft Agent Framework, najdete v části Sémantické konvence pro agenta GenAI a frameworky od Open Telemetry.

Požadavky

Požadavky si přečtěte v části Vytvoření a spuštění jednoduchého agenta v tomto kurzu.

Instalace balíčků NuGet

Pokud chcete používat rozhraní Microsoft Agent Framework s Azure OpenAI, musíte nainstalovat následující balíčky NuGet:

dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Pokud chcete také přidat podporu OpenTelemetry s podporou zápisu do konzoly, nainstalujte tyto další balíčky:

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console

Povolení OpenTelemetry v aplikaci

Povolte telemetrii rozhraní Agent Framework a vytvořte OpenTelemetry TracerProvider , která exportuje do konzoly. TracerProvider musí zůstat aktivní, když spouštíte agenta, aby mohly být exportovány stopy.

using System;
using OpenTelemetry;
using OpenTelemetry.Trace;

// Create a TracerProvider that exports to the console
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("agent-telemetry-source")
    .AddConsoleExporter()
    .Build();

Vytvoření a instrumentace agenta

Vytvořte agenta a pomocí vzoru tvůrce zavolejte UseOpenTelemetry pro zadání názvu zdroje. Všimněte si, že řetězcový literál agent-telemetry-source je název zdroje OpenTelemetry, který jste použili při vytváření zprostředkovatele traceru.

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using OpenAI;

// Create the agent and enable OpenTelemetry instrumentation
AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker")
        .AsBuilder()
        .UseOpenTelemetry(sourceName: "agent-telemetry-source")
        .Build();

Spusťte agenta a vytiskněte textovou odpověď. Konzolový exportér zobrazí data trasování v konzoli.

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Očekávaný výstup bude vypadat přibližně takto, kde se nejprve zobrazí trasování vyvolání agenta a za ním textová odpověď od agenta.

Activity.TraceId:            f2258b51421fe9cf4c0bd428c87b1ae4
Activity.SpanId:             2cad6fc139dcf01d
Activity.TraceFlags:         Recorded
Activity.DisplayName:        invoke_agent Joker
Activity.Kind:               Client
Activity.StartTime:          2025-09-18T11:00:48.6636883Z
Activity.Duration:           00:00:08.6077009
Activity.Tags:
    gen_ai.operation.name: chat
    gen_ai.request.model: gpt-4o-mini
    gen_ai.provider.name: openai
    server.address: <myresource>.openai.azure.com
    server.port: 443
    gen_ai.agent.id: 19e310a72fba4cc0b257b4bb8921f0c7
    gen_ai.agent.name: Joker
    gen_ai.response.finish_reasons: ["stop"]
    gen_ai.response.id: chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5
    gen_ai.response.model: gpt-4o-mini-2024-07-18
    gen_ai.usage.input_tokens: 26
    gen_ai.usage.output_tokens: 29
Instrumentation scope (ActivitySource):
    Name: agent-telemetry-source
Resource associated with Activity:
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.13.1
    service.name: unknown_service:Agent_Step08_Telemetry

Why did the pirate go to school?

Because he wanted to improve his "arrr-ticulation"! ?????

Další kroky

Zachování konverzací

Požadavky

Požadavky si přečtěte v části Vytvoření a spuštění jednoduchého agenta v tomto kurzu.

Instalace balíčků

Pokud chcete používat Agent Framework s Azure OpenAI, musíte nainstalovat následující balíčky. Agent Framework automaticky zahrnuje všechny nezbytné závislosti OpenTelemetry:

pip install agent-framework --pre

Ve výchozím nastavení jsou zahrnuty následující balíčky OpenTelemetry:

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

Pokud chcete exportovat do služby Azure Monitor (Application Insights), musíte balíček nainstalovat azure-monitor-opentelemetry také:

pip install azure-monitor-opentelemetry

Povolení OpenTelemetry v aplikaci

Agent Framework poskytuje pohodlnou setup_observability funkci, která konfiguruje OpenTelemetry s rozumnými výchozími nastaveními. Ve výchozím nastavení exportuje do konzoly, pokud není nakonfigurovaný žádný konkrétní vývozce.

import asyncio
from agent_framework.observability import setup_observability

# Enable Agent Framework telemetry with console output (default behavior)
setup_observability(enable_sensitive_data=True)

Pochopení `setup_observability` parametrů

Funkce setup_observability přijímá následující parametry pro přizpůsobení konfigurace pozorovatelnosti:

enable_otel (bool, volitelné): Povolí trasování a metriky OpenTelemetry. Výchozí hodnota je False při použití pouze proměnných prostředí, ale při volání True prostřednictvím kódu programu se předpokládásetup_observability(). Při použití proměnných prostředí nastavte ENABLE_OTEL=true.
enable_sensitive_data (bool, volitelné): Určuje, jestli jsou do trasování zahrnuta citlivá data, jako jsou výzvy, odpovědi, argumenty volání funkce a výsledky. Výchozí hodnota je False. Nastavte na True, abyste viděli skutečné výzvy systému a odpovědi ve svých trasách. Upozornění: Buďte opatrní při tomto nastavení, protože může vystavit citlivá data ve vašich protokolech. Lze také nastavit prostřednictvím ENABLE_SENSITIVE_DATA=true proměnné prostředí.
otlp_endpoint (str, volitelné): Adresa URL koncového bodu OTLP pro export telemetrických dat. Výchozí hodnota je None. Běžně nastaveno na hodnotu http://localhost:4317. Tím se vytvoří OTLPExporter pro rozsahy, metriky a protokoly. Lze použít s libovolným koncovým bodem kompatibilním s OTLP, jako je OpenTelemetry Collector, Aspire Dashboard nebo jiné koncové body OTLP. Lze také nastavit prostřednictvím OTLP_ENDPOINT proměnné prostředí.
applicationinsights_connection_string (str, volitelné): Připojovací řetězec Azure Application Insights pro export do Služby Azure Monitor. Výchozí hodnota je None. Vytvoří AzureMonitorTraceExporter, AzureMonitorMetricExporter a AzureMonitorLogExporter. Tento připojovací řetězec najdete na webu Azure Portal v části Přehled vašeho prostředku Application Insights. Lze také nastavit prostřednictvím APPLICATIONINSIGHTS_CONNECTION_STRING proměnné prostředí. Vyžaduje instalaci azure-monitor-opentelemetry balíčku.
vs_code_extension_port (int, volitelné): Číslo portu pro rozšíření AI Toolkit nebo Azure AI Foundry VS Code Výchozí hodnota je 4317. Umožňuje integraci s rozšířeními VS Code pro místní vývoj a ladění. Lze také nastavit prostřednictvím VS_CODE_EXTENSION_PORT proměnné prostředí.
exporters (seznam, volitelné): Vlastní seznam exportérů OpenTelemetry pro pokročilé scénáře. Výchozí hodnota je None. Umožňuje poskytovat vlastní nakonfigurované vývozce, pokud standardní možnosti nevyhovují vašim potřebám.

Důležité

Pokud nejsou poskytnuty žádné exportéry (prostřednictvím parametrů, proměnných prostředí nebo jako explicitní exportéry), je exportér konzole výchozí konfigurovaný pro místní ladění.

Možnosti nastavení

Pozorovatelnost můžete nakonfigurovat třemi způsoby:

1. Proměnné prostředí (nejjednodušší přístup):

export ENABLE_OTEL=true
export ENABLE_SENSITIVE_DATA=true
export OTLP_ENDPOINT=http://localhost:4317

Pak v kódu:

from agent_framework.observability import setup_observability

setup_observability()  # Reads from environment variables

2. Programová konfigurace:

from agent_framework.observability import setup_observability

# note that ENABLE_OTEL is implied to be True when calling setup_observability programmatically
setup_observability(
    enable_sensitive_data=True,
    otlp_endpoint="http://localhost:4317",
    applicationinsights_connection_string="InstrumentationKey=your_key"
)

3. Vlastní vývozci (pro pokročilé scénáře):

from agent_framework.observability import setup_observability
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import ConsoleSpanExporter

custom_exporters = [
    OTLPSpanExporter(endpoint="http://localhost:4317"),
    ConsoleSpanExporter()
]

setup_observability(exporters=custom_exporters, enable_sensitive_data=True)

Funkce setup_observability nastaví globálního zprostředkovatele trasování a poskytovatele měřičů, což vám umožní vytvářet vlastní rozsahy a 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"):
    # Your code here
    pass

counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Vytvoření a spuštění agenta

Vytvořte agenta pomocí rozhraní Agent Framework. Pozorovatelnost bude automaticky povolena pro agenta, jakmile bude setup_observability zavoláno.

from agent_framework import ChatAgent
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

# Create the agent - telemetry is automatically enabled
agent = ChatAgent(
    chat_client=AzureOpenAIChatClient(
        credential=AzureCliCredential(),
        model="gpt-4o-mini"
    ),
    name="Joker",
    instructions="You are good at telling jokes."
)

# Run the agent
result = await agent.run("Tell me a joke about a pirate.")
print(result.text)

Exportér konzole zobrazí v konzoli údaje o trasování podobné následujícímu.

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

Následuje textová odpověď od agenta:

Why did the pirate go to school?

Because he wanted to improve his "arrr-ticulation"! ⛵

Vysvětlení výstupu telemetrie

Jakmile je povolená pozorovatelnost, rozhraní Agent Framework automaticky vytvoří následující rozsahy:

invoke_agent <agent_name>: Rozsah nejvyšší úrovně pro každé vyvolání agenta. Obsahuje všechny ostatní rozsahy jako podřízené prvky a obsahuje metadata, například ID agenta, název a pokyny.
chat <model_name>: Vytvořeno, když agent volá podkladový chatový model. Obsahuje výzvu a odpověď jako atributy, pokud enable_sensitive_data je True, spolu s informacemi o využití tokenu.
execute_tool <function_name>: Vytvořeno, když agent volá funkční nástroj. Obsahuje argumenty funkce a výsledky jako atributy, pokud enable_sensitive_data je True.

Shromažďují se také následující metriky:

Pro činnost chatu:

gen_ai.client.operation.duration (histogram): Doba trvání každé operace v sekundách
gen_ai.client.token.usage (histogram): Využití tokenů v počtu tokenů

Volání funkcí:

agent_framework.function.invocation.duration (histogram): Doba trvání každého spuštění funkce v sekundách

Integrace Azure AI Foundry

Pokud používáte klienty Azure AI Foundry, existuje vhodná metoda automatického nastavení:

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

agent_client = AzureAIAgentClient(
    credential=AzureCliCredential(),
    # endpoint and model_deployment_name can be taken from environment variables
    # project_endpoint="https://<your-project>.foundry.azure.com"
    # model_deployment_name="<your-deployment-name>"
)

# Automatically configures observability with Application Insights
await agent_client.setup_azure_ai_observability()

Tato metoda načte připojovací řetězec Application Insights z projektu Azure AI Foundry a automaticky volá setup_observability . Pokud chcete používat telemetrii Foundry s jinými typy agentů, můžete to samé udělat takto:

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

project_client = AIProjectClient(endpoint, credential=AzureCliCredential())
conn_string = project_client.telemetry.get_application_insights_connection_string()
setup_observability(applicationinsights_connection_string=conn_string)

Projděte si také příslušnou dokumentaci k Foundry.

Poznámka:

Pokud pro telemetrii používáte Azure Monitor, musíte balíček nainstalovat azure-monitor-opentelemetry explicitně, protože ve výchozím nastavení není součástí agenta Framework.

Další kroky

Pokročilejší scénáře a příklady pozorovatelnosti najdete v uživatelské příručce Agent Observability a ukázkách pozorovatelnosti v úložišti GitHub.

Zachování konverzací

Váš názor

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

Last updated on 2025-11-05

Sdílet prostřednictvím

Povolení sledovatelnosti pro agenty

Požadavky

Instalace balíčků NuGet

Povolení OpenTelemetry v aplikaci

Vytvoření a instrumentace agenta

Další kroky

Požadavky

Instalace balíčků

Povolení OpenTelemetry v aplikaci

Pochopení setup_observability parametrů

Možnosti nastavení

Vytvoření a spuštění agenta

Vysvětlení výstupu telemetrie

Integrace Azure AI Foundry

Další kroky

Váš názor

Další materiály

Pochopení `setup_observability` parametrů