Observabilidade do agente

Importante

Você precisa fazer parte do programa de versão preliminar do Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente com as inovações de IA mais recentes da Microsoft. As versões preliminares da Frontier estão sujeitas aos termos de versão preliminar existentes dos contratos de cliente. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Para participar do ecossistema Agent 365, adicione capacidades de Observabilidade do Agent 365 ao seu agente. O Agent 365 Observability se baseia no OpenTelemetry (OTel) e oferece uma estrutura unificada para capturar telemetria de forma consistente e segura em todas as plataformas de agentes. Ao implementar esse componente necessário, você permite que os administradores de TI monitorem a atividade do agente no centro de administração Microsoft e permitam que as equipes de segurança usem Defender e o Purview para conformidade e detecção de ameaças.

Principais benefícios

Visibilidade de ponta a ponta: capture telemetria abrangente para cada invocação de agente, incluindo sessões, chamadas de ferramentas e exceções, garantindo rastreabilidade total entre as plataformas.
Habilitação de segurança e conformidade: insira logs de auditoria unificados no Defender e Purview, permitindo cenários avançados de segurança e relatórios de conformidade para seu agente.
Flexibilidade multiplataforma: baseie-se nos padrões OTel e dê suporte a diversos runtimes e plataformas como Copilot Studio, Foundry e futuros frameworks de agentes.
Operational efficiency for admins: fornecer observabilidade centralizada em Centro de administração do Microsoft 365, reduzindo o tempo de solução de problemas e melhorando a governança com controles de acesso baseados em função para as equipes de TI que gerenciam seu agente.

Agentes com suporte

Os seguintes tipos de agente dão suporte à observabilidade do Agente 365:

Agentes habilitados para Microsoft Agent 365: use o SDK de observabilidade para instrumentar seu agente.
Agentes de motor personalizados: use o SDK de observabilidade para instrumentar seu agente.
Agentes declarativos: há suporte para a observabilidade pronta para uso. Nenhuma implementação do SDK é necessária.

Instalação

Use esses comandos para instalar os módulos de observabilidade para as linguagens suportadas pelo Agente 365.

Instale os principais pacotes de observabilidade e runtime. Todos os agentes que usam a Observabilidade do Agente 365 precisam desses pacotes.

pip install microsoft-agents-a365-observability-core
pip install microsoft-agents-a365-runtime

Se o agente usar o pacote Microsoft Agents Hosting, instale o pacote de integração de hospedagem. Ele fornece middleware que preenche automaticamente a bagagem e os escopos a partir do TurnContext, e inclui o armazenamento de tokens para o exportador de observabilidade.

pip install microsoft-agents-a365-observability-hosting

Se o agente usar uma das estruturas de IA com suporte, instale a extensão de instrumentação automática correspondente para capturar automaticamente a telemetria sem código de instrumentação manual. Para obter detalhes de configuração, consulte Instrumentação automática.

# For Semantic Kernel
pip install microsoft-agents-a365-observability-extensions-semantic-kernel

# For OpenAI Agents SDK
pip install microsoft-agents-a365-observability-extensions-openai

# For Microsoft Agent Framework
pip install microsoft-agents-a365-observability-extensions-agent-framework

# For LangChain
pip install microsoft-agents-a365-observability-extensions-langchain

Instale os principais pacotes de observabilidade e runtime. Todos os agentes que usam a Observabilidade do Agente 365 precisam desses pacotes.

npm install @microsoft/agents-a365-observability
npm install @microsoft/agents-a365-runtime

Se o agente usar o pacote de hospedagem de @microsoft/agentes , instale o pacote de integração de hospedagem. Ele fornece middleware que preenche automaticamente a bagagem e os escopos a partir do TurnContext, e inclui o armazenamento de tokens para o exportador de observabilidade.

npm install @microsoft/agents-a365-observability-hosting

// For OpenAI Agents SDK
npm install @microsoft/agents-a365-observability-extensions-openai

// For LangChain
npm install @microsoft/agents-a365-observability-extensions-langchain

Instale o pacote central de observabilidade e tempo de execução. Todos os agentes que usam a Observabilidade do Agente 365 precisam desse pacote.

dotnet add package Microsoft.Agents.A365.Observability.Runtime

Se o agente usar o Microsoft. Agents.A365.Observability.Hosting NuGet package, instale o pacote de integração de hospedagem. Ele fornece middleware que preenche automaticamente a bagagem e os escopos a partir do TurnContext, e inclui o armazenamento de tokens para o exportador de observabilidade.

dotnet add package Microsoft.Agents.A365.Observability.Hosting

// For Semantic Kernel
dotnet add package Microsoft.Agents.A365.Observability.Extensions.SemanticKernel

// For OpenAI
dotnet add package Microsoft.Agents.A365.Observability.Extensions.OpenAI

// For Agent Framework
dotnet add package Microsoft.Agents.A365.Observability.Extensions.AgentFramework

Configuração

Use as seguintes configurações para ativar e personalizar a Observabilidade do Agente 365 para seu agente.

Defina a ENABLE_A365_OBSERVABILITY_EXPORTER variável do ambiente como true para observalidade. Essa configuração exporta logs para o serviço e requer que seja fornecido um token_resolver. Caso contrário, o exportador de console é utilizado.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Implement secure token retrieval here
    return "Bearer <token>"

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_resolver,
)

O resolver de tokens é excluído do login no console.

Você pode personalizar o comportamento do exportador passando uma Agent365ExporterOptions instância para exporter_options. Quando exporter_options for fornecido, ele terá precedência sobre os parâmetros token_resolver e cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    exporter_options=Agent365ExporterOptions(
        cluster_category="prod",
        token_resolver=token_resolver,
    ),
    suppress_invoke_agent_input=True,
)

A tabela a seguir descreve os parâmetros opcionais para configure().

