Habilitando a observabilidade para 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 OpenTelemetry.

Observação

Para obter mais informações sobre os padrões seguidos pelo Microsoft Agent Framework, consulte Convenções Semânticas para agente genai e intervalos de estrutura da Telemetria Aberta.

Pré-requisitos

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

Instalar os 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 ao OpenTelemetry, 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 um OpenTelemetry TracerProvider que exporta para o console. O TracerProvider deve permanecer ativo enquanto você executa o agente, para que os traços 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 OpenTelemetry que você usou quando criou o provedor de rastreamento.

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 exibirá os dados de rastreamento no console.

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

A saída esperada será algo assim, em que 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óximas etapas

Armazenamento de conversas

Este tutorial mostra como habilitar rapidamente o OpenTelemetry em um agente para que as interações com o agente sejam automaticamente registradas e exportadas.

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

Pré-requisitos

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

Instalar pacotes

Para usar o Agent Framework com o OpenTelemetry, instale a estrutura:

pip install agent-framework --pre

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

Habilitar o OpenTelemetry em seu aplicativo

A maneira mais simples de habilitar a observabilidade é usando 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 use variáveis de ambiente para obter mais 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 é habilitada automaticamente assim que configure_otel_providers() é chamada.

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 de console mostrará dados de rastreamento 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 do Microsoft Foundry

Se você estiver usando o Microsoft Foundry, há um método conveniente que configura automaticamente o Azure Monitor com o Application Insights. Primeiro, verifique se o projeto do Foundry tem o Azure Monitor configurado (consulte aplicativos 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)

Agentes personalizados com a observabilidade do Foundry

Para agentes personalizados não criados por meio do Foundry, você pode registrá-los no portal do Foundry e usar a mesma ID do agente OpenTelemetry. Consulte Registrar agente personalizado para obter instruções de instalaçã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

Dica

Para obter instruções de instalação mais detalhadas, consulte a seção de instalação do Microsoft Foundry no guia do usuário.

Próximas etapas

Para cenários de observabilidade mais avançados, incluindo exportadores personalizados, integrações de terceiros (Langfuse, etc.), instalação do Aspire Dashboard e documentação detalhada de extensão/métrica, consulte o guia do usuário de Observabilidade.

Armazenamento de conversas