SDK de observabilidade

Importante

Para ativar a observabilidade no Agent 365, utilize o Microsoft OpenTelemetry Distro. Esta distribuição fornece um único SDK de observabilidade em toda a Microsoft, suportando o Agent 365, o Microsoft Foundry, o Azure Monitor, entre outros. A abordagem existente descrita neste artigo continua a funcionar sem alterações interruptivas. Para orientações de migração por linguagem, consulte os seguintes guias:

• Guia de migração Python
• Guia de migração JavaScript/TypeScript
• Guia de migração .NET Para informações sobre o modelo de dados subjacente, identidade e autenticação, âmbitos e consentimento, e limites — que se aplicam a todos os caminhos de integração — consulte Conceitos de observabilidade do Agent 365.

Nota

A observabilidade é um dos escalões incrementais de capacidade em Introdução ao desenvolvimento do Agent 365 e aplica-se a todos os tipos de agentes.

Para participar no ecossistema do Agent 365, adicione as capacidades de Observabilidade do Agent 365 ao seu agente. A Observabilidade do Agent 365 baseia-se em OpenTelemetry (OTel) e fornece uma estrutura unificada para capturar telemetria de forma consistente e segura em todas as plataformas de agentes. Ao implementar este componente necessário, permite que os administradores de TI monitorizem a atividade do seu agente no centro de administração da Microsoft e possibilita que as equipas de segurança utilizem o Defender e o Purview para conformidade e deteção de ameaças.

Principais benefícios

• Visibilidade ponto a ponto: Capturar telemetria abrangente para cada invocação do agente, incluindo sessões, chamadas de ferramentas e exceções, proporcionando rastreabilidade completa entre plataformas.
• Ativação de segurança e conformidade: Integrar registos de auditoria unificados no Defender e no Purview, permitindo cenários avançados de segurança e relatórios de conformidade para o seu agente.
• Flexibilidade entre plataformas: Baseia-se nos padrões do OTel e suporta diversos runtimes e plataformas, como o Copilot Studio, o Foundry e futuras estruturas de agentes.
• Eficiência operacional para administradores: Proporcionar observabilidade centralizada no centro de administração do Microsoft 365, reduzindo o tempo de resolução de problemas e melhorando a governação com controlos de acesso baseados em funções para as equipas de TI que gerem o seu agente.

Agentes suportados

Os seguintes tipos de agentes suportam a observabilidade do Agent 365:

• Agentes compatíveis com Microsoft Agent 365: Utilize o SDK de observabilidade para instrumentar o seu agente.
• Agentes com motor personalizado: Utilize o SDK de observabilidade para instrumentar o seu agente.
• Agentes declarativos: A observabilidade é suportada de origem. Não é necessária qualquer implementação do SDK.

Instalação

Utilize estes pedidos para instalar os módulos de observabilidade para as linguagens suportadas pelo Agent 365.

Python

Instale os principais pacotes de runtime e de observabilidade. Todos os agentes que usam a Observabilidade do Agent 365 necessitam destes pacotes.

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

Caso o seu agente utilize o pacote Microsoft Agents Hosting, instale o pacote de integração de alojamento. Fornece middleware que preenche automaticamente o baggage e os âmbitos a partir de TurnContext e inclui a colocação em cache de tokens para o exportador de observabilidade.

pip install microsoft-agents-a365-observability-hosting

Se o seu agente utiliza uma das estruturas de IA suportadas, instale a extensão de instrumentação automática correspondente para capturar telemetria automaticamente, sem código de instrumentação manual. Para 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

JavaScript

Instale os principais pacotes de runtime e de observabilidade. Todos os agentes que usam a Observabilidade do Agent 365 necessitam destes pacotes.

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

Se o seu agente utilizar o pacote @microsoft/agents-hosting, instale o pacote de integração de alojamento. Fornece middleware que preenche automaticamente o baggage e os âmbitos a partir de TurnContext e inclui a colocação em cache de tokens para o exportador de observabilidade.

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

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

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

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