Parâmetro	Descrição	Default
`logger_name`	Nome do logger de Python usado para depuração e saída de log do console.	`microsoft_agents_a365.observability.core`
`exporter_options`	Uma `Agent365ExporterOptions` instância que configura o resolvedor de token e a categoria de cluster juntos.	`None`
`suppress_invoke_agent_input`	Quando `True`, suprime mensagens de entrada em trechos `InvokeAgent`.	`False`

A tabela a seguir descreve as propriedades opcionais para Agent365ExporterOptions.

Propriedade	Descrição	Default
`use_s2s_endpoint`	Quando `True`, usa o caminho do ponto de extremidade serviço-a-serviço.	`False`
`max_queue_size`	Tamanho máximo da fila para o processador de lote.	`2048`
`scheduled_delay_ms`	Atraso em milissegundos entre lotes de exportação.	`5000`
`exporter_timeout_ms`	Tempo limite em milissegundos para a operação de exportação.	`30000`
`max_export_batch_size`	Tamanho máximo do lote para operações de exportação.	`512`

Defina a ENABLE_A365_OBSERVABILITY_EXPORTER variável do ambiente como true para observalidade. Essa configuração exporta logs para o serviço e requer que um resolvedor de token seja fornecido. Caso contrário, o exportador de console é utilizado.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';

// Define a token resolver to authenticate with the observability service for exporting logs
const tokenResolver = (agentId, tenantId) => {
    // Your token resolution logic here
    return "your-token";
};

// Advanced configuration with builder pattern
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Como alternativa às variáveis de ambiente, você pode configurar a observabilidade programaticamente usando um provedor de configuração por meio do método withConfigurationProvider. Se você também usar métodos de construtor individuais (como withExporterOptions ou withClusterCategory), os métodos individuais do construtor têm precedência sobre os valores do provedor de configuração.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { ObservabilityConfiguration } from '@microsoft/agents-a365-observability';

const configProvider = new ObservabilityConfiguration({
  isObservabilityExporterEnabled: () => true,
  // Set log levels as pipe-separated values (for example, 'info|warn|error')
  observabilityLogLevel: () => 'info|warn|error',
});

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withConfigurationProvider(configProvider)
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Você pode personalizar o comportamento do exportador passando uma Agent365ExporterOptions instância para withExporterOptions. Essa opção permite controlar o envio em lote, os tempos limite e o modo de rota.

import {
  ObservabilityManager,
  Agent365ExporterOptions,
} from '@microsoft/agents-a365-observability';
import { ClusterCategory } from '@microsoft/agents-a365-runtime';

const exporterOptions = new Agent365ExporterOptions();
exporterOptions.maxQueueSize = 10;

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withClusterCategory(ClusterCategory.prod)
    .withExporterOptions(exporterOptions)
    .withTokenResolver(tokenResolver)
);

builder.start();

A tabela a seguir descreve as propriedades opcionais para Agent365ExporterOptions.

Propriedade	Descrição	Default
`useS2SEndpoint`	Quando `true`, usa o caminho do ponto de extremidade serviço-a-serviço.	`false`
`maxQueueSize`	Tamanho máximo da fila para o processador de lote.	`2048`
`scheduledDelayMilliseconds`	Atraso em milissegundos entre lotes de exportação.	`5000`
`exporterTimeoutMilliseconds`	Tempo limite em milissegundos para toda a operação de exportação.	`90000`
`httpRequestTimeoutMilliseconds`	Tempo limite em milissegundos para cada solicitação HTTP individual para o back-end.	`30000`
`maxExportBatchSize`	Tamanho máximo do lote para operações de exportação.	`512`

Você também pode fornecer um logger personalizado que implemente a ILogger interface (info, warn, error, event). Passe para o Builder usando withCustomLogger.

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withCustomLogger({
      info: (message, ...args) => { /* your logging logic */ },
      warn: (message, ...args) => { /* your logging logic */ },
      error: (message, ...args) => { /* your logging logic */ },
      event: (eventName, success, durationMs, message, details) => { /* your logging logic */ }
    })
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Definir EnableAgent365Exporter como true em appsettings.json.

No Program.cs, adicione Agent365ExporterOptions à coleção de serviços. Essa alteração configura o delegado que o exportador de rastreamento usa para recuperar o token.

Adicione dependências relacionadas à observabilidade usando AddA365Tracing().

using Microsoft.Agents.A365.Observability.Runtime;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

Você pode personalizar o comportamento do exportador passando um delegado de configuração e tipo de exportador para AddA365Tracing().

builder.AddA365Tracing(
    configure: tracingBuilder =>
    {
        // Use the builder to add extensions (e.g., WithSemanticKernel(), WithOpenAI())
    },
    agent365ExporterType: Agent365ExporterType.Agent365ExporterAsync
);

A tabela a seguir descreve as propriedades opcionais para Agent365ExporterOptions.

Propriedade	Descrição	Default
`UseS2SEndpoint`	Quando `true`, usa o caminho do ponto de extremidade serviço-a-serviço.	`false`
`MaxQueueSize`	Tamanho máximo da fila para o processador de lote.	`2048`
`ScheduledDelayMilliseconds`	Atraso em milissegundos entre lotes de exportação.	`5000`
`ExporterTimeoutMilliseconds`	Tempo limite em milissegundos para a operação de exportação.	`30000`
`MaxExportBatchSize`	Tamanho máximo do lote para operações de exportação.	`512`

Atributos de bagagem

Use BaggageBuilder para definir informações contextuais que se propagam por todos os trechos em uma requisição. O SDK implementa um SpanProcessor que copia todas as entradas de bagagem não vazias para novos intervalos sem sobrescrever atributos existentes.

from microsoft_agents_a365.observability.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

