Permitindo a observabilidade para os agentes

Este tutorial mostra como habilitar o OpenTelemetry em um agente para que as interações com o agente sejam automaticamente registradas e exportadas. Neste tutorial, a saída é gravada no console usando o exportador de console OpenTelemetria.

Pré-requisitos

Para obter os pré-requisitos, consulte a etapa Criar e executar um agente simples neste tutorial.

Instalar pacotes NuGet

Para usar o Microsoft Agent Framework com o Azure OpenAI, você precisa instalar os seguintes pacotes NuGet:

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

Para também adicionar suporte a OpenTelemetria, com suporte para gravação no console, instale estes pacotes adicionais:

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

Habilitar o OpenTelemetry em seu aplicativo

Habilite a telemetria do Agent Framework e crie uma OpenTelemetry TracerProvider que exporta para o console. O TracerProvider deve permanecer ativo enquanto você executa o agente para que os rastreamentos sejam exportados.

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

Criar e instrumentar o agente

Crie um agente e, usando o padrão do construtor, chame UseOpenTelemetry para fornecer um nome de origem. Observe que o literal agent-telemetry-source da cadeia de caracteres é o nome de origem do OpenTelemetry que você usou quando criou o provedor de rastreador.

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

Execute o agente e imprima a resposta de texto. O exportador do console mostrará dados de rastreamento no console.

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

A saída esperada será algo assim, onde o rastreamento de invocação do agente é mostrado primeiro, seguido pela resposta de texto do 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"! ?????

Próximos passos

Este tutorial mostra como ativar rapidamente o OpenTelemetry num agente para que as interações com o agente sejam automaticamente registadas e exportadas.

Para documentação abrangente sobre observabilidade, incluindo todas as opções de configuração, variáveis de ambiente e cenários avançados, consulte o guia do utilizador da Observabilidade.

Pré-requisitos

Para obter os pré-requisitos, consulte a etapa Criar e executar um agente simples neste tutorial.

Instalar pacotes

Para usar o Agent Framework com OpenTelemetry, instale o framework:

pip install agent-framework --pre

Para a saída da consola durante o desenvolvimento, não é necessário nenhum pacote adicional. Para outros exportadores, consulte a secção Dependências no guia do utilizador.

Habilitar o OpenTelemetry em seu aplicativo

A forma mais simples de permitir a observabilidade é 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)

Ou usar variáveis de ambiente para maior flexibilidade:

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

Criar e executar o agente

Crie um agente usando o Agent Framework. A observabilidade é ativada automaticamente após configure_otel_providers() ser invocado.

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)

O exportador da consola mostrará dados de traço semelhantes a:

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

Integração com o Microsoft Foundry

Se estiver a usar o Microsoft Foundry, existe um método conveniente que configura automaticamente o Azure Monitor com o Application Insights. Primeiro, certifique-se de que o seu projeto Foundry tem o Azure Monitor configurado (ver Monitorizar aplicações).

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 aduaneiros com observabilidade Foundry

Para agentes personalizados que não foram criados através do Foundry, pode registá-los no portal do Foundry e usar o mesmo ID de agente OpenTelemetry. Consulte o agente de registo personalizado para instruções de configuração.

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

Próximos passos

Para cenários de observabilidade mais avançados, incluindo exportadores personalizados, integrações de terceiros (Langfuse, etc.), configuração do Aspire Dashboard e documentação detalhada de span/métricas, consulte o guia do utilizador da Observabilidade.