Aracılığıyla paylaş

Aracılar için izlenebilirliği etkinleştirme

Bu öğretici, bir aracı üzerinde OpenTelemetry'nin nasıl etkinleştirileceğini ve bu sayede aracı ile etkileşimlerin otomatik olarak kaydedilip dışa aktarılacağını gösterir. Bu öğreticide çıkış, OpenTelemetry konsol dışa aktarıcısı kullanılarak konsola yazılır.

Uyarı

Microsoft Agent Framework'ün izlediği standartlar hakkında daha fazla bilgi için bkz. Open Telemetry'den GenAI aracısı ve çerçeve kapsamları için Anlam Kuralları .

Önkoşullar

Önkoşullar için bu öğreticideki Basit bir aracı oluşturma ve çalıştırma adımına bakın.

NuGet paketlerini yükleme

Microsoft Agent Framework'ü Azure OpenAI ile kullanmak için aşağıdaki NuGet paketlerini yüklemeniz gerekir:

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

Konsola yazma desteğiyle birlikte OpenTelemetry desteği eklemek için şu ek paketleri yükleyin:

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

Uygulamanızda OpenTelemetry'yi etkinleştirme

Agent Framework telemetrisini etkinleştirin ve konsola aktaran bir OpenTelemetry TracerProvider oluşturun. İzlemelerin TracerProvider dışarı aktarılabilmesi için aracıyı çalıştırdığınız sırada etkin kalması gerekir.

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

Aracıyı oluşturma ve donatma

Bir aracı oluşturun ve oluşturucu desenini kullanarak kaynak adı sağlamak için UseOpenTelemetry çağrısı yapın. Dize değişmez değerinin agent-telemetry-source , izleyici sağlayıcısını oluştururken kullandığınız OpenTelemetry kaynak adı olduğunu unutmayın.

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

Temsilciyi çalıştır ve metin yanıtını yazdır. Console verileri dışa aktarıcı izleme verisini konsolda gösterir.

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

Beklenen çıkış, aracı çağırma izlemesinin ilk olarak gösterildiği ve ardından aracıdan gelen metin yanıtının gösterildiği şuna benzer olacaktır.

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

Sonraki Adımlar

Sürekli konuşmalar

Bu öğreticide, bir ajan üzerinde OpenTelemetry'nin hızlıca etkinleştirilmesi ve böylece ajanla etkileşimlerin otomatik olarak günlüğe kaydedilip dışa aktarılması gösterilmektedir.

Tüm yapılandırma seçenekleri, ortam değişkenleri ve gelişmiş senaryolar dahil olmak üzere gözlemlenebilirlik hakkında kapsamlı belgeler için Bkz. Gözlemlenebilirlik kullanıcı kılavuzu.

Önkoşullar

Önkoşullar için bu öğreticideki Basit bir aracı oluşturma ve çalıştırma adımına bakın.

Paketleri yükleme

Agent Framework'ü OpenTelemetry ile kullanmak için çerçeveyi yükleyin:

pip install agent-framework --pre

Geliştirme sırasında konsol çıkışı için ek paket gerekmez. Diğer dışarı verenler için, kullanıcı kılavuzundaki Bağımlılıklar bölümüne bakın.

Uygulamanızda OpenTelemetry'yi etkinleştirme

Gözlemlenebilirliği etkinleştirmenin en basit yolu kullanmaktır configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

Veya daha fazla esneklik için ortam değişkenlerini kullanın:

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

Ajenti oluştur ve çalıştır

Agent Framework kullanarak bir aracı oluşturun. Gözlemlenebilirlik, çağrıldıktan sonra configure_otel_providers() otomatik olarak etkinleştirilir.

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)

Konsol dışarı aktarma, aşağıdakine benzer izleme verilerini gösterir:

{
    "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 tümleştirmesi

Microsoft Foundry kullanıyorsanız Azure İzleyici'yi Application Insights ile otomatik olarak yapılandıran kullanışlı bir yöntem vardır. Önce Foundry projenizde Azure İzleyici'nin yapılandırıldığından emin olun (bkz. Uygulamaları izleme).

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)

Foundry gözlemlenebilirlik özellikli özel ajanlar

Foundry aracılığıyla oluşturulmayan özel aracılar için, bunları Foundry portalına kaydedebilir ve aynı OpenTelemetry aracı kimliğini kullanabilirsiniz. Kurulum yönergeleri için bkz Özel aracıyı kaydet.

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

İpucu

Daha ayrıntılı kurulum yönergeleri için, kullanıcı kılavuzundaki Microsoft Foundry kurulumu bölümüne bakın.

Sonraki Adımlar

Özel ihracat modülleri, üçüncü taraf entegrasyonları (Langfuse vb.), Aspire Kontrol Paneli kurulumu ve ayrıntılı izleme/ölçüm belgeleri gibi daha gelişmiş gözlemlenebilirlik senaryoları için Gözlemlenebilirlik kullanıcı kılavuzuna bakın.

Sürekli konuşmalar

  • Last updated on