Observability

Pengamatan adalah aspek utama dalam membangun sistem yang andal dan dapat dipertahankan. Agent Framework menyediakan dukungan bawaan untuk pengamatan, memungkinkan Anda memantau perilaku agen Anda.

Panduan ini akan memandu Anda melalui langkah-langkah untuk memungkinkan pengamatan dengan Agent Framework untuk membantu Anda memahami performa agen Anda dan mendiagnosis masalah apa pun yang mungkin muncul.

Integrasi OpenTelemetry

Agent Framework terintegrasi dengan OpenTelemetry, dan lebih khusus lagi Agent Framework memancarkan jejak, log, dan metrik sesuai dengan Konvensi Semantik OpenTelemetry GenAI.

Aktifkan Observabilitas (C#)

Untuk mengaktifkan pengamatan untuk klien obrolan Anda, Anda perlu membangun klien obrolan sebagai berikut:

// Using the AIProjectClient as an example
var instrumentedChatClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName) // Converts into a Microsoft.Extensions.AI.IChatClient
    .AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Warning

DefaultAzureCredential nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Untuk mengaktifkan pengamatan untuk agen Anda, Anda perlu membangun agen sebagai berikut:

var agent = new ChatClientAgent(
    instrumentedChatClient,
    name: "OpenTelemetryDemoAgent",
    instructions: "You are a helpful assistant that provides concise and informative responses.",
    tools: [AIFunctionFactory.Create(GetWeatherAsync)]
)
    .AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Penting

Saat mengaktifkan pengamatan untuk klien dan agen obrolan, Anda mungkin melihat informasi duplikat, terutama saat data sensitif diaktifkan. Konteks obrolan (termasuk perintah dan respons) yang diambil oleh klien obrolan dan agen akan disertakan dalam kedua rentang. Bergantung pada kebutuhan Anda, Anda dapat memilih untuk mengaktifkan pengamatan hanya pada klien obrolan atau hanya pada agen untuk menghindari duplikasi. Lihat Konvensi Semantik GenAI untuk detail selengkapnya tentang atribut yang diambil untuk LLM dan Agen.

Warning

Hanya aktifkan data sensitif dalam lingkungan pengembangan atau pengujian, karena mungkin mengekspos informasi pengguna dalam log dan jejak produksi. Data sensitif mencakup perintah, respons, argumen panggilan fungsi, dan hasil.

Configuration

Sekarang setelah klien dan agen obrolan Anda diinstrumentasikan, Anda dapat mengonfigurasi pengekspor OpenTelemetry untuk mengirim data telemetri ke backend yang Anda inginkan.

Traces

Untuk mengekspor jejak ke backend yang diinginkan, Anda dapat mengonfigurasi OpenTelemetry SDK dalam kode startup aplikasi Anda. Misalnya, untuk mengekspor jejak ke sumber daya Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
using System;

// The source name under which all activities, metrics, and logs will be emitted.
const string SourceName = "MyApplication";
const string ServiceName = "AgentOpenTelemetry";

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Tip

Metode AddSource ini digunakan untuk menentukan nama sumber yang akan didengarkan penyedia. Pastikan cocok dengan nama sumber yang Anda gunakan dalam kode instrumentasi Anda (misalnya, UseOpenTelemetry(sourceName: SourceName)). Jika nama sumber tidak ditentukan dalam kode instrumentasi, nama tersebut akan default ke Experimental.Microsoft.Agents.AI, dalam hal ini Anda harus menggunakan AddSource("Experimental.Microsoft.Agents.AI") di penyedia pelacak dan konfigurasi penyedia meter Anda.

Tip

Bergantung pada backend, Anda dapat menggunakan eksportir yang berbeda. Untuk informasi selengkapnya, lihat dokumentasi .NET OpenTelemetry. Untuk pengembangan lokal, pertimbangkan untuk menggunakan Dasbor Aspire.

Metrics

Demikian pula, untuk mengekspor metrik ke backend yang diinginkan, Anda dapat mengonfigurasi OpenTelemetry SDK dalam kode startup aplikasi Anda. Misalnya, untuk mengekspor metrik ke sumber daya Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using System;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Logs

