Aktivieren der Beobachtbarkeit für Agenten

In diesem Lernprogramm wird gezeigt, wie OpenTelemetry für einen Agent aktiviert wird, sodass Interaktionen mit dem Agent automatisch protokolliert und exportiert werden. In diesem Lernprogramm wird die Ausgabe mithilfe des OpenTelemetry-Konsolenexporters in die Konsole geschrieben.

Voraussetzungen

Voraussetzungen finden Sie im Schritt "Erstellen und Ausführen eines einfachen Agents " in diesem Lernprogramm.

Installieren von NuGet-Paketen

Um Microsoft Agent Framework mit Azure OpenAI zu verwenden, müssen Sie die folgenden NuGet-Pakete installieren:

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

Um auch die OpenTelemetry-Unterstützung hinzuzufügen, installieren Sie diese zusätzlichen Pakete mit Unterstützung für das Schreiben in die Konsole:

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

Aktivieren von OpenTelemetry in Ihrer App

Aktivieren Sie die Telemetrie des Agent-Frameworks, und erstellen Sie eine OpenTelemetry TracerProvider , die in die Konsole exportiert wird. Der TracerProvider muss aktiv bleiben, während Sie den Agenten ausführen, damit Traces exportiert werden.

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

Erstellen und instrumentieren Sie den Agenten

Erstellen Sie einen Agent, und verwenden Sie das Generatormuster, und rufen Sie auf UseOpenTelemetry , um einen Quellnamen anzugeben. Beachten Sie, dass das Zeichenfolgenliteral agent-telemetry-source der OpenTelemetry-Quellname ist, den Sie beim Erstellen des Tracer-Anbieters verwendet haben.

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

Führen Sie den Agent aus, und drucken Sie die Textantwort. Der Konsolen-Exporter zeigt Ablaufverfolgungsdaten auf der Konsole an.

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

Die erwartete Ausgabe sieht ungefähr so aus, wobei die Agent-Aufrufablaufverfolgung zuerst angezeigt wird, gefolgt von der Textantwort des Agents.

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"! ?????

Nächste Schritte

In diesem Lernprogramm wird gezeigt, wie Sie OpenTelemetry für einen Agent schnell aktivieren, damit Interaktionen mit dem Agent automatisch protokolliert und exportiert werden.

Eine umfassende Dokumentation zur Observability, einschließlich aller Konfigurationsoptionen, Umgebungsvariablen und erweiterten Szenarien, finden Sie in der Observability-Benutzerhandbuch.

Voraussetzungen

Voraussetzungen finden Sie im Schritt "Erstellen und Ausführen eines einfachen Agents " in diesem Lernprogramm.

Pakete installieren

Um Agent Framework mit OpenTelemetry zu verwenden, installieren Sie das Framework:

pip install agent-framework --pre

Für die Konsolenausgabe während der Entwicklung sind keine zusätzlichen Pakete erforderlich. Weitere Exporteure finden Sie im Abschnitt "Abhängigkeiten" in der Benutzerhandbuch.

Aktivieren von OpenTelemetry in Ihrer App

Die einfachste Möglichkeit zur Aktivierung der Observierbarkeit ist die Verwendung configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

Oder verwenden Sie Umgebungsvariablen für mehr Flexibilität:

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

Agent erstellen und ausführen

Erstellen Sie einen Agent mithilfe von Agent Framework. Observability wird automatisch aktiviert, sobald configure_otel_providers() aufgerufen wurde.

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)

Der Konsolenexporteur zeigt Ablaufverfolgungsdaten wie folgt an:

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

Microsoft Foundry-Integration

Wenn Sie Microsoft Foundry verwenden, gibt es eine bequeme Methode, mit der Azure Monitor automatisch mit Application Insights konfiguriert wird. Stellen Sie zuerst sicher, dass Ihr Foundry-Projekt Azure Monitor konfiguriert hat (siehe Monitoranwendungen).

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)

Benutzerdefinierte Agents mit Gießereibeobachtbarkeit

Für benutzerdefinierte Agents, die nicht über Foundry erstellt wurden, können Sie sie im Foundry-Portal registrieren und dieselbe OpenTelemetry-Agent-ID verwenden. Anweisungen zum Registrieren eines benutzerdefinierten Agents finden Sie unter "Registrieren eines benutzerdefinierten Agents ".

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

Nächste Schritte

Komplexere Observability-Szenarien, einschließlich benutzerdefinierter Exporteure, Integrationen von Drittanbietern (Langfuse etc.), Einrichten des Aspire-Dashboards und detaillierter Span- und Metrikdokumentation, finden Sie im Observability-Benutzerhandbuch.