.NET

Instale o pacote principal de runtime e de observabilidade. Todos os agentes que utilizam a Observabilidade do Agent 365 necessitam deste pacote.

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

Se o seu agente utilizar o pacote NuGet Microsoft.Agents.A365.Observability.Hosting, instale o pacote de integração de alojamento. Fornece middleware que preenche automaticamente o baggage a partir de TurnContext e inclui a colocação em cache de tokens para o exportador de observabilidade.

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

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

// 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

Utilize as seguintes definições para ativar e personalizar a Observabilidade do Agent 365 para o seu agente.

Python

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como true para observabilidade. Esta definição exporta registos para o serviço e exige que seja fornecido um token_resolver. Caso contrário, é utilizado o exportador de consola.

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 resolvedor de token está excluído do registo na consola.

Pode personalizar o comportamento do exportador passando uma instância de Agent365ExporterOptions para exporter_options. Quando o parâmetro exporter_options é fornecido, tem 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 que se segue descreve os parâmetros opcionais para configure().

Parâmetro	Description	Predefinição
logger_name	Nome do logger Python utilizado para depuração e para a saída de registos da consola.	microsoft_agents_a365.observability.core
exporter_options	Uma instância Agent365ExporterOptions que configura o resolvedor de token e a categoria de cluster em conjunto.	None
suppress_invoke_agent_input	Quando True, suprime mensagens de entrada nos spans InvokeAgent.	False

A tabela que se segue descreve as propriedades opcionais para Agent365ExporterOptions.

Propriedade	Description	Predefinição
use_s2s_endpoint	Quando True, utilize o caminho do ponto final de serviço a serviço.	False
max_queue_size	Tamanho máximo da fila para o processador em 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

JavaScript

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como true para observabilidade. Esta definição exporta os registos para o serviço e exige a disponibilização de um resolvedor de token. Caso contrário, é utilizado o exportador de consola.

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, pode configurar a observabilidade programaticamente usando um fornecedor de configuração através do método withConfigurationProvider. Se também utilizar métodos de construtores individuais (como withExporterOptions ou withClusterCategory), estes têm prioridade sobre os valores do fornecedor 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();

Pode personalizar o comportamento do exportador passando uma instância de Agent365ExporterOptions para withExporterOptions. Esta opção permite controlar a criação de lotes, 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 que se segue descreve as propriedades opcionais para Agent365ExporterOptions.

Propriedade	Description	Predefinição
useS2SEndpoint	Quando true, utilize o caminho do ponto final de serviço a serviço.	false
maxQueueSize	Tamanho máximo da fila para o processador em 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 pedido HTTP individual ao back-end.	30000
maxExportBatchSize	Tamanho máximo do lote para operações de exportação.	512

É possível fornecer um logger personalizado que implemente a interface ILogger (info, warn, error, event). Passe-o ao construtor utilizando 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();

.NET

Defina EnableAgent365Exporter como true em appsettings.json.

Em Program.cs, adicione Agent365ExporterOptions à coleção de serviços. Esta alteração configura o delegado que o exportador de rastreio utiliza para obter o token.

Adicione dependências relacionadas com observabilidade utilizando 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();

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

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

A tabela que se segue descreve as propriedades opcionais para Agent365ExporterOptions.

Propriedade	Description	Predefinição
UseS2SEndpoint	Quando true, utilize o caminho do ponto final de serviço a serviço.	false
MaxQueueSize	Tamanho máximo da fila para o processador em 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 baggage

Utilize BaggageBuilder para definir informações contextuais que fluem por todos os intervalos de um pedido. O SDK implementa um SpanProcessor que copia todas as entradas do baggage não vazias para spans recém-iniciados sem substituir os atributos existentes.

Python

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, utilize o programa auxiliar populate do pacote microsoft-agents-a365-observability-hosting. Este programa auxiliar extrai automaticamente detalhes do chamador, agente, inquilino, 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

