Habilitación de la observabilidad para agentes

En este tutorial se muestra cómo habilitar OpenTelemetry en un agente para que las interacciones con el agente se registren y exportan automáticamente. En este tutorial, la salida se escribe en la consola mediante el exportador de consola de OpenTelemetry.

Prerrequisitos

Para conocer los requisitos previos, consulte el paso Crear y ejecutar un agente sencillo en este tutorial.

Instalación de paquetes NuGet

Para usar Microsoft Agent Framework con Azure OpenAI, debe instalar los siguientes paquetes NuGet:

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

Para agregar también compatibilidad con OpenTelemetry, con compatibilidad para escribir en la consola, instale estos paquetes adicionales:

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

Habilitación de OpenTelemetry en la aplicación

Habilite la telemetría de Agent Framework y cree una openTelemetry TracerProvider que exporte a la consola. TracerProvider debe permanecer activo mientras ejecute el agente para que se exporten las trazas.

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

Creación e instrumentación del agente

Cree un agente y, utilizando el patrón de diseño 'builder', llame a UseOpenTelemetry para proporcionar un nombre de origen. Tenga en cuenta que el literal de cadena agent-telemetry-source es el nombre de origen de OpenTelemetry que usó al crear el proveedor de trazador.

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

Ejecute el agente e imprima la respuesta de texto. El exportador de la consola mostrará los datos de seguimiento en la consola.

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

La salida esperada será similar a esta, donde primero se muestra el seguimiento de invocación del agente, seguido de la respuesta de texto del agente.

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

Pasos siguientes

En este tutorial se muestra cómo habilitar rápidamente OpenTelemetry en un agente para que las interacciones con el agente se registren y exportan automáticamente.

Para obtener documentación completa sobre la observabilidad, incluidas todas las opciones de configuración, las variables de entorno y los escenarios avanzados, consulte la guía del usuario de observabilidad.

Prerrequisitos

Para conocer los requisitos previos, consulte el paso Crear y ejecutar un agente sencillo en este tutorial.

Instalación de paquetes

Para usar Agent Framework con OpenTelemetry, instale el marco:

pip install agent-framework --pre

Para la salida de la consola durante el desarrollo, no se necesitan paquetes adicionales. Para otros exportadores, consulte la sección Dependencias de la guía de usuario.

Habilitación de OpenTelemetry en la aplicación

La manera más sencilla de habilitar la observabilidad es usar configure_otel_providers():

from agent_framework.observability import configure_otel_providers

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

O bien, use variables de entorno para obtener más flexibilidad:

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

Creación y ejecución del agente

Cree un agente mediante Agent Framework. La observabilidad se habilita automáticamente una vez que se ha llamado configure_otel_providers().

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)

El exportador de la consola mostrará datos de seguimiento similares a los siguientes:

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

Integración de Microsoft Foundry

Si usa Microsoft Foundry, hay un método práctico que configura Automáticamente Azure Monitor con Application Insights. En primer lugar, asegúrese de que el proyecto foundry tiene configurado Azure Monitor (consulte Supervisión de aplicaciones).

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)

Agentes customizados con la observabilidad de Foundry

En el caso de los agentes personalizados no creados a través de Foundry, puede registrarlos en el portal de Foundry y usar el mismo identificador de agente de OpenTelemetry. Consulte Registro del agente personalizado para obtener instrucciones de configuración.

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

Pasos siguientes

Para ver escenarios de observabilidad más avanzados, incluidos exportadores personalizados, integraciones de terceros (Langfuse, etc.), configuración del panel aspire y documentación detallada sobre intervalos o métricas, consulte la guía del usuario de Observabilidad.