Partager via

Mise en place de l’observabilité pour les agents

Ce tutoriel montre comment activer OpenTelemetry sur un agent afin que les interactions avec l’agent soient automatiquement journalisées et exportées. Dans ce tutoriel, la sortie est écrite dans la console à l’aide de l’exportateur de console OpenTelemetry.

Note

Pour plus d’informations sur les normes suivies par Microsoft Agent Framework, consultez Conventions sémantiques pour l’agent GenAI et les étendues d’infrastructure à partir d’Open Telemetry.

Prerequisites

Pour connaître les prérequis, consultez l’étape Créer et exécuter un agent simple dans ce tutoriel.

Installer les packages NuGet

Pour utiliser Microsoft Agent Framework avec Azure OpenAI, vous devez installer les packages NuGet suivants :

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

Pour ajouter également le support d’OpenTelemetry, avec support de l’écriture dans la console, installez ces packages supplémentaires :

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

Activer OpenTelemetry dans votre application

Activez la télémétrie Agent Framework et créez une openTelemetry TracerProvider qui exporte vers la console. Le TracerProvider doit rester actif pendant que vous exécutez l’agent afin que les traces soient exportées.

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

Créer et instrumenter l’agent

Créez un agent et utilisez le modèle de générateur, appelez UseOpenTelemetry pour fournir un nom source. Notez que le littéral de chaîne de caractères agent-telemetry-source est le nom de la source OpenTelemetry que vous avez utilisé lorsque vous avez créé le fournisseur de traceur.

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

Exécutez l’agent et affichez la réponse textuelle. L’exportateur de console affiche les données de trace sur la console.

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

La sortie attendue est similaire à celle-ci, où la trace d’appel de l’agent est affichée en premier, suivie de la réponse textuelle de l’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"! ?????

Étapes suivantes

Maintien des conversations

Ce tutoriel montre comment activer rapidement OpenTelemetry sur un agent afin que les interactions avec l’agent soient automatiquement journalisées et exportées.

Pour obtenir une documentation complète sur l’observabilité, y compris toutes les options de configuration, les variables d’environnement et les scénarios avancés, consultez le guide de l’utilisateur observabilité.

Prerequisites

Pour connaître les prérequis, consultez l’étape Créer et exécuter un agent simple dans ce tutoriel.

Installer des packages

Pour utiliser Agent Framework avec OpenTelemetry, installez l’infrastructure :

pip install agent-framework --pre

Pour la sortie de la console pendant le développement, aucun package supplémentaire n’est nécessaire. Pour les autres exportateurs, consultez la section Dépendances dans le guide de l’utilisateur.

Activer OpenTelemetry dans votre application

La façon la plus simple d’activer l’observabilité consiste à utiliser configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

Vous pouvez également utiliser des variables d’environnement pour plus de flexibilité :

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

Créer et exécuter l’agent

Créez un agent à l’aide d’Agent Framework. L'observabilité est automatiquement activée une fois que configure_otel_providers() a été appelé.

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)

L’exportateur de console affiche des données de trace similaires à ce qui suit :

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

Intégration de Microsoft Foundry

Si vous utilisez Microsoft Foundry, il existe une méthode pratique qui configure automatiquement Azure Monitor avec Application Insights. Vérifiez d’abord que votre projet Foundry a configuré Azure Monitor (voir Applications Monitor).

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)

Agents sur mesure avec l'observabilité de Foundry

Pour les agents personnalisés non créés via Foundry, vous pouvez les inscrire dans le portail Foundry et utiliser le même ID d’agent OpenTelemetry. Consultez Inscrire un agent personnalisé pour obtenir des instructions d’installation.

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

Conseil / Astuce

Pour obtenir des instructions de configuration plus détaillées, consultez la section Configuration de Microsoft Foundry dans le guide de l’utilisateur.

Étapes suivantes

Pour des scénarios d’observabilité plus avancés, notamment les exportateurs personnalisés, les intégrations tierces (Langfuse, etc.), la configuration du tableau de bord Aspire et la documentation détaillée sur l’étendue/métrique, consultez le guide de l’utilisateur observabilité.

Maintien des conversations

  • Last updated on