Delen via

Waarneembaarheid inschakelen voor agents

In deze zelfstudie ziet u hoe u OpenTelemetry inschakelt op een agent, zodat interacties met de agent automatisch worden geregistreerd en geëxporteerd. In deze handleiding wordt uitvoer naar de console geschreven met behulp van de OpenTelemetry-consoleexporteur.

Opmerking

Zie voor meer informatie over de standaarden gevolgd door het Microsoft Agent Framework, Semantic Conventions for GenAI agent and framework-onderdelen van Open Telemetry.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten.

NuGet-pakketten installeren

Als u Microsoft Agent Framework wilt gebruiken met Azure OpenAI, moet u de volgende NuGet-pakketten installeren:

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

Als u ook OpenTelemetry-ondersteuning wilt toevoegen, met ondersteuning voor schrijven naar de console, installeert u deze aanvullende pakketten:

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

OpenTelemetry inschakelen in uw app

Schakel Agent Framework-telemetrie in en maak een OpenTelemetry TracerProvider die naar de console exporteert. De TracerProvider moet actief blijven terwijl u de agent uitvoert, zodat traces worden geëxporteerd.

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

Creëer en instrumenteer de agent

Maak een agent en gebruik het opbouwpatroon UseOpenTelemetry om een bronnaam op te geven. Houd er rekening mee dat de letterlijke agent-telemetry-source tekenreeks de openTelemetry-bronnaam is die u hebt gebruikt bij het maken van de tracerprovider.

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

Voer de agent uit en druk de tekstreactie af. De consoleexporteur toont traceringsgegevens op de console.

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

De verwachte uitvoer ziet er ongeveer als volgt uit, waarbij de aanroeptracering van de agent eerst wordt weergegeven, gevolgd door het tekstantwoord van de agent.

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

Volgende stappen

Permanente gesprekken

Deze zelfstudie laat zien hoe u OpenTelemetry snel inschakelt op een agent, zodat interacties met de agent automatisch worden geregistreerd en geëxporteerd.

Zie de gebruikershandleiding voor waarneembaarheid voor uitgebreide documentatie over waarneembaarheid, inclusief alle configuratieopties, omgevingsvariabelen en geavanceerde scenario's.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten.

Pakketten installeren

Als u Agent Framework wilt gebruiken met OpenTelemetry, installeert u het framework:

pip install agent-framework --pre

Voor console-uitvoer tijdens de ontwikkeling zijn er geen extra pakketten nodig. Zie de sectie Afhankelijkheden in de gebruikershandleiding voor andere exporteurs.

OpenTelemetry inschakelen in uw app

De eenvoudigste manier om waarneembaarheid mogelijk te maken, is door gebruik te maken van configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

Of gebruik omgevingsvariabelen voor meer flexibiliteit:

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

De agent maken en uitvoeren

Maak een agent met Agent Framework. Waarneembaarheid wordt automatisch ingeschakeld nadat configure_otel_providers() is aangeroepen.

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)

De consoleexporteur toont traceringsgegevens die vergelijkbaar zijn met:

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

Als u Microsoft Foundry gebruikt, is er een handige methode waarmee Azure Monitor automatisch wordt geconfigureerd met Application Insights. Controleer eerst of uw Foundry-project Azure Monitor heeft geconfigureerd (zie Monitor-toepassingen).

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)

Aangepaste agents met waarneembaarheid van Foundry

Voor aangepaste agents die niet zijn gemaakt via Foundry, kunt u deze registreren in de Foundry-portal en dezelfde OpenTelemetry-agent-id gebruiken. Zie Aangepaste agent registreren voor installatie-instructies.

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

Aanbeveling

Zie de sectie Microsoft Foundry setup in de gebruikershandleiding voor gedetailleerdere installatie-instructies.

Volgende stappen

Zie de gebruikershandleiding voor waarneembaarheid voor meer geavanceerde scenario's met betrekking tot waarneembaarheid, waaronder aangepaste exporteurs, integraties van derden (Langfuse, enzovoort), het instellen van het Aspire Dashboard en gedetailleerde documentatie over span/metric.

Permanente gesprekken

  • Last updated on