Log diambil melalui kerangka kerja pengelogan yang Anda gunakan, misalnya Microsoft.Extensions.Logging. Untuk mengekspor log ke sumber daya Azure Monitor, Anda dapat mengonfigurasi penyedia pengelogan dalam kode startup aplikasi Anda:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Extensions.Logging;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter(options => options.ConnectionString = applicationInsightsConnectionString);
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    })
    .SetMinimumLevel(LogLevel.Debug);
});

// Create a logger instance for your application
var logger = loggerFactory.CreateLogger<Program>();

Dasbor Aspire

Pertimbangkan untuk menggunakan Dasbor Aspire sebagai cara cepat untuk memvisualisasikan jejak dan metrik Anda selama pengembangan. Untuk Mempelajari selengkapnya, lihat Dokumentasi Dasbor Aspire. Dasbor Aspire menerima data melalui OpenTelemetry Collector, yang dapat Anda tambahkan ke penyedia pelacak Anda sebagai berikut:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

Memulai Langkah Pertama

Lihat contoh lengkap agen dengan OpenTelemetry yang diaktifkan di repositori Kerangka Kerja Agen.

Tip

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Ketergantungan

Paket yang disertakan

Untuk mengaktifkan pengamatan di aplikasi Python Anda, paket OpenTelemetry berikut diinstal secara default:

Eksportir

Kami tidak menginstal pengekspor secara default untuk mencegah dependensi yang tidak perlu dan potensi masalah dengan instrumentasi otomatis. Ada banyak eksportir yang tersedia untuk backend yang berbeda, sehingga Anda dapat memilih yang paling sesuai dengan kebutuhan Anda.

Beberapa pengekspor umum yang mungkin ingin Anda instal berdasarkan kebutuhan Anda:

  • Untuk dukungan protokol gRPC: instal opentelemetry-exporter-otlp-proto-grpc
  • Untuk dukungan protokol HTTP: instal opentelemetry-exporter-otlp-proto-http
  • Untuk Azure Application Insights: instal azure-monitor-opentelemetry

Gunakan OpenTelemetry Registry untuk menemukan lebih banyak pengekspor dan paket instrumentasi.

Aktifkan Observability (Python)

Penyebaran jejak MCP

Setiap kali ada konteks rentang OpenTelemetry aktif, Agent Framework secara otomatis menyebarluaskan konteks pelacakan ke server MCP melalui params._meta bidang tools/call permintaan. Ini menggunakan penyebar OpenTelemetry yang dikonfigurasi secara global (W3C Trace Context secara default, memproduksi traceparent dan tracestate), sehingga penyebar kustom (B3, Jaeger, dll.) juga didukung. Ini memungkinkan pelacakan terdistribusi di seluruh batas agen-ke-MCP-server, sesuai dengan spesifikasi MCP_meta.

Cakupan: injeksi otomatis _meta hanya berlaku untuk sesi MCP yang dibuka oleh proses agen itu sendiri — MCPStreamableHTTPTool, , MCPStdioTooldan MCPWebsocketTool (atau subkelas lain yang dibuka MCPTool klien). Ini tidak berlaku untuk konfigurasi alat MCP yang dihosting/dikelola penyedia seperti FoundryChatClient.get_mcp_tool(...), , OpenAIChatClient.get_mcp_tool(...), AnthropicClient.get_mcp_tool(...), GeminiChatClient.get_mcp_tool(...)atau kotak alat agen yang dihosting Foundry, karena dalam kasus tersebut tools/call pesan dikeluarkan oleh runtime layanan penyedia daripada oleh proses agen. Akibatnya, kerangka kerja tidak memiliki kesempatan untuk menyuntikkan konteks pelacakan ke dalam permintaan tersebut, dan menyebar traceparent/tracestate ke seluruh batas layanan yang dihosting adalah tanggung jawab runtime layanan, bukan Kerangka Kerja Agen. Jika pelacakan terdistribusi end-to-end ke server MCP hilir diperlukan, gunakan transportasi MCP yang dibuka klien alih-alih konektor yang dihosting.

Lima pola untuk mengonfigurasi pengamatan

Kami telah mengidentifikasi beberapa cara untuk mengonfigurasi pengamatan dalam aplikasi Anda, tergantung pada kebutuhan Anda:

Pendekatan paling sederhana - konfigurasikan semuanya melalui variabel lingkungan:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Atau jika Anda hanya ingin pengekspor konsol, atur ENABLE_CONSOLE_EXPORTERS variabel lingkungan:

ENABLE_CONSOLE_EXPORTERS=true