JavaScript

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, utilize o programa auxiliar fromTurnContext do pacote @microsoft/agents-a365-observability-hosting. Este programa auxiliar extrai automaticamente detalhes do chamador, agente, inquilino, 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
});

.NET

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 a partir do ITurnContext, utilize o método de extensão FromTurnContext no pacote Microsoft.Agents.A365.Observability.Hosting. Este método extrai automaticamente detalhes do chamador, agente, inquilino, canal e da 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 baggage

Se o seu agente utilizar o pacote de integração de alojamento, registe o middleware do baggage para preencher automaticamente o baggage em cada pedido recebido. Este passo elimina a necessidade de chamar BaggageBuilder manualmente em cada processador de atividades.

Python

Registe BaggageMiddleware no conjunto de middleware do adaptador. Extrai automaticamente os detalhes do autor da chamada, agente, inquilino, canal e conversa de cada TurnContext recebido e encapsula o pedido num âmbito do baggage.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Em alternativa, utilize ObservabilityHostingManager para configurar o middleware de baggage juntamente com outras funcionalidades de alojamento:

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 do baggage para respostas assíncronas (eventos ContinueConversation) para evitar substituir o baggage que o pedido original já definiu.

JavaScript

Registe BaggageMiddleware no adaptador. Extrai automaticamente os detalhes do autor da chamada, agente, inquilino, canal e conversa de cada TurnContext recebido e encapsula o pedido num âmbito do baggage.

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

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

Em alternativa, utilize ObservabilityHostingManager para configurar o middleware de baggage juntamente com outras funcionalidades de alojamento:

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

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

O middleware ignora a configuração do baggage para respostas assíncronas (eventos ContinueConversation) para evitar substituir o baggage que o pedido original já definiu.

.NET

Registe BaggageTurnMiddleware no adaptador. Extrai automaticamente os detalhes do autor da chamada, agente, inquilino, canal e conversa de cada ITurnContext recebido e encapsula o pedido num âmbito do baggage.

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

adapter.Use(new BaggageTurnMiddleware());

O middleware ignora a configuração do baggage para respostas assíncronas (eventos ContinueConversation) para evitar substituir o baggage que o pedido original já definiu.

Se precisar do baggage ao nível de HTTP (por exemplo, para definir IDs de inquilino e agente antes das execuções do pipeline do Bot Framework), registe ObservabilityBaggageMiddleware no pipeline do ASP.NET Core utilizando o método de extensão UseObservabilityRequestContext. Deve fornecer uma função de resolução que extraia o ID do inquilino e o 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 tokens

Ao utilizar o exportador do Agent 365, deve fornecer uma função de resolução de tokens que devolve um token de autenticação. Quando utiliza o SDK de Observabilidade do Agent 365 com a estrutura Agent Hosting, pode gerar tokens utilizando o TurnContext das atividades do agente.

Python

O fragmento a seguir mostra como gerar um token utilizando o SDK microsoft_agents.hosting.core. O token de autenticação gerado aqui é utilizado para exportar os spans para o serviço de ingestão do A365. Os agentes podem gerar eles próprios um token, por exemplo utilizando a Biblioteca de Autenticação Microsoft (MSAL), mas têm de garantir que o token inclui o âmbito 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 A365 que utiliza um colega de IA e o pacote Microsoft Agent 365 Observability Hosting Library, utilize AgenticTokenCache para gerir automaticamente a colocação em cache de tokens. Registe o token uma vez por agente e inquilino durante um processador de atividade e passe cache.get_observability_token como token_resolver na sua 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(),
    )

JavaScript

