Włączanie obserwowalności agentów

W tym samouczku pokazano, jak włączyć usługę OpenTelemetry na agencie, aby interakcje z agentem zostały automatycznie zarejestrowane i wyeksportowane. W tym samouczku dane wyjściowe są zapisywane w konsoli przy użyciu eksportera konsoli OpenTelemetry.

Wymagania wstępne

Aby uzyskać wymagania wstępne, zobacz krok Tworzenie i uruchamianie prostego agenta w tym samouczku.

Instalowanie pakietów NuGet

Aby używać programu Microsoft Agent Framework z usługą Azure OpenAI, należy zainstalować następujące pakiety NuGet:

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

Aby dodać również obsługę OpenTelemetry, z obsługą zapisu na konsolę, zainstaluj następujące dodatkowe pakiety:

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

Włączanie funkcji OpenTelemetry w aplikacji

Włącz telemetrię Agent Framework i utwórz metrykę OpenTelemetry TracerProvider, która eksportuje do konsoli. Element TracerProvider musi pozostać aktywny podczas uruchamiania agenta, aby dane śledzenia zostały wyeksportowane.

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

Tworzenie i instrumentacja agenta

Utwórz agenta, a następnie używając wzorca projektowego budowniczego, wywołaj UseOpenTelemetry aby podać nazwę źródłową. Należy pamiętać, że literał ciągu agent-telemetry-source to nazwa źródła OpenTelemetry, której użyto podczas tworzenia dostawcy trasera.

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

Uruchom agenta i wydrukuj odpowiedź tekstową. Eksporter konsoli pokaże dane śledzenia w konsoli.

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

Oczekiwane dane wyjściowe będą wyglądać mniej więcej tak, gdzie najpierw zostanie wyświetlony ślad wywołania agenta, po którym następuje odpowiedź tekstowa 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"! ?????

Dalsze kroki

W tym samouczku pokazano, jak szybko włączyć OpenTelemetry na agencie, aby interakcje z nim były automatycznie rejestrowane i eksportowane.

Aby uzyskać kompleksową dokumentację dotyczącą możliwości obserwowania, w tym wszystkich opcji konfiguracji, zmiennych środowiskowych i zaawansowanych scenariuszy, zobacz Podręcznik użytkownika dotyczący obserwacji.

Wymagania wstępne

Aby uzyskać wymagania wstępne, zobacz krok Tworzenie i uruchamianie prostego agenta w tym samouczku.

Instalowanie pakietów

Aby użyć platformy Agent Framework z funkcją OpenTelemetry, zainstaluj platformę:

pip install agent-framework --pre

W przypadku danych wyjściowych konsoli podczas programowania nie są potrzebne żadne dodatkowe pakiety. W przypadku innych eksporterów zobacz sekcję Zależności w podręczniku użytkownika.

Włączanie funkcji OpenTelemetry w aplikacji

Najprostszym sposobem włączenia możliwości obserwacji jest użycie polecenia configure_otel_providers():

from agent_framework.observability import configure_otel_providers

# Enable console output for local development
configure_otel_providers(enable_console_exporters=True)

Możesz też użyć zmiennych środowiskowych, aby uzyskać większą elastyczność:

export ENABLE_INSTRUMENTATION=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Tworzenie i uruchamianie agenta

Tworzenie agenta przy użyciu platformy Agent Framework. Obserwowalność jest automatycznie włączana po wywołaniu configure_otel_providers().

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

# Create the agent - telemetry is automatically enabled
agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    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)

Eksporter konsoli wyświetli dane śledzenia podobne do następujących:

{
    "name": "invoke_agent Joker",
    "context": {
        "trace_id": "0xf2258b51421fe9cf4c0bd428c87b1ae4",
        "span_id": "0x2cad6fc139dcf01d"
    },
    "attributes": {
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.agent.name": "Joker",
        "gen_ai.usage.input_tokens": 26,
        "gen_ai.usage.output_tokens": 29
    }
}

Integracja z rozwiązaniem Microsoft Foundry

Jeśli używasz rozwiązania Microsoft Foundry, istnieje wygodna metoda, która automatycznie konfiguruje usługę Azure Monitor za pomocą usługi Application Insights. Najpierw upewnij się, że projekt foundry ma skonfigurowaną usługę Azure Monitor (zobacz Monitorowanie aplikacji).

pip install azure-monitor-opentelemetry

from agent_framework.azure import AzureAIClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async with (
    AzureCliCredential() as credential,
    AIProjectClient(endpoint="https://<your-project>.foundry.azure.com", credential=credential) as project_client,
    AzureAIClient(project_client=project_client) as client,
):
    # Automatically configures Azure Monitor with connection string from project
    await client.configure_azure_monitor(enable_live_metrics=True)

Agenci niestandardowi z obserwacją rozwiązania Foundry

W przypadku agentów niestandardowych, których nie utworzono za pomocą rozwiązania Foundry, można je zarejestrować w portalu Foundry i użyć tego samego identyfikatora agenta OpenTelemetry. Aby uzyskać instrukcje dotyczące konfiguracji, zobacz Rejestrowanie agenta niestandardowego .

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework import ChatAgent
from agent_framework.observability import create_resource, enable_instrumentation
from agent_framework.openai import OpenAIChatClient

# Configure Azure Monitor
configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),
    enable_live_metrics=True,
)
# Optional if ENABLE_INSTRUMENTATION is already set in env vars
enable_instrumentation()

# Create your agent with the same OpenTelemetry agent ID as registered in Foundry
agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    name="My Agent",
    instructions="You are a helpful assistant.",
    id="<OpenTelemetry agent ID>"  # Must match the ID registered in Foundry
)
# Use the agent as normal

Dalsze kroki

Aby uzyskać bardziej zaawansowane scenariusze obserwacji, w tym eksporterów niestandardowych, integracji innych firm (Langfuse itp.), Konfiguracja pulpitu nawigacyjnego Aspiruj i szczegółowa dokumentacja zakresu/metryki, zobacz podręcznik użytkownika możliwości obserwacji.