from agent_framework.observability import configure_otel_providers

# Console exporters are enabled via the ENABLE_CONSOLE_EXPORTERS env var
configure_otel_providers()

2. Pengekspor Kustom

Untuk kontrol lebih atas eksportir, buat sendiri dan berikan ke configure_otel_providers():

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from agent_framework.observability import configure_otel_providers

# Create custom exporters with specific configuration
exporters = [
    OTLPSpanExporter(endpoint="http://localhost:4317", compression=Compression.Gzip),
    OTLPLogExporter(endpoint="http://localhost:4317"),
    OTLPMetricExporter(endpoint="http://localhost:4317"),
]

# These will be added alongside any exporters from environment variables
configure_otel_providers(exporters=exporters, enable_sensitive_data=True)

3. Penyiapan pihak ketiga

Banyak paket OpenTelemetry pihak ketiga memiliki metode penyiapannya sendiri. Anda dapat menggunakan metode tersebut terlebih dahulu, lalu memanggil enable_instrumentation() untuk mengaktifkan jalur kode instrumentasi Kerangka Kerja Agen:

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

# Configure Azure Monitor first
configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),  # Uses OTEL_SERVICE_NAME, etc.
    enable_live_metrics=True,
)

# Then activate Agent Framework's telemetry code paths
# This is optional if ENABLE_INSTRUMENTATION and/or ENABLE_SENSITIVE_DATA are set in env vars
enable_instrumentation(enable_sensitive_data=False)

Untuk Langfuse:

from agent_framework.observability import enable_instrumentation
from langfuse import get_client

langfuse = get_client()

# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")

# Then activate Agent Framework's telemetry code paths
enable_instrumentation(enable_sensitive_data=False)

4. Penyiapan manual

Untuk kontrol penuh, Anda dapat menyiapkan pengekspor, penyedia, dan instrumentasi secara manual. Gunakan fungsi create_resource() pembantu untuk membuat sumber daya dengan nama dan versi layanan yang sesuai. Lihat dokumentasi Python OpenTelemetry untuk panduan terperinci tentang instrumentasi manual.

5. Instrumentasi otomatis (kode nol)

Gunakan alat OpenTelemetry CLI untuk melengkapi aplikasi Anda secara otomatis tanpa perubahan kode:

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name your-service-name \
    --exporter_otlp_endpoint 0.0.0.0:4317 \
    python agent_framework_app.py

Lihat dokumentasi Python OpenTelemetry Zero untuk informasi selengkapnya.

Menggunakan pelacak dan meter

Setelah pengamatan dikonfigurasi, Anda dapat membuat rentang atau metrik kustom:

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # do something
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Ini adalah pembungkus API OpenTelemetry yang mengembalikan pelacak atau meter dari penyedia global, dengan agent_framework ditetapkan sebagai nama pustaka instrumentasi secara default.

Variabel lingkungan

Variabel lingkungan berikut mengontrol pengamatan Agent Framework:

  • ENABLE_INSTRUMENTATION - Defaultnya adalah true; diatur ke false untuk menonaktifkan instrumentasi OpenTelemetry.
  • ENABLE_SENSITIVE_DATA - Defaultnya adalah false, atur ke true untuk mengaktifkan pengelogan data sensitif (perintah, respons, argumen panggilan fungsi, dan hasil). Berhati-hatilah dengan pengaturan ini karena mungkin mengekspos data sensitif.
  • ENABLE_CONSOLE_EXPORTERS - Defaultnya adalah false, diatur ke true untuk mengaktifkan output konsol untuk telemetri.
  • VS_CODE_EXTENSION_PORT - Port untuk toolkit AI atau integrasi ekstensi Microsoft Foundry VS Code.

Agent Framework juga menambahkan paket dan versinya ke User-Agent permintaan klien yang didukung. Jalur permintaan Microsoft Foundry dan Azure OpenAI yang disetujui dapat menyertakan token penggunaan fitur di seluruh proses yang mengodekan kategori fitur kerangka kerja, bukan konten permintaan atau respons. Atur variabel ini sebelum memulai proses:

  • AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true - Hanya menonaktifkan token penggunaan fitur dan menyimpan paket/versi User-Agent.
  • AGENT_FRAMEWORK_USER_AGENT_DISABLED=true - Menonaktifkan seluruh Kontribusi User-Agent Kerangka Kerja Agen, termasuk token fitur.

