Megosztás:

Az ügynökök megfigyelhetőségének engedélyezése

Ez az oktatóanyag bemutatja, hogyan engedélyezheti az OpenTelemetryt egy ügynökön, hogy a rendszer automatikusan naplózza és exportálja az ügynökkel folytatott interakciókat. Ebben az oktatóanyagban a kimenet az OpenTelemetry konzolexportáló használatával lesz megírva a konzolra.

Megjegyzés:

A Microsoft Agent Framework által követett szabványokról további információt a GenAI-ügynökre vonatkozó szemantikai konvenciók és az Open Telemetria keretrendszerei című témakörben talál.

Előfeltételek

Az előfeltételekről ebben az oktatóanyagban az Egyszerű ügynök létrehozása és futtatása című témakörben olvashat.

NuGet-csomagok telepítése

A Microsoft Agent Framework azure OpenAI-val való használatához telepítenie kell a következő NuGet-csomagokat:

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

Az OpenTelemetry támogatásának hozzáadásához a konzolra való írás támogatásával telepítse az alábbi további csomagokat:

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

OpenTelemetria engedélyezése az alkalmazásban

Engedélyezze az Agent Framework telemetriát, és hozzon létre egy OpenTelemetry TracerProvider, amely a konzolra exportál. Az TracerProvider ügynök futtatása közben a rendszernek életben kell maradnia, hogy a nyomkövetések exportálva legyenek.

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

Az ügynök létrehozása és hangszerelése

Hozzon létre egy ügynököt, és a builder minta használatával hívja meg a UseOpenTelemetry függvényt, hogy megadja a forrás nevét. Vegye figyelembe, hogy a sztringkonstans agent-telemetry-source az OpenTelemetry forrásneve, amelyet a nyomkövetési szolgáltató létrehozásakor használt.

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

Futtassa az ügynököt, és nyomtassa ki a szöveges választ. A konzolexportáló nyomkövetési adatokat jelenít meg a konzolon.

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

A várt kimenet ehhez hasonló lesz, ahol először az ügynök meghívási nyomkövetése jelenik meg, majd az ügynök szöveges válasza.

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

Következő lépések

Beszélgetések megőrzése

Ez az oktatóanyag bemutatja, hogyan engedélyezheti gyorsan az OpenTelemetryt egy ügynökön, hogy a rendszer automatikusan naplózza és exportálja az ügynökkel folytatott interakciókat.

A megfigyelhetőséggel kapcsolatos átfogó dokumentációt, beleértve az összes konfigurációs lehetőséget, környezeti változót és speciális forgatókönyvet, tekintse meg az Megfigyelhetőség felhasználói útmutatót.

Előfeltételek

Az előfeltételekről ebben az oktatóanyagban az Egyszerű ügynök létrehozása és futtatása című témakörben olvashat.

Csomagok telepítése

Az Agent Framework OpenTelemetryvel való használatához telepítse a keretrendszert:

pip install agent-framework --pre

A konzolkimenethez a fejlesztés során nincs szükség további csomagokra. Más exportőrök esetében lásd a felhasználói útmutató Függőségek szakaszát .

OpenTelemetria engedélyezése az alkalmazásban

A megfigyelhetőség engedélyezésének legegyszerűbb módja a következő configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

Vagy használjon környezeti változókat a nagyobb rugalmasság érdekében:

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

Az ügynök létrehozása és futtatása

Ügynök létrehozása az Agent Framework használatával. A configure_otel_providers() meghívása után a megfigyelhetőség automatikusan engedélyeződik.

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)

A konzolexportáló a következőhöz hasonló nyomkövetési adatokat jelenít meg:

{
    "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-integráció

A Microsoft Foundry használata esetén van egy kényelmes módszer, amely automatikusan konfigurálja az Azure Monitort az Application Insights használatával. Először győződjön meg arról, hogy a Foundry-projekt konfigurálva van az Azure Monitorral (lásd az alkalmazások monitorozását).

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)

A Foundry megfigyelhetőségével rendelkező egyedi ügynökök

A Foundryben nem létrehozott egyéni ügynökök esetében regisztrálhatja őket az Foundry portálon, és ugyanazt az OpenTelemetry-ügynökazonosítót használhatja. A beállítási utasításokért tekintse meg az egyéni ügynök regisztrálása című témakört.

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

Jótanács

További részletes beállítási utasításokért tekintse meg a Microsoft Foundry beállítási szakaszát a felhasználói útmutatóban.

Következő lépések

A fejlettebb megfigyelhetőségi forgatókönyvek, például az egyéni exportőrök, a külső integrációk (Langfuse stb.), az Aspire Irányítópult beállítása és a részletes span/metric dokumentációért tekintse meg az Megfigyelhetőség felhasználói útmutatót.

Beszélgetések megőrzése

  • Last updated on