O fragmento a seguir mostra como gerar um token utilizando o SDK @microsoft/agents-hosting. O token de autenticação gerado aqui é utilizado para exportar os spans para o serviço de ingestão do A365. Os agentes podem gerar eles próprios um token, por exemplo utilizando a Biblioteca de Autenticação Microsoft (MSAL), mas têm de garantir que o token inclui o âmbito 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 utiliza um colega de IA e o pacote @microsoft/agents-a365-observability-hosting, utilize AgenticTokenCacheInstance para processar automaticamente a colocação em cache de tokens. Chame RefreshObservabilityToken uma vez por agente e inquilino durante um processador de atividade e passe AgenticTokenCacheInstance.getObservabilityToken como tokenResolver na sua 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()
    );
  }
);

.NET

O fragmento abaixo mostra como gerar um token utilizando o SDK de alojamento Microsoft.Agents. Utilize o token de autenticação gerado para exportar os spans para o serviço de ingestão do A365. Os agentes podem gerar eles próprios um token, por exemplo utilizando a Biblioteca de Autenticação Microsoft (MSAL), mas têm de garantir que o token inclui o âmbito de observabilidade.

Forneça um resolvedor de token ao registar Agent365ExporterOptions com um Delegado TokenResolver. O delegado recebe o agentId e o tenantId e devolve 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 do A365 que utiliza um colega de IA e o pacote NuGet Microsoft.Agents.A365.Observability.Hosting, utilize o método AddAgenticTracingExporter() para processar automaticamente a colocação em cache de tokens através da injeção de dependências.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Na aplicação do agente, registe 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 escuta automaticamente os sinais de telemetria existentes das estruturas por meio de agentes (SDKs) para rastreios e reencaminha-os para o serviço de observabilidade do Agent 365. Esta funcionalidade elimina a necessidade de os programadores escreverem código de monitorização manualmente, simplifica a configuração e assegura o rastreio consistente do desempenho.

Importante

A instrumentação automática preenche apenas os atributos OTel padrão. Deve adicionar atributos específicos da Microsoft através de BaggageBuilder. Para ver que atributos estão em falta, valide a saída do span da consola comparando-a com os registos da loja para o conjunto de diferenças.

Vários SDKs e plataformas suportam a instrumentação automática:

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

Nota

O suporte à instrumentação automática varia consoante a plataforma e a implementação do SDK.

Kernel Semântico

A instrumentação automática requer a utilização do construtor de baggage. Defina o ID do agente e o ID do inquilino utilizando BaggageBuilder.

Python

Instale o pacote.

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

Configure 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

JavaScript

O Kernel Semântico não é suportado com JavaScript.

.NET

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 utilizando BaggageBuilder. Certifique‑se de que o ID utilizado ao criar um ChatCompletionAgent corresponde ao ID do agente que passa ao 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 automática requer a utilização do construtor de baggage. Defina o ID do agente e o ID do inquilino utilizando BaggageBuilder.

Python

Instale o pacote.

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

Configure 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

JavaScript

Instale o pacote.

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

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

.NET

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 utilizando BaggageBuilder. Para chamadas de ferramentas, inicie um rastreio utilizando Trace() numa 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>);
    }
}

Agent Framework

A instrumentação automática requer a utilização do construtor de baggage. Defina o ID do agente e o ID do inquilino utilizando BaggageBuilder.

Python

Instale o pacote.

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

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

JavaScript

O Agent Framework não é suportado em JavaScript.

.NET

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

Arquitetura do LangChain

A instrumentação automática requer a utilização do construtor de baggage. Defina o ID do agente e o ID do inquilino utilizando BaggageBuilder.

Python

Instale o pacote.

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

Configure 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

JavaScript

Instale o pacote.

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

Configure 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

.NET

LangChain não é suportado com .NET.

Instrumentação Manual

Utilize o SDK de observabilidade do Agent 365 para compreender o funcionamento interno do agente. O SDK disponibiliza âmbitos que pode ativar: InvokeAgentScope, ExecuteToolScope, InferenceScope e OutputScope.

Invocação do agente

Utilize este âmbito no início do processo do agente. Ao utilizar o âmbito de invocação do agente, pode capturar propriedades como o agente atual a ser invocado, dados do utilizador de agente e muito mais.