Warning

Informasi sensitif mencakup perintah, respons, dan banyak lagi, dan hanya boleh diaktifkan dalam lingkungan pengembangan atau pengujian. Tidak disarankan untuk mengaktifkan ini dalam produksi karena dapat mengekspos data sensitif.

Variabel lingkungan OpenTelemetry Standar

Fungsi ini configure_otel_providers() secara otomatis membaca variabel lingkungan OpenTelemetry standar:

Konfigurasi OTLP (untuk Dasbor Aspire, Jaeger, dll.):

  • OTEL_EXPORTER_OTLP_ENDPOINT - Titik akhir dasar untuk semua sinyal (misalnya, http://localhost:4317)
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Titik akhir khusus jejak (menimpa basis)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Titik akhir khusus metrik (basis penimpaan)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Titik akhir khusus log (menggantikan basis)
  • OTEL_EXPORTER_OTLP_PROTOCOL - Protokol untuk digunakan (grpc atau http, default: grpc)
  • OTEL_EXPORTER_OTLP_HEADERS - Header untuk semua sinyal (misalnya, key1=value1,key2=value2)

Identifikasi Layanan:

  • OTEL_SERVICE_NAME - Nama layanan (default: agent_framework)
  • OTEL_SERVICE_VERSION - Versi layanan (default: versi paket)
  • OTEL_RESOURCE_ATTRIBUTES - Atribut sumber daya tambahan

Lihat spesifikasi OpenTelemetry untuk detail selengkapnya.

penyiapan Microsoft Foundry

Microsoft Foundry memiliki dukungan bawaan untuk melacak dengan visualisasi untuk rentang Anda.

Pastikan Anda memiliki Foundry yang dikonfigurasi dengan instans Azure Monitor, lihat details

Instal paket azure-monitor-opentelemetry:

pip install azure-monitor-opentelemetry

Mengonfigurasi pengamatan langsung dari FoundryChatClient

Untuk proyek Foundry, Anda dapat mengonfigurasi observabilitas langsung dari FoundryChatClient:

import os

from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=credential,
        )

        # Automatically configures Azure Monitor with the connection string from the Foundry project
        await client.configure_azure_monitor(enable_live_metrics=True)

Tip

Argumen untuk client.configure_azure_monitor() diteruskan ke fungsi configure_azure_monitor() yang mendasar dari paket azure-monitor-opentelemetry, lihat dokumentasi untuk detailnya, kami mengurus pengaturan string koneksi dan sumber daya.

Mengonfigurasi azure monitor dan mengaktifkan instrumentasi secara opsional

Untuk proyek non-Foundry dengan Application Insights, pastikan Anda menyiapkan agen kustom di Foundry, lihat detailnya.

Kemudian jalankan agen Anda dengan ID agen OpenTelemetry yang sama seperti yang terdaftar di Foundry, dan konfigurasikan azure monitor sebagai berikut:

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

configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),
    enable_live_metrics=True,
)
# optional if you do not have ENABLE_INSTRUMENTATION in env vars
enable_instrumentation()

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

Dasbor Aspire

Untuk pengembangan lokal tanpa penyiapan Azure, Anda dapat menggunakan DasborAspire, yang berjalan secara lokal melalui Docker dan memberikan pengalaman melihat telemetri yang sangat baik.

Menyiapkan Dasbor Aspire dengan Docker

# Pull and run the Aspire Dashboard container
docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:latest

Perintah ini akan memulai dasbor dengan:

  • UI Web: Tersedia di http://localhost:18888
  • Titik akhir OTLP: Tersedia untuk http://localhost:4317 aplikasi Anda untuk mengirim data telemetri

Mengonfigurasi aplikasi Anda

Atur variabel lingkungan berikut:

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

Atau sertakan dalam file Anda .env dan pastikan Anda memanggil load_dotenv() di awal aplikasi Anda (Agent Framework tidak secara otomatis memuat .env file).

Setelah sampel Anda selesai berjalan, navigasikan ke http://localhost:18888 di browser web untuk melihat data telemetri. Ikuti panduan eksplorasi Dasbor Aspire untuk mengautentikasi ke dasbor dan mulai menjelajahi jejak, log, dan metrik Anda.

Rentang dan metrik