Para preencher automaticamente o BaggageBuilder a partir do TurnContext, use a função auxiliar populate no pacote microsoft-agents-a365-observability-hosting. Esse auxiliar extrai automaticamente os detalhes do chamador, agente, locatário, canal e conversa da atividade.

from microsoft_agents.hosting.core.turn_context import TurnContext
from microsoft_agents_a365.observability.core import BaggageBuilder
from microsoft_agents_a365.observability.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

import { BaggageBuilder } from '@microsoft/agents-a365-observability';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

Para preencher automaticamente o BaggageBuilder a partir do TurnContext, use a função auxiliar fromTurnContext no pacote @microsoft/agents-a365-observability-hosting. Esse auxiliar extrai automaticamente os detalhes do chamador, agente, locatário, canal e conversa da atividade.

import { BaggageBuilder } from '@microsoft/agents-a365-observability';
import { BaggageBuilderUtils } from '@microsoft/agents-a365-observability-hosting';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is auto-populated from the TurnContext activity
});

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

Para preencher automaticamente o BaggageBuilder do ITurnContext, use o método de extensão FromTurnContext no pacote Microsoft.Agents.A365.Observability.Hosting. Esse método extrai automaticamente os detalhes do chamador, agente, locatário, canal e conversa da atividade.

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

Middleware de bagagem

Se o agente usar o pacote de integração de hospedagem, registre o middleware de bagagem para preencher automaticamente a bagagem para cada solicitação de entrada. Esta etapa remove a necessidade de chamar BaggageBuilder manualmente em cada manipulador de atividades.

Registre BaggageMiddleware no conjunto do middleware do adaptador. Ele extrai automaticamente os detalhes de chamadas, agente, locatário, canal e conversa de cada entrada TurnContext e encapsula a solicitação em um escopo de bagagem.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Como alternativa, use ObservabilityHostingManager para configurar o middleware de bagagem junto com outros recursos de hospedagem:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

O middleware ignora a configuração de dados adicionais para respostas assíncronas (eventos ContinueConversation) para evitar substituir as informações que a solicitação de origem já estabeleceu.

Registre BaggageMiddleware no adaptador. Ele extrai automaticamente os detalhes de chamadas, agente, locatário, canal e conversa de cada entrada TurnContext e encapsula a solicitação em um escopo de bagagem.

import { BaggageMiddleware } from '@microsoft/agents-a365-observability-hosting';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

Como alternativa, use ObservabilityHostingManager para configurar o middleware de bagagem junto com outros recursos de hospedagem:

import { ObservabilityHostingManager } from '@microsoft/agents-a365-observability-hosting';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

Registre BaggageTurnMiddleware no adaptador. Ele extrai automaticamente os detalhes de chamadas, agente, locatário, canal e conversa de cada entrada ITurnContext e encapsula a solicitação em um escopo de bagagem.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

Se você precisar de bagagem de nível HTTP (por exemplo, para definir IDs de locatário e agente antes das execuções do pipeline do Bot Framework), registre ObservabilityBaggageMiddleware no pipeline do ASP.NET Core usando o método de extensão UseObservabilityRequestContext. Você deve fornecer uma função de resolvedor que extraia a ID do locatário e a ID do agente do contexto HTTP.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

Resolvedor de token

Ao usar o exportador do Agent 365, você deve fornecer uma função de resolvedor de token que retorna um token de autenticação. Ao usar o SDK de Observabilidade do Agent 365 com a estrutura de Hospedagem do Agente, você pode gerar tokens usando TurnContext das atividades do agente.

O snippet a seguir mostra como um token pode ser gerado usando o microsoft_agents.hosting.core SDK. O token de autenticação gerado aqui é usado para exportar os intervalos para o serviço de ingestão do A365. Os agentes são livres para gerar um token em si, por exemplo, usando a MSAL (Biblioteca de Autenticação da Microsoft), mas precisam garantir que o token tenha o escopo de observabilidade.

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

Para um agente criado com a CLI do AA365 que usar um colega de equipe de IA e o pacote Biblioteca de Hosting de Observabilidade do Microsoft Agent 365, use AgenticTokenCache para tratar o cache de tokens automaticamente. Registre o token uma vez por agente e locatário durante um manipulador de atividades e passe cache.get_observability_token como token_resolver na configuração de observabilidade.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

O snippet a seguir mostra como um token pode ser gerado usando o @microsoft/agents-hosting SDK. O token de autenticação gerado aqui é usado para exportar os intervalos para o serviço de ingestão do A365. Os agentes são livres para gerar um token em si, por exemplo, usando a MSAL (Biblioteca de Autenticação da Microsoft), mas precisam garantir que o token tenha o escopo de observabilidade.

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

const storage = new MemoryStorage();

export const agentApplication = new AgentApplication<ApplicationTurnState>({
  authorization: {
    agentic: {}, // We have the type and scopes set in the .env file
  },
  storage,
});

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const aauAuthToken = await agentApplication.authorization.exchangeToken(context, 'agentic', {
      scopes: getObservabilityAuthenticationScope()
    });
    // cache this auth token and return via token resolver
  }
);

Para um agente criado com a CLI do A365 que usa um colega de equipe de IA e o pacote @microsoft/agents-a365-observability-hosting, use AgenticTokenCacheInstance para tratar o cache de token automaticamente. Chame RefreshObservabilityToken uma vez por agente e locatário durante um manipulador de atividades e passe AgenticTokenCacheInstance.getObservabilityToken como o parâmetro tokenResolver na configuração de observabilidade.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-hosting';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

O snippet a seguir mostra como gerar um token usando o Microsoft.Agents SDK de hospedagem. Use o token de autenticação gerado para exportar os intervalos para o serviço de ingestão do A365. Os agentes podem gerar um token por conta própria, por exemplo, usando a MSAL (Biblioteca de Autenticação da Microsoft), mas precisam garantir que o token tenha o escopo de observabilidade.