Python

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

JavaScript

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 seu agente utilizar o pacote @microsoft/agents-a365-observability-hosting, pode utilizar ScopeUtils.populateInvokeAgentScopeFromTurnContext para criar o âmbito com detalhes do agente, detalhes do chamador e informações do canal automaticamente derivadas de 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();
}

.NET

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 da ferramenta

Os exemplos a seguir mostram como adicionar o rastreio de observabilidade à execução de ferramentas do seu agente. Este rastreio captura telemetria para fins de monitorização e auditoria.

Python

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)

JavaScript

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 seu agente utilizar o pacote @microsoft/agents-a365-observability-hosting, utilize ScopeUtils.populateExecuteToolScopeFromTurnContext para criar o âmbito com os detalhes do agente automaticamente derivados de 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();
}

.NET

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 seguintes mostram como instrumentar chamadas de inferência de modelos de IA com rastreio de observabilidade para capturar a utilização de tokens, detalhes do modelo e metadados de resposta.

Python

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)

JavaScript

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 seu agente utilizar o pacote @microsoft/agents-a365-observability-hosting, pode utilizar ScopeUtils.populateInferenceScopeFromTurnContext para criar o âmbito com os detalhes do agente automaticamente derivados de 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();
}

.NET

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

Utilize este âmbito para cenários assíncronos onde InvokeAgentScope, ExecuteToolScope ou InferenceScope não podem capturar dados de saída de forma síncrona. Inicie OutputScope como um span de elemento subordinado para registar as mensagens finais de saída após o término do âmbito do elemento principal.

Python

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

JavaScript

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

.NET

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

Validar localmente

Para verificar se a integração com o SDK de observabilidade foi bem-sucedida, analise os registos da consola gerados pelo seu agente e os registos do SDK de observabilidade.

Python

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Esta definição exporta spans (rastreios) para a consola.

Para investigar falhas de exportação, ative o registo verboso definindo ENABLE_A365_OBSERVABILITY_EXPORTER como true e configurando o registo de depuração no arranque da sua aplicação:

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)

Principais mensagens de registo:

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.

JavaScript

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Esta definição exporta spans (rastreios) para a consola.

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

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Reveja a saída da consola 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, utilize um logger personalizado para capturar eventos de exportação para um ficheiro:

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

.NET

Defina EnableAgent365Exporter como false em appsettings.json. Esta definição exporta spans (rastreios) para a consola.

Para investigar falhas de exportação, configure o registo verboso 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

Principais mensagens de registo:

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.

Nota

Se não registar um ILoggerFactory em DI, o exportador recorre automaticamente a um logger de consola.

Visualização de registos exportados

Para ver a telemetria do agente no Microsoft Purview ou Microsoft Defender, certifique-se de que os seguintes requisitos são satisfeitos:

• Microsoft Purview: a auditoria deve estar ativada para a sua organização. Para obter instruções, consulte Ativar ou desativar a auditoria.
• Microsoft Defender: a procura avançada deve ser configurada para aceder à tabela CloudAppEvents. Para mais informações, consulte a tabela CloudAppEvents no esquema de procura avançada.

Validar para publicação na loja

Importante

Para que a validação na loja seja bem-sucedida, o seu agente deve implementar os âmbitos InvokeAgentScope, InferenceScope e ExecuteToolScope. Estes três âmbitos são necessários para publicação.

Antes de publicar, utilize os registos da consola para validar a integração de observabilidade do seu agente, implementando os âmbitos invoke agent, execute tool, inference e output obrigatórios. Em seguida, compare os registos do seu agente com as seguintes listas de atributos para verificar se todos os atributos necessários estão presentes. Capture atributos em cada âmbito ou através do construtor de baggage e inclua atributos opcionais a seu critério.

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

Atributos InvokeAgentScope

A lista seguinte resume os atributos de telemetria obrigatórios e opcionais registados quando 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 ExecuteToolScope