Setelah semuanya diatur, Anda akan mulai melihat rentang dan metrik yang dibuat secara otomatis untuk Anda, rentangnya adalah:

  • invoke_agent <agent_name>: Ini adalah rentang tingkat atas untuk setiap pemanggilan agen, itu akan berisi semua rentang lain sebagai anak-anak.
  • chat <model_name>: Rentang ini dibuat ketika agen memanggil model obrolan yang mendasar, itu akan berisi perintah dan respons sebagai atribut, jika enable_sensitive_data diatur ke True.
  • execute_tool <function_name>: Rentang ini dibuat ketika agen memanggil alat fungsi, itu akan berisi argumen fungsi dan hasilnya sebagai atribut, jika enable_sensitive_data diatur ke True.

Metrik yang dibuat adalah:

  • Untuk klien obrolan dan chat operasi:

    • gen_ai.client.operation.duration (histogram): Metrik ini mengukur durasi setiap operasi, dalam hitungan detik.
    • gen_ai.client.token.usage (histogram): Metrik ini mengukur penggunaan token, dalam jumlah token.

  • Untuk pemanggilan fungsi selama execute_tool operasi:

    • agent_framework.function.invocation.duration (histogram): Metrik ini mengukur durasi setiap eksekusi fungsi, dalam hitungan detik.

Contoh output pelacakan

Saat menjalankan agen dengan pengamatan diaktifkan, Anda akan melihat data pelacakan yang mirip dengan output konsol berikut:

{
    "name": "invoke_agent Joker",
    "context": {
        "trace_id": "0xf2258b51421fe9cf4c0bd428c87b1ae4",
        "span_id": "0x2cad6fc139dcf01d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-09-25T11:00:48.663688Z",
    "end_time": "2025-09-25T11:00:57.271389Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.system": "openai",
        "gen_ai.agent.id": "Joker",
        "gen_ai.agent.name": "Joker",
        "gen_ai.request.instructions": "You are good at telling jokes.",
        "gen_ai.response.id": "chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5",
        "gen_ai.usage.input_tokens": 26,
        "gen_ai.usage.output_tokens": 29
    }
}

Jejak ini menunjukkan:

  • Pengidentifikasi pelacakan dan rentang: Untuk menghubungkan operasi terkait
  • Informasi waktu: Saat operasi dimulai dan berakhir
  • Metadata agen: ID Agen, nama, dan instruksi
  • Informasi model: Sistem AI yang digunakan (OpenAI) dan ID respons
  • Penggunaan token: Jumlah token input dan output untuk pelacakan biaya

Samples

Ada sejumlah sampel di repositori microsoft/agent-framework yang menunjukkan kemampuan ini. Untuk informasi selengkapnya, lihat folder sampel pengamatan. Folder itu mencakup sampel untuk menggunakan telemetri nol kode juga.

Contoh lengkap

# Copyright (c) Microsoft. All rights reserved.

import asyncio
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.observability import configure_otel_providers, get_tracer
from agent_framework.openai import OpenAIChatClient
from opentelemetry.trace import SpanKind
from opentelemetry.trace.span import format_trace_id
from pydantic import Field

"""
This sample shows how you can observe an agent in Agent Framework by using the
same observability setup function.
"""


# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
async def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    await asyncio.sleep(randint(0, 10) / 10.0)  # Simulate a network call
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


async def main():
    # calling `configure_otel_providers` will *enable* tracing and create the necessary tracing, logging
    # and metrics providers based on environment variables.
    # See the .env.example file for the available configuration options.
    configure_otel_providers()

    questions = ["What's the weather in Amsterdam?", "and in Paris, and which is better?", "Why is the sky blue?"]

    with get_tracer().start_as_current_span("Scenario: Agent Chat", kind=SpanKind.CLIENT) as current_span:
        print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}")

        agent = Agent(
            client=OpenAIChatClient(),
            tools=get_weather,
            name="WeatherAgent",
            instructions="You are a weather assistant.",
            id="weather-agent",
        )
        thread = agent.create_session()
        for question in questions:
            print(f"\nUser: {question}")
            print(f"{agent.name}: ", end="")
            async for update in agent.run(
                question,
                session=thread,
                stream=True,
            ):
                if update.text:
                    print(update.text, end="")


if __name__ == "__main__":
    asyncio.run(main())

Observabilitas dengan OpenTelemetry

Go Agent Framework menyertakan middleware OpenTelemetry yang secara otomatis melacak pemanggilan agen.