Forneça um resolvedor de tokens registrando-se Agent365ExporterOptions com um TokenResolver Delegado. O delegado recebe o agentId e o tenantId e retorna um token de autenticação.

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Implement your token retrieval logic here
                return await GetTokenAsync(agentId, tenantId);
            }
        };
    });

Para um agente criado com a CLI A365 que usa um parceiro de IA e o pacote Microsoft.Agents.A365.Observability.Hosting NuGet, use o método AddAgenticTracingExporter() para lidar com o cache de token automaticamente por meio da injeção de dependência.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

No aplicativo do agente, registre o token.

using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App.UserAuth;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;
using System;
using System.Threading.Tasks;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct(
                    userAuthorization: UserAuthorization,
                    turnContext: turnContext,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Instrumentação automática

A instrumentação automática monitora automaticamente as estruturas do agente (SDKs), sinais de telemetria existentes para rastreamentos e os encaminha para o serviço de observabilidade do Agent 365. Esse recurso elimina a necessidade de os desenvolvedores escreverem código de monitoramento manualmente, simplifica a configuração e garante um acompanhamento consistente de desempenho.

Múltiplos SDKs e plataformas suportam auto-instrumentação:

Plataforma	SDKs/Frameworks suportados
.NET	Kernel Semântico, OpenAI, Agent Framework
Python	Kernel Semântico, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Observação

O suporte à auto-instrumentação varia conforme a plataforma e a implementação do SDK.

Núcleo Semântico

A instrumentação automotiva requer o uso de um construtor de bagagens. Defina o ID do agente e o ID do tenant usando BaggageBuilder.

Instale o pacote.

pip install microsoft-agents-a365-observability-extensions-semantic-kernel

Configurar a observabilidade

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

Adicione dependências à coleção de serviços.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;

builder.AddA365Tracing(configure: config => config.WithSemanticKernel());

Defina AgentId e TenantId usando BaggageBuilder. Certifique-se de que o ID que você usa ao criar um ChatCompletionAgent corresponde ao ID do agente que você passa para BaggageBuilder.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;
using Microsoft.Agents.A365.Observability.Runtime.Common;
public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      var chatCompletionAgent = new ChatCompletionAgent
      {
          // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. Should match above.
          Id = <your-agent-id>,
          ...
      };
    }
}

OpenAI

A instrumentação automotiva requer o uso de um construtor de bagagens. Defina o ID do agente e o ID do tenant usando BaggageBuilder.

Instale o pacote.

pip install microsoft-agents-a365-observability-extensions-openai

Configurar a observabilidade

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

Instale o pacote.

npm install @microsoft/agents-a365-observability-extensions-openai

Configurar a observabilidade

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { OpenAIAgentsTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-openai';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

Adicione dependências à coleção de serviços.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;

builder.AddA365Tracing(configure: config => config.WithOpenAI());

Defina AgentId e TenantId usando BaggageBuilder. Para chamadas de ferramenta, inicie um rastreamento usando Trace() em uma instância ChatToolCall.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      // NOTE: This will be the agent and tenant ID with which the TokenResolver delegate will be invoked. 
      using var scope = chatToolCall.Trace(agentId: <your-agent-id>, <your-tenant-id>);
    }
}

Estrutura do Agente

A instrumentação automotiva requer o uso de um construtor de bagagens. Defina o ID do agente e o ID do tenant usando BaggageBuilder.

Instale o pacote.

pip install microsoft-agents-a365-observability-extensions-agent-framework

Configurar a observabilidade

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.agentframework import (
    AgentFrameworkInstrumentor,
)

# Configure observability
configure(
    service_name="AgentFrameworkTracingWithAzureOpenAI",
    service_namespace="AgentFrameworkTesting",
)

# Enable auto-instrumentation
AgentFrameworkInstrumentor().instrument()

Adicione dependências à coleção de serviços.

using Microsoft.Agents.A365.Observability.Extensions.AgentFramework;

builder.AddA365Tracing(configure: config => config.WithAgentFramework());

Defina AgentId e TenantId usando BaggageBuilder.

using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
    }
}

Estrutura LangChain

Instrumentação automática requer o uso do criador de bagagem. Defina o ID do agente e o ID do tenant usando BaggageBuilder.

Instale o pacote.

pip install microsoft-agents-a365-observability-extensions-langchain

Configurar a observabilidade

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor

# Configure observability
configure(
    service_name="my-langchain-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

Instale o pacote.

npm install @microsoft/agents-a365-observability-extensions-langchain

Configurar a observabilidade

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { LangChainTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-langchain';
import * as LangChainCallbacks from '@langchain/core/callbacks/manager';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

sdk.start();

// Enable LangChain auto-instrumentation
LangChainTraceInstrumentor.instrument(LangChainCallbacks);

// Your LangChain code is now automatically traced

Instrumentação manual

Use o SDK de observabilidade do Agente 365 para entender o funcionamento interno do agente. O SDK fornece escopos que você pode iniciar: InvokeAgentScope, ExecuteToolScope, InferenceScope, e OutputScope.

Invocação do agente

Use esse escopo no início do processo do seu agente. Usando o escopo do agente de invocação, você pode capturar propriedades como o agente atual que está sendo invocado, dados do usuário do agente, entre outros.

from microsoft_agents_a365.observability.core import (
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    AgentDetails,
    CallerDetails,
    UserDetails,
    Channel,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="My Agent",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

request = Request(
    content="User asks a question",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

caller_details = CallerDetails(
    user_details=UserDetails(
        user_id="user-123",
        user_email="jane.doe@contoso.com",
        user_name="Jane Doe",
    ),
)

with InvokeAgentScope.start(request, scope_details, agent_details, caller_details):
    # Perform agent invocation logic
    response = call_agent(...)

import {
  InvokeAgentScope,
  InvokeAgentScopeDetails,
  AgentDetails,
  CallerDetails,
  UserDetails,
  Channel,
  Request,
  ServiceEndpoint,
} from '@microsoft/agents-a365-observability';

// Use the same agentDetails instance across all scopes in a request
const agentDetails: AgentDetails = {
  agentId: 'agent-456',
  agentName: 'Email Assistant',
  agentDescription: 'An AI agent powered by Azure OpenAI',
  agentAuid: 'auid-123',
  agentEmail: 'agent@contoso.com',
  agentBlueprintId: 'blueprint-789',
  tenantId: 'tenant-123',
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

// Use the same request instance across all scopes in a request
const request: Request = {
  content: 'Please help me organize my emails',
  sessionId: 'session-42',
  conversationId: 'conv-xyz',
  channel: { name: 'msteams' } as Channel,
};

// Optional: Caller details (human user, or agent-to-agent)
const callerDetails: CallerDetails = {
  userDetails: {
    userId: 'user-123',
    userEmail: 'jane.doe@contoso.com',
    userName: 'Jane Doe',
  } as UserDetails,
};

const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails);

try {
  await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);

    // Your agent invocation logic here
    const response = await invokeAgent(request.content);

    // Record output messages
    scope.recordOutputMessages(['I found 15 urgent emails', 'Here is your organized inbox']);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Se o agente usar o @microsoft/agents-a365-observability-hosting pacote, você poderá usar ScopeUtils.populateInvokeAgentScopeFromTurnContext para criar o escopo com detalhes do agente, detalhes do chamador e informações de canal derivadas automaticamente do TurnContext.

import { InvokeAgentScopeDetails, AgentDetails, ServiceEndpoint } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const agentDetails: AgentDetails = { agentId: 'agent-456' };
const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

const scope = ScopeUtils.populateInvokeAgentScopeFromTurnContext(
  agentDetails,
  scopeDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    // Agent details, caller details, and channel are auto-populated from context
    const response = await invokeAgent(context.activity.text);
    scope.recordOutputMessages([response]);
  });
} finally {
  scope.dispose();
}

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

        var scopeDetails = new InvokeAgentScopeDetails(
            endpoint: new Uri("https://myagent.contoso.com")
        );

        var request = new Request(
            content: userInput,
            sessionId: "session-abc",
            channel: new Channel("msteams"),
            conversationId: "conv-xyz"
        );

        var callerDetails = new CallerDetails(
            userDetails: new UserDetails(
                userId: "user-123",
                userEmail: "jane.doe@contoso.com",
                userName: "Jane Doe"
            )
        );

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            request: request,
            scopeDetails: scopeDetails,
            agentDetails: agentDetails,
            callerDetails: callerDetails
        );

        // Record input messages
        scope.RecordInputMessages(new[] { userInput });

        // ... your agent logic here ...

        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        return new AgentResponse { Content = output };
    }
}

public class AgentResponse
{
    public string Content { get; set; }
}

Execução de ferramentas

Os exemplos a seguir mostram como adicionar rastreamento de observabilidade à execução da ferramenta do seu agente. Esse rastreamento captura telemetria para fins de monitoramento e auditoria.

from microsoft_agents_a365.observability.core import (
    ExecuteToolScope,
    ToolCallDetails,
    Request,
    ServiceEndpoint,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=ServiceEndpoint(hostname="tools.contoso.com", port=8080),
)

with ExecuteToolScope.start(request, tool_details, agent_details) as scope:
    result = run_tool(tool_details)
    scope.record_response(result)