A lista seguinte resume os atributos de telemetria obrigatórios e opcionais registados quando 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 InferenceScope

A lista seguinte resume os atributos de telemetria obrigatórios e opcionais registados quando 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 OutputScope

A lista seguinte resume os atributos de telemetria obrigatórios e opcionais registados quando inicia um OutputScope. Utilize este âmbito para cenários assíncronos em que o âmbito do elemento principal não consegue 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"
    }

Testar o seu agente com observabilidade

Após implementar a observabilidade no seu agente, teste-a para assegurar que a telemetria é capturada corretamente. Siga o guia de testes para configurar o seu ambiente. Depois, concentre-se principalmente na secção Ver registos de observabilidade para validar se a sua implementação de observabilidade está a funcionar como esperado.

Verificação:

• Aceda a: https://admin.cloud.microsoft/#/agents/all
• Selecione o seu agente > Atividade
• Vê sessões e chamadas de ferramentas

Resolução de Problemas

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

Problema	Descrição
Os dados de observabilidade não aparecem	Não há telemetria visível porque a exportação não está ativada, a configuração está incorreta ou a resolução do token falha.
ID do inquilino ou ID do agente em falta – spans ignorados	Os spans são descartados antes da exportação quando os atributos de identidade necessários para a criação de partições estão em falta.
Falha na resolução do token - exportação ignorada ou não autorizada	Os pedidos de exportação falham ou são ignorados quando o resolvedor não devolve nenhum token ou encontra uma exceção.
HTTP 401 Não autorizado	A autenticação é bem-sucedida sintaticamente, mas o token é inválido para ingestão devido ao âmbito, tipo ou expiração.
HTTP 403 Proibido	O acesso é negado devido a lacunas de licenciamento do inquilino ou permissões de observabilidade em falta.
HTTP 403 Proibido - O ID do agente não corresponde	O pedido é rejeitado quando a identidade do agente no URL não corresponde à identidade representada pelo token.
Erros HTTP 429 ou 5xx - Erros transitórios	Limitações temporárias ou falhas do lado de serviço interrompem a exportação e podem exigir ajuste de repetição.
Tempo limite de exportação	Os lotes de telemetria excedem as janelas de tempo limite configuradas devido à latência da rede ou à capacidade de resposta do ponto final.
A exportação é bem-sucedida, mas a telemetria não aparece no Defender ou no Purview	A ingestão é concluída, mas a visibilidade a jusante é atrasada ou bloqueada por pré-requisitos do produto.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

Os dados de observabilidade não aparecem

Sintomas:

• O agente está em execução
• Sem telemetria no centro de administração
• Não é possível ver a atividade do agente

Causa raiz:

• A observabilidade não está ativada
• Erros de configuração
• Problemas com o resolver de tokens

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

• Verificar se o exportador de observabilidade está ativado

  Deve ativar explicitamente o exportador do Agent 365. Quando desativado, o SDK recorre a um exportador de consola e a telemetria não é enviada para o serviço. Para detalhes de configuração, consulte Configuração.

• Verificar a configuração do resolver de tokens

  O exportador requer um resolver de tokens válido que devolva um token de Portador para cada pedido de exportação. Se o resolver de tokens estiver em falta ou devolver null, a exportação é ignorada silenciosamente. Certifique-se de que o seu código implementa corretamente o resolvedor de tokens. Para detalhes, consulte Resolvedor de tokens.

• Verificar se existem erros nos registos

  Ative o registo verboso e utilize o comando az webapp log tail para procurar erros relacionados com observabilidade nos registos. Para detalhes sobre como ativar o registo por 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 a exportação de telemetria

  Verifique se a telemetria é gerada e exportada conforme esperado.

  • Adicione um exportador de consola e verifique se a telemetria é gerada localmente. Para saber como utilizar o exportador da consola e validar a saída, consulte Validar localmente.

ID do inquilino ou do agente em falta — spans ignorados

