Bagikan melalui

Mengaktifkan pengamatan untuk Agen

Tutorial ini menunjukkan cara mengaktifkan OpenTelemetry pada agen sehingga interaksi dengan agen secara otomatis dicatat dan diekspor. Dalam tutorial ini, output ditulis ke konsol menggunakan pengekspor konsol OpenTelemetry.

Nota

Untuk informasi selengkapnya tentang standar yang diikuti oleh Microsoft Agent Framework, lihat Konvensi Semantik untuk agen GenAI dan rentang kerangka kerja dari Open Telemetry.

Prasyarat

Untuk prasyarat, lihat langkah Membuat dan menjalankan agen sederhana dalam tutorial ini.

Menginstal paket NuGet

Untuk menggunakan Microsoft Agent Framework dengan Azure OpenAI, Anda perlu menginstal paket NuGet berikut:

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

Untuk menambahkan dukungan OpenTelemetry, dengan dukungan untuk menulis ke konsol, instal paket tambahan ini:

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

Mengaktifkan OpenTelemetry di aplikasi Anda

Aktifkan telemetri Agent Framework dan buat OpenTelemetry TracerProvider yang diekspor ke konsol. TracerProvider harus tetap aktif saat Anda menjalankan agen agar jejak dapat diekspor.

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

Membuat dan menginstrumenkan agen

Buat agen, dan gunakan pola penyusun, panggil UseOpenTelemetry untuk memberikan nama sumber. Perhatikan bahwa string literal agent-telemetry-source adalah nama sumber OpenTelemetry yang Anda gunakan saat membuat penyedia pelacak.

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")
        .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker")
        .AsBuilder()
        .UseOpenTelemetry(sourceName: "agent-telemetry-source")
        .Build();

Jalankan agen dan cetak respons teks. Pengekspor konsol akan menampilkan data pelacakan di konsol.

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

Output yang diharapkan akan menjadi sesuatu seperti ini, di mana jejak pemanggilan agen ditampilkan terlebih dahulu, diikuti oleh respons teks dari agen.

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

Langkah selanjutnya

Percakapan yang bertahan

Tutorial ini menunjukkan cara mengaktifkan OpenTelemetry dengan cepat pada agen sehingga interaksi dengan agen secara otomatis dicatat dan diekspor.

Untuk dokumentasi komprehensif tentang pengamatan termasuk semua opsi konfigurasi, variabel lingkungan, dan skenario tingkat lanjut, lihat panduan pengguna Observabilitas.

Prasyarat

Untuk prasyarat, lihat langkah Membuat dan menjalankan agen sederhana dalam tutorial ini.

Memasang paket

Untuk menggunakan Agent Framework dengan OpenTelemetry, instal kerangka kerja:

pip install agent-framework --pre

Untuk output konsol selama pengembangan, tidak diperlukan paket tambahan. Untuk pengekspor lain, lihat bagian Dependensi di panduan pengguna.

Mengaktifkan OpenTelemetry di aplikasi Anda

Cara paling sederhana untuk mengaktifkan pengamatan adalah menggunakan configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

Atau gunakan variabel lingkungan untuk lebih banyak fleksibilitas:

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

Membuat dan menjalankan agen

Buat agen menggunakan Agent Framework. Keteramatan diaktifkan secara otomatis setelah configure_otel_providers() dipanggil.

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)

Pengekspor konsol akan menampilkan data pelacakan yang mirip dengan:

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

Integrasi Microsoft Foundry

Jika Anda menggunakan Microsoft Foundry, ada metode mudah yang secara otomatis mengonfigurasi Azure Monitor dengan Application Insights. Pertama pastikan proyek Foundry Anda memiliki Azure Monitor yang dikonfigurasi (lihat Memantau aplikasi).

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)

Agen kustom dengan pengamatan Foundry

Untuk agen kustom yang tidak dibuat melalui Foundry, Anda dapat mendaftarkannya di portal Foundry dan menggunakan ID agen OpenTelemetry yang sama. Lihat Mendaftarkan agen kustom untuk instruksi penyiapan.

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

Petunjuk / Saran

Untuk instruksi penyiapan yang lebih rinci, lihat bagian penyiapan Microsoft Foundry di panduan pengguna.

Langkah selanjutnya

Untuk skenario pengamatan yang lebih canggih termasuk eksportir kustom, integrasi pihak ketiga (Langfuse, dll.), penyiapan Dasbor Aspire, dan dokumentasi rentang/metrik terperinci, lihat panduan Pengguna observabilitas.

Percakapan yang bertahan

  • Last updated on