import { ExecuteToolScope, ToolCallDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com', limit: 10 }),
  toolCallId: 'tool-call-456',
  description: 'Search emails by criteria',
  toolType: 'function',
  endpoint: {
    host: 'tools.contoso.com',
    port: 8080,  // Will be recorded since not 443
    protocol: 'https'
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Execute the tool
    const result = await searchEmails(toolDetails.arguments);

    // Record the tool execution result
    scope.recordResponse(result);

    return result;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Se o agente usar o pacote @microsoft/agents-a365-observability-hosting, use ScopeUtils.populateExecuteToolScopeFromTurnContext para criar o escopo com os detalhes do agente derivados automaticamente do TurnContext.

import { ToolCallDetails } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com' }),
  toolCallId: 'tool-call-456',
  toolType: 'function',
};

const scope = ScopeUtils.populateExecuteToolScopeFromTurnContext(
  toolDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} finally {
  scope.dispose();
}

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

// ... your tool logic here ...

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

Inferência

Os exemplos a seguir mostram como instrumentar chamadas de inferência de modelos de IA com rastreamento de observabilidade para capturar o uso de tokens, detalhes do modelo e metadados de resposta.

from microsoft_agents_a365.observability.core import (
    InferenceScope,
    InferenceCallDetails,
    InferenceOperationType,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
)

with InferenceScope.start(request, inference_details, agent_details) as scope:
    completion = call_llm(...)
    scope.record_output_messages([completion.text])
    scope.record_input_tokens(completion.usage.input_tokens)
    scope.record_output_tokens(completion.usage.output_tokens)

import { InferenceScope, InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Summarize the following emails for me...']);

    // Call the LLM
    const response = await callLLM();

    // Record detailed telemetry with granular methods
    scope.recordOutputMessages(['Here is your email summary...']);
    scope.recordInputTokens(145);
    scope.recordOutputTokens(82);
    scope.recordFinishReasons(['stop']);

    return response.text;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Se o agente usar o @microsoft/agents-a365-observability-hosting pacote, você poderá usar ScopeUtils.populateInferenceScopeFromTurnContext para criar o escopo com detalhes do agente derivados automaticamente do TurnContext.

import { InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = ScopeUtils.populateInferenceScopeFromTurnContext(
  inferenceDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
  });
} finally {
  scope.dispose();
}

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

// ... your inference logic here ...

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

Saída

Use este escopo para cenários assíncronos onde InvokeAgentScope, ExecuteToolScope ou InferenceScope não possam capturar dados de saída sincronamente. Comece OutputScope como um intervalo filho para registrar as mensagens de saída finais após a conclusão do escopo pai.

from microsoft_agents_a365.observability.core import (
    OutputScope,
    Response,
    SpanDetails,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

# Get the parent context from the originating scope
parent_context = invoke_scope.get_context()

response = Response(messages=["Here is your organized inbox with 15 urgent emails."])

with OutputScope.start(
    request,
    response,
    agent_details,
    span_details=SpanDetails(parent_context=parent_context),
):
    # Output messages are recorded automatically from the response
    pass

import { OutputScope, OutputResponse, SpanDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
const parentContext = invokeScope.getSpanContext();

const response: OutputResponse = {
  messages: ['Here is your organized inbox with 15 urgent emails.'],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined, // userDetails
  { parentContext } as SpanDetails
);

// Output messages are recorded automatically from the response
scope.dispose();

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
var parentContext = invokeScope.GetActivityContext();

var response = new Response(new[] { "Here is your organized inbox with 15 urgent emails." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext)
);
// Output messages are recorded automatically from the response

Valide localmente

Para verificar se você integrou-se com sucesso ao SDK de observabilidade, examine os logs de console gerados pelo agente e os logs do SDK de observabilidade.

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Essa configuração exporta os spans (traces) para o console.

Para investigar falhas de exportação, habilite o log detalhado definindo ENABLE_A365_OBSERVABILITY_EXPORTER como true e configure o log de depuração na inicialização do aplicativo:

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("microsoft_agents_a365.observability.core").setLevel(logging.DEBUG)

# Or target only the exporter:
logging.getLogger(
    "microsoft_agents_a365.observability.core.exporters.agent365_exporter"
).setLevel(logging.DEBUG)

Mensagens importantes de log:

DEBUG  Token resolved for agent {agentId} tenant {tenantId}
DEBUG  Exporting {n} spans to {url}
DEBUG  HTTP 200 - correlation ID: abc-123
ERROR  Token resolution failed: {error}
ERROR  HTTP 401 exporting spans - correlation ID: abc-123
INFO   No spans with tenant/agent identity found; nothing exported.

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Essa configuração exporta os spans (traces) para o console.

Para investigar falhas de exportação, defina variáveis de ambiente no .env ou no shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Examine a saída do console para mensagens como:

[INFO]  [Agent365Exporter] Exporting 245 spans
[INFO]  [Agent365Exporter] Partitioned into 3 identity groups (2 spans skipped)
[INFO]  [Agent365Exporter] Token resolved successfully via tokenResolver
[EVENT] export-group succeeded in 98ms {"tenantId":"...","agentId":"...","correlationId":"abc-123"}
[ERROR] [Agent365Exporter] Failed with status 401, correlation ID: abc-123
[WARN]  export-partition-span-missing-identity: 5 spans skipped due to missing tenant or agent ID

Opcionalmente, use um logger personalizado para capturar eventos de exportação para um arquivo:

import { setLogger, ExporterEventNames } from '@microsoft/agents-a365-observability';

setLogger({
  info: (msg, ...args) => myLogger.info(msg, ...args),
  warn: (msg, ...args) => myLogger.warn(msg, ...args),
  error: (msg, ...args) => myLogger.error(msg, ...args),
  event: (eventType: ExporterEventNames, isSuccess: boolean, durationMs: number,
          message?: string, details?: Record<string, string>) => {
    myLogger.info({ eventType, isSuccess, durationMs, message, ...details });
  }
});

Definir EnableAgent365Exporter como false em appsettings.json. Essa configuração exporta os spans (traces) para o console.

Para investigar falhas de exportação, configure o log detalhado em appsettings.json:

{
  "EnableAgent365Exporter": "True",
  "Logging": {
    "LogLevel": {
      "Microsoft.Agents.A365.Observability": "Debug"
    }
  }
}

Ou defina variáveis de ambiente:

EnableAgent365Exporter=True
A365_OBSERVABILITY_DOMAIN_OVERRIDE=https://your-test-endpoint.example.com
A365_OBSERVABILITY_SCOPE_OVERRIDE=https://api.powerplatform.com/.default

Mensagens importantes de log:

info: Agent365ExporterCore: Obtained token for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: Sending {count} spans to {requestUri} for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: HTTP {statusCode} exporting spans. 'x-ms-correlation-id': '{correlationId}'.
error: Agent365Exporter: Exception exporting spans: {exception}
warn: Agent365ExporterCore: No token obtained for agent {agentId} tenant {tenantId}. Skipping export.

Observação

Se você não registrar um ILoggerFactory no DI, o exportador reverterá automaticamente para um logger do console.

Exibindo logs exportados

Para exibir a telemetria do agente em Microsoft Purview ou Microsoft Defender, verifique se os seguintes requisitos foram atendidos:

Microsoft Purview: a auditoria deve ser ativada para sua organização. Para obter instruções, consulte Ativar ou desativar a auditoria.
Microsoft Defender: a busca avançada deve ser configurada para acessar a tabela CloudAppEvents. Para obter detalhes, consulte a tabela CloudAppEvents no esquema de busca avançado.

Validar para publicação em lojas

Importante

Para validação bem-sucedida da loja, seu agente deve implementar os escopos InvokeAgentScope, InferenceScope e ExecuteToolScope. Esses três escopos são necessários para publicação.

Antes de publicar, use logs de console para validar sua integração de observabilidade para o agente, implementando os escopos necessários de invoke agent, execute tool, inference e output. Depois, compare os logs do seu agente com as seguintes listas de atributos para verificar se todos os atributos necessários estão presentes. Capture atributos em cada escopo ou através do criador de contexto, e inclua atributos opcionais segundo seu critério.

Para mais informações sobre os requisitos de publicação em loja, consulte as diretrizes de validação da loja.

atributos de `InvokeAgentScope`

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um InvokeAgentScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "microsoft.a365.caller.agent.blueprint.id": "Optional",
        "microsoft.a365.caller.agent.id": "Optional",
        "microsoft.a365.caller.agent.name": "Optional",
        "microsoft.a365.caller.agent.platform.id": "Optional",
        "microsoft.a365.caller.agent.user.email": "Optional",
        "microsoft.a365.caller.agent.user.id": "Optional",
        "microsoft.a365.caller.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "server.address": "Required",
        "server.port": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

atributos de `ExecuteToolScope`

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um ExecuteToolScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.tool.call.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.call.result": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

atributos de `InferenceScope`

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um InferenceScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.a365.agent.thought.process": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "gen_ai.provider.name": "Required",
        "gen_ai.request.model": "Required",
        "gen_ai.response.finish_reasons": "Optional",
        "gen_ai.usage.input_tokens": "Optional",
        "gen_ai.usage.output_tokens": "Optional",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.tenant.id": "Required"
    }

atributos de `OutputScope`

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um OutputScope. Use esse escopo para cenários assíncronos em que o escopo pai não pode capturar dados de saída de forma síncrona.

"attributes": {
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

Teste seu agente com observabilidade

Depois de implementar a observabilidade em seu agente, teste-a para garantir que ela capture a telemetria corretamente. Siga o guia de testes para configurar seu ambiente. Em seguida, concentre-se principalmente na seção Exibir logs de observabilidade para validar se sua implementação de observabilidade está funcionando conforme o esperado.

Verificação:

Acesse: https://admin.cloud.microsoft/#/agents/all
Selecione sua agente > Atividade
Você vê sessões e invocações de ferramentas

Resolução de problemas

Esta seção descreve problemas comuns ao implementar e utilizar observabilidade.

Dica

O Guia de Solução de Problemas do Agente 365 contém recomendações de resolução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de desenvolvimento do Agente 365.

Os dados de observabilidade não aparecem

Sintomas:

O agente está correndo
Sem telemetria no centro administrativo
Não consigo ver a atividade dos agentes

Causa raiz:

A observabilidade não é ativada
Erros de configuração
Problemas do resolvedor de tokens

Soluções: Tente os seguintes passos para resolver o problema:

Verificar se o exportador de observabilidade está habilitado

Você deve habilitar explicitamente o exportador do Agente 365. Quando desabilitado, o SDK volta para um exportador de console e a telemetria não é enviada ao serviço. Para obter detalhes de configuração, consulte Configuração.
Verifique a configuração do resolver de tokens

O exportador requer um resolvedor de token válido que retorna um token de portador para cada solicitação de exportação. Se o resolvedor de token estiver ausente ou retornar null, a exportação será ignorada silenciosamente. Certifique-se de que seu código implementa corretamente o resolvedor de tokens. Para obter detalhes, consulte Resolvedor de tokens.
Verifique se há erros nos logs

Habilite o log detalhado e use o comando az webapp log tail para procurar nos logs erros relacionados à observabilidade. Para obter detalhes sobre como habilitar o logging para cada plataforma, consulte Validar localmente.
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
Verificar exportação de telemetria

Confirme que a telemetria foi gerada e exportada conforme esperado.
- Adicione um exportador de console e verifique se a telemetria é gerada localmente. Para obter detalhes sobre como usar o exportador de console e validar a saída, consulte Validar localmente.

ID do locatário ou ID do agente ausente – intervalos ignorados

Sintomas: o sistema descarta silenciosamente intervalos e nunca os exporta. Alguns SDKs registram uma contagem de intervalos ignorados ou uma mensagem como "Nenhum intervalo com a identificação de locatário/agente encontrada". Outros os descartam sem registrar.

Resolução:

Antes da exportação, as partições do SDK abrangem a identidade do locatário e do agente. O sistema descarta segmentos que não têm uma ID de locatário ou uma ID de agente e nunca os envia para o serviço.
Verifique se BaggageBuilder está configurado com a ID do locatário e a ID do agente antes de criar intervalos. Esses valores se propagam por meio do contexto OpenTelemetry e são anexados a todos os intervalos criados dentro do escopo da bagagem. Para a API específica da plataforma, consulte Atributos de bagagem.
Confirme se a atividade TurnContext tem um destinatário válido com a identidade do agente, caso você use o middleware de bagagem ou o auxiliar de contexto do pacote de integração de hospedagem para preencher essas IDs.

Falha no processamento de token – exportação ignorada ou não autorizada

Sintomas: O resolvedor de token retorna null ou gera um erro. Dependendo do SDK, a exportação é totalmente ignorada ou a solicitação é enviada sem um cabeçalho de autorização e falha com HTTP 401.

Resolução:

O resolvedor de token é necessário na inicialização. Se ele estiver ausente, o exportador gerará um erro na inicialização. Verifique se um resolvedor de token é fornecido e retorna um token de portador válido.
Verifique se a ID do locatário correta e a ID do agente são usadas para BaggageBuilder, porque esses valores são passados para o resolvedor de token.
Para agentes hospedados Azure, verifique se a Identidade Gerenciada tem a permissão de API necessária para o escopo de observabilidade.

HTTP 401 Não Autorizado

Sintomas: A exportação falha com HTTP 401. O exportador não tenta novamente esse erro.

Resolução:

Verifique se o público-alvo do token corresponde ao escopo do ponto de extremidade de observabilidade.
Verifique se o resolvedor de token não está retornando um token de usuário delegado, um token para um público-alvo incorreto ou um token expirado.

HTTP 403 Proibido

Sintomas: A exportação falha com HTTP 403. O exportador não tenta novamente esse erro.

Causa raiz: Um erro HTTP 403 pode ter causas diferentes. Verifique as resoluções a seguir na ordem correta.

Resolução:

Missing license — verifique se seu locatário tem uma das seguintes licenças atribuídas no Centro de administração do Microsoft 365:
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
Permissão ausente Agent365.Observability.OtelWrite – se você atualizou recentemente seus pacotes de observabilidade, precisará conceder essa permissão. Veja a observação importante abaixo.

Importante

A atualização de agentes existentes para essas versões de pacote exige uma etapa extra

Esta etapa se aplicará somente se você estiver atualizando um agente existente. As novas instalações do agente não exigem essa etapa. Se você estiver atualizando para as seguintes versões de pacote ou mais recentes, deverá conceder a nova Agent365.Observability.OtelWrite permissão à sua identidade (Identidade Gerenciada ou registro de aplicativo). Sem essa permissão, a exportação de telemetria falha com HTTP 403.

Plataforma	Versão mínima que exige esta etapa
.NET	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

Conceda a permissão usando uma das opções a seguir.

Option A – CLI do Agente 365 (requer a365.config.json e a365.generated.config.json no diretório de configuração, uma conta de Administrador Global e Agent 365 CLI v1.1.139-preview ou posterior)

a365 setup admin --config-dir "<path-to-config-dir>"

Esse comando concede todas as permissões ausentes, incluindo os novos escopos de Observabilidade.

Opção B — Portal entra (nenhum arquivo de configuração necessário; requer acesso do Administrador Global ao registro do aplicativo blueprint)

Acesse o Entra portal>Registro de aplicativos> e selecione seu aplicativo Blueprint.
Acesse Permissões de API>Adicionar uma permissão>APIs que minha organização usa> procurar por 9b975845-388f-4429-889e-eab1ef63949c.
Selecione Permissões delegadas> marque Agent365.Observability.OtelWrite>Adicionar permissões.
Repita a etapa 2 a 3, desta vez selecione Permissões> de aplicativo para verificar Agent365.Observability.OtelWrite>Adicionar permissões.
Clique em Conceder consentimento do administrador e confirme.

Ambos Agent365.Observability.OtelWrite (Delegado) e Agent365.Observability.OtelWrite (Aplicativo) devem mostrar o status Granted.

HTTP 429 / 5xx — Erros transitórios

Sintomas: A exportação falha com um código de status HTTP transitório, como 429 ou 5xx.

Resolução:

Esses erros geralmente são transitórios e resolvidos por conta própria. Os SDKs de Python e JavaScript realizam tentativas automáticas novamente em códigos de status HTTP 408, 429 e 5xx até três vezes com retirada exponencial. O SDK do .NET não tenta novamente automaticamente.
Se os erros persistirem, verifique o painel de integridade do serviço.
Considere reduzir a frequência de exportação aumentando o atraso agendado entre lotes ou aumentando o tamanho máximo do lote de exportação. Para obter opções de configuração por plataforma, consulte a Agent365ExporterOptions tabela em Configuração.

Tempo limite de exportação

Sintomas: tempo limite de tentativas de exportação.

Resolução:

Verifique a conectividade de rede com o endpoint de observabilidade.
Os padrões de tempo limite variam de acordo com a plataforma. O tempo limite de solicitação HTTP padrão é de 30 segundos. Alguns SDKs também têm um tempo limite global separado do exportador que abrange todo o ciclo de exportação, incluindo novas tentativas. Para obter as propriedades exatas e os padrões por plataforma, consulte a Agent365ExporterOptions tabela em Configuração.
Caso os tempos limite ocorram com frequência, aumente o valor de tempo limite relevante nas opções do exportador.

A exportação é bem-sucedida, mas a telemetria não aparece no Defender ou no Purview

Symptoms: Os logs indicam uma exportação bem-sucedida, mas a telemetria não está visível no Microsoft Defender ou Microsoft Purview.

Resolução:

Verifique se você atende aos pré-requisitos para exibir logs exportados. Para o Purview, a auditoria deve ser ativada. Para Defender, você deve configurar a busca avançada. Para obter mais informações, consulte Visualização de logs exportados.
A telemetria pode levar vários minutos para ser atualizada após uma exportação bem-sucedida. Aguarde até que os dados apareçam antes de investigar mais.

Para saber mais sobre como testar a observabilidade, confira:

Comentários

Esta página foi útil?

Last updated on 2026-04-27

Observabilidade do agente

Principais benefícios

Agentes com suporte

Instalação

Configuração

Atributos de bagagem

Middleware de bagagem

Resolvedor de token

Instrumentação automática

Núcleo Semântico

OpenAI

Estrutura do Agente

Estrutura LangChain

Instrumentação manual

Invocação do agente

Execução de ferramentas

Inferência

Saída

Valide localmente

Exibindo logs exportados

Validar para publicação em lojas

atributos de InvokeAgentScope

atributos de ExecuteToolScope

atributos de InferenceScope

atributos de OutputScope

Teste seu agente com observabilidade

Resolução de problemas

Os dados de observabilidade não aparecem

ID do locatário ou ID do agente ausente – intervalos ignorados

Falha no processamento de token – exportação ignorada ou não autorizada

HTTP 401 Não Autorizado

HTTP 403 Proibido

HTTP 429 / 5xx — Erros transitórios

Tempo limite de exportação

A exportação é bem-sucedida, mas a telemetria não aparece no Defender ou no Purview

Comentários

Recursos adicionais

atributos de `InvokeAgentScope`

atributos de `ExecuteToolScope`

atributos de `InferenceScope`

atributos de `OutputScope`