Sintomas: o sistema descarta os spans silenciosamente e nunca os exporta. Alguns SDKs registam uma contagem de spans ignorados ou uma mensagem como "Não foram encontrados spans com identidade de inquilino/agente". Outros descartam-nos sem registo.

Resolução:

• Antes da exportação, o SDK cria partições de spans por identidade de inquilino e de agente. O sistema descarta os spans que não tenham um ID de inquilino ou um ID de agente e nunca os envia para o serviço.
• Garanta que BaggageBuilder está configurado com o ID do inquilino e o ID do agente antes de criar spans. Estes valores propagam-se através do contexto OpenTelemetry e ligam-se a todos os spans criados dentro do âmbito do baggage. Para a API específica da plataforma, consulte atributos do baggage.
• Confirme que a atividade de TurnContext tem um destinatário válido com identidade de agente se utilizar o middleware de baggage ou o programa auxiliar de contexto de turno do pacote de integração de alojamento para preencher esses IDs.

Falha na resolução do token — exportação ignorada ou não autorizada

Sintomas: o resolver de tokens devolve null ou lança um erro. Consoante o SDK, a exportação ou é totalmente ignorada ou o pedido é enviado sem um cabeçalho de autorização e falha com HTTP 401.

Resolução:

• O resolvedor de tokens é necessário na inicialização. Se estiver em falta, o exportador lança um erro no arranque. Verifique se um resolver de tokens é fornecido e devolve um token de Portador válido.
• Certifique-se de que o ID de inquilino e o ID de agente corretos são utilizados no BaggageBuilder, pois estes valores são passados ao resolvedor de tokens.
• Para os agentes alojados no Azure, verifique se a Identidade Gerida tem a permissão necessária da API para o âmbito de observabilidade.

HTTP 401 Não autorizado

Sintomas: a exportação falha com HTTP 401. O exportador não volta a tentar este erro.

Resolução:

• Verifique se a audiência do token corresponde ao âmbito do ponto final de observabilidade.
• Verifique se o resolver de tokens não está a devolver um token de utilizador delegado, um token para uma audiência incorreta ou um token expirado.

HTTP 403 Proibido

Sintomas: a exportação falha com HTTP 403. O exportador não volta a tentar este erro.

Causa principal: um erro HTTP 403 pode ter diferentes causas. Verifique as seguintes resoluções pela ordem apresentada.

Resolução:

• Licença em falta — Certifique-se de que o seu inquilino tem uma das seguintes licenças atribuídas no Centro de administração do Microsoft 365:

  • Testar - Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Permissão Agent365.Observability.OtelWrite em falta — Se atualizou recentemente os seus pacotes de observabilidade, precisa de conceder esta permissão. Veja a nota importante na secção seguinte.

Importante

Os agentes existentes que sejam atualizados para estas versões de pacotes requerem um passo extra

Este passo aplica-se apenas se estiver a atualizar um agente existente. As instalação de novos agentes não requer este passo. Se estiver a atualizar para as versões de pacote seguintes ou mais recentes, deve conceder a nova permissão Agent365.Observability.OtelWrite à sua identidade (Identidade Gerida ou registo de aplicação). Sem esta permissão, a exportação de telemetria falha com erro HTTP 403.

Plataforma	Versão mínima que requer este passo
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Conceda a permissão utilizando uma das seguintes opções.

Opção A — CLI do Agent 365 (requer uma conta de Administrador Global; execute a partir do diretório do projeto do agente que contém a365.config.json, ou utilize --agent-name)

a365 setup permissions bot

Ou, sem um ficheiro de configuração:

a365 setup permissions bot --agent-name "<agent-name>"

Este comando concede todas as permissões em falta no esquema, incluindo os âmbitos de Observabilidade.

Opção B — Portal do Entra (não são necessários ficheiros de configuração; é necessário acesso como Administrador Global ao registo da aplicação de esquema)