Siapkan

import (
    "github.com/microsoft/agent-framework-go/provider/otelprovider"

    "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    otellib "go.opentelemetry.io/otel"
)

// Create a tracer provider with a console exporter
exporter, _ := stdouttrace.New(stdouttrace.WithPrettyPrint())
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
defer tp.Shutdown(context.Background())
otellib.SetTracerProvider(tp)

Menambahkan middleware ke agen Anda

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Middlewares: []agent.Middleware{
            otelprovider.NewMiddleware(otelprovider.MiddlewareConfig{}), // OpenTelemetry tracing
        },
    },
})

Middleware memancarkan rentang dengan atribut termasuk:

  • gen_ai.provider.name — Nama penyedia (misalnya, "openai")
  • gen_ai.agent.id — ID unik agen
  • gen_ai.agent.name — Nama tampilan agen
  • gen_ai.agent.description — Deskripsi agen

Tip

Lihat sampel lengkap untuk contoh lengkap yang dapat dijalankan.

Gunakan pengamatan dengan Harness Agent

Untuk agen biasa, tambahkan OpenTelemetry ke alur klien obrolan atau agen dengan UseOpenTelemetry atau WithOpenTelemetry, seperti yang ditunjukkan sebelumnya. Menambahkan HarnessAgent instrumentasi OpenTelemetry klien obrolan dan agen secara default:

using Microsoft.Agents.AI;
using OpenTelemetry;
using OpenTelemetry.Trace;

const string SourceName = "MyApplication.Harness";

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(SourceName)
    .AddOtlpExporter()
    .Build();

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    OpenTelemetrySourceName = SourceName,
});

OpenTelemetrySourceName defaultnya adalah Experimental.Microsoft.Agents.AI. Nama yang diteruskan harus AddSource cocok dengannya. Atur DisableOpenTelemetry = true untuk menghilangkan kedua lapisan instrumentasi yang ditambahkan Harness.

Harness mengonfigurasi instrumentasi, tetapi Anda masih memiliki TracerProvider, pengekspor, kredensial, pembilasan, dan pematian. Jangan melakukan pra-instrumen klien obrolan yang sama lalu biarkan instrumentasi Harness diaktifkan kecuali Anda sengaja menginginkan rentang duplikat.

Telemetri berisi metadata secara default. Pengaturan OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true juga merekam perintah, respons, argumen alat, dan hasil alat; hanya aktifkan saat kebijakan pengekspor dan retensi sesuai untuk data tersebut.

HarnessAgent tersedia dari Microsoft.Agents.AI.Harness paket.

Instans biasa Agent sudah menyertakan lapisan telemetri; mengonfigurasi penyedia dan pengekspor OpenTelemetry dengan configure_otel_providers() atau penyiapan SDK OpenTelemetry Anda sendiri. create_harness_agent menggunakan konfigurasi global yang sama dan menetapkan nama penyedia khusus Harness:

from agent_framework import create_harness_agent
from agent_framework.observability import configure_otel_providers

configure_otel_providers()

agent = create_harness_agent(
    client=client,
    otel_provider_name="my.application.harness",
)

otel_provider_name mengontrol nama penyedia yang direkam pada telemetri Harness. Ini default ke microsoft.agent_framework.harness; tidak mengonfigurasi eksportir atau tujuan telemetri. Instrumentasi diaktifkan secara default, pengambilan data sensitif dinonaktifkan secara default, dan tidak ada pengekspor yang diinstal atau dikonfigurasi secara otomatis.

Penyedia OpenTelemetry adalah sumber daya di seluruh proses. Konfigurasikan sekali, amankan kredensial dan titik akhir pengekspor, dan bersihkan atau matikan sesuai dengan OpenTelemetry SDK dan pengekspor yang Anda pilih. Atur ENABLE_INSTRUMENTATION=false atau panggil disable_instrumentation() saat telemetri harus dinonaktifkan. Mengaktifkan ENABLE_SENSITIVE_DATA menambahkan pesan mentah, argumen alat, dan hasil alat.

create_harness_agent dirilis dalam agent-framework-core.

Go Harness paket saat ini tidak tersedia. Konfigurasikan middleware OpenTelemetry langsung pada agen Go biasa seperti yang ditunjukkan sebelumnya.

Langkah berikutnya

Keterampilan Agen

  • Last updated on