1. Vá para o portal do Entra>Registos de aplicações>, selecione a sua aplicação de Esquema.
2. Vá para Permissões da API>Adicionar uma permissão>APIs que a minha organização utiliza>, procure 9b975845-388f-4429-889e-eab1ef63949c.
3. Selecione Permissões delegadas,>, verifique Agent365.Observability.OtelWrite>Adicionar permissões.
4. Repita os passos 2–3, desta vez selecione Permissões de aplicação>, verifique Agent365.Observability.OtelWrite>Adicionar permissões.
5. Clique em Conceder consentimento do administrador e confirme.

Tanto Agent365.Observability.OtelWrite (Delegado) como Agent365.Observability.OtelWrite (Aplicação) devem mostrar o estado Granted.

HTTP 403 Proibido — O ID do agente não corresponde

Sintomas: a exportação falha com o HTTP 403 e uma mensagem do servidor semelhante a 403 Forbidden, com falhas de agent-ID-mismatch ao chamar os pontos finais de rastreios do Agent 365.

Causa raiz: este erro ocorre quando usa o ID do cliente do esquema, em vez do ID do cliente da instância de agente ao definir os detalhes do agente. O ID do agente no URL de exportação não corresponde à identidade autorizada pelo token, por isso o ponto final dos rastreios rejeita o pedido.

Resolução:

• Verifique se o ID do inquilino foi adicionado à lista de inquilinos permitidos do Agent 365.
• Defina os detalhes do agente com o ID do cliente da instância de agente (não o ID do cliente do esquema).
• Verifique o URL de exportação gerado – está registado se ativar o seu logger. Confirme se o ID do agente no URL corresponde ao ID do cliente da instância de agente.
• Para ativar o registo de diagnósticos por SDK, consulte Validar localmente.

Erros HTTP 429 ou 5xx - Erros transitórios

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

Resolução:

• Estes erros são geralmente transitórios e resolvem-se por si mesmos. Os SDKs de Python e JavaScript efetuam automaticamente novas tentativas para códigos de estado HTTP 408, 429 e 5xx até três vezes, com recuo exponencial. O SDK de .NET não efetua novas tentativas automaticamente.
• Se persistirem erros, verifique o dashboard do estado de funcionamento 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 opções de configuração por plataforma, consulte a tabela Agent365ExporterOptions em Configuração.

Tempo limite de exportação

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

Resolução:

• Verifique a conectividade de rede com o ponto final de observabilidade.
• As predefinições de tempo limite variam consoante a plataforma. O tempo limite predefinido para pedidos HTTP é de 30 segundos. Alguns SDKs também têm um tempo limite geral do exportador separado, que abrange todo o ciclo de exportação, incluindo as novas tentativas. Para obter as propriedades exatas e os valores predefinidos por plataforma, consulte a tabela Agent365ExporterOptions em Configuração.
• Se ocorrerem tempos limite 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

Sintomas: Os registos mostram uma exportação bem-sucedida, mas a telemetria não é visível no Microsoft Defender nem no Microsoft Purview.

Resolução:

• Verifique se cumpre os pré-requisitos para ver os registos exportados. Para o Purview, a auditoria tem de estar ativada. Para o Defender, é necessário configurar a investigação avançada. Para obter mais informações, consulte Ver registos exportados.
• A telemetria pode demorar vários minutos a ser disponibilizada após uma exportação bem-sucedida. Aguarde que os dados sejam apresentados antes de continuar a investigação.

Para saber mais sobre como testar a observabilidade, consulte:

• Guia de testes - Ver registos de observabilidade
• Configuração de observabilidade

Conteúdos relacionados

• Conceitos de observabilidade do Agent 365 - Fluxo de dados, modelos de identidade, autenticação, âmbitos e limites que se aplicam a todos os caminhos de integração.
• Referência de atributos de observabilidade do Agent 365 - Esquema canónico de atributos de span ao qual cada span ingerido pelo Agent 365 deve obedecer.
• Microsoft OpenTelemetry Distro - O SDK unificado recomendado para novas integrações.