Kit de développement logiciel d’observabilité

Important

Pour activer l’observabilité dans Agent 365, utilisez Microsoft OpenTelemetry Distro. Cette distribution fournit un SDK unique d’observabilité à l’échelle de Microsoft, alimentant Agent 365, Microsoft Foundry, Azure Monitor, et bien d’autres. L’approche existante décrite dans cet article continue de fonctionner sans changements cassants. Pour des conseils sur la migration par langue, consultez les guides suivants :

• Guide de migration Python
• Guide de migration JavaScript/TypeScript
• Guide de migration .NET Pour le modèle de données sous-jacent, l’identité et l’authentification, les portées et le consentement, et les limites – qui s’appliquent à chaque chemin d’intégration – reportez-vous à la rubrique Concepts d’observabilité d’Agent 365.

Remarque

L’observabilité est l’un des niveaux de capacité incrémentales dans Démarrage avec le développement d’Agent 365 et s’applique à tous les types d’assistants.

Pour participer à l’écosystème Agent 365, vous devez ajouter des fonctionnalités d’observabilité Agent 365 à votre assistant. L’observabilité d’Agent 365 s’appuie sur OpenTelemetry (OTel) et fournit une infrastructure unifiée pour capturer de manière cohérente et sécurisée les données de télémétrie sur toutes les plateformes d’assistant. En implémentant ce composant requis, vous allez autoriser les administrateurs informatiques à surveiller l’activité de votre assistant dans le Centre d’administration Microsoft (MAC) et autoriser les équipes de sécurité à utiliser Defender et Purview pour la conformité et la détection des menaces.

Principaux avantages

• Visibilité de bout en bout : capturez des données de télémétrie complètes pour chaque appel d’assistant, y compris les sessions, les appels d’outils et les exceptions, ce qui vous donne une traçabilité complète entre les plateformes.
• Activation de la sécurité de la conformité : alimentez les journaux d’audit unifiés dans Defender et Purview, en actionnant des scénarios de sécurité avancée et les rapports de conformité pour votre assistant.
• Flexibilité inter-plateformes : créez des normes OTel et prenez en charge différents environnements d’exécution et diverses plateformes comme Copilot Studio, Foundry et les futurs frameworks d’assistant.
• Efficacité opérationnelle pour les administrateurs : fournissez une observabilité centralisée dans le Centre d’administration Microsoft 365, ce qui réduit le temps de résolution des problèmes et améliore la gouvernance avec des contrôles d’accès en fonction du rôle pour les équipes informatiques qui gèrent votre assistant.

Agents pris en charge

Les types d’assistants suivants prennent en charge l’observabilité de l’Agent 365 :

• Assistants compatibles Microsoft Agent 365 : Utilisez le SDK d’observabilité pour instrumenter votre assistant.
• Assistants à moteur personnalisé : Utilisez le SDK d’observabilité pour instrumenter votre assistant.
• Assistants déclaratifs : l’observabilité est prise en charge prête à l’emploi. Aucune implémentation du SDK requise.

Installation

Utilisez ces commandes pour installer les modules d’observabilité pour les langues prises en charge par Agent 365.

Python

Installez les packages d’observabilité et d’exécution du noyau. Tous les assistants utilisant Agent 365 Observability ont besoin de ces packages.

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

Si votre assistant utilise le package Microsoft Agents Hosting, installez le package d’intégration pour l’hébergement. Il fournit un intergiciel qui remplit automatiquement les bagages et les étendues à partir de TurnContext, et inclut la mise en cache des jetons pour l’exportateur d’observabilité.

pip install microsoft-agents-a365-observability-hosting

Si votre assistant utilise l’un des frameworks d’IA pris en charge, installez l’extension d’auto-instrumentation correspondante pour capturer automatiquement la télémétrie sans code d’instrumentation manuel. Pour les détails de configuration, consultez Auto-instrumentation.

# 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

Installez les packages d’observabilité et d’exécution du noyau. Tous les assistants utilisant Agent 365 Observability ont besoin de ces packages.

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

Si votre assistant utilise le package @microsoft/agents-hosting, installez le package d’intégration pour l’hébergement. Il fournit un intergiciel qui remplit automatiquement les bagages et les étendues à partir de TurnContext, et inclut la mise en cache des jetons pour l’exportateur d’observabilité.

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

Si votre assistant utilise l’un des frameworks d’IA pris en charge, installez l’extension d’auto-instrumentation correspondante pour capturer automatiquement la télémétrie sans code d’instrumentation manuel. Pour les détails de configuration, consultez Auto-instrumentation.

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

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

.NET

Installez les packages d’observabilité et d’exécution du noyau. Tous les assistants qui utilisent Agent 365 Observability ont besoin de ce package.

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

Si votre assistant utilise le package NuGet Microsoft.Agents.A365.Observability.Hosting, installez le package d’intégration d’hébergement. Il fournit un intergiciel qui remplit automatiquement les bagages à partir de TurnContext, et inclut la mise en cache des jetons pour l’exportateur d’observabilité.

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

Si votre assistant utilise l’un des frameworks d’IA pris en charge, installez l’extension d’auto-instrumentation correspondante pour capturer automatiquement la télémétrie sans code d’instrumentation manuel. Pour les détails de configuration, consultez Auto-instrumentation.

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

Configuration

Utilisez les paramètres suivants pour activer et personnaliser Agent 365 Observability pour votre assistant.

Python

Définir la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur true pour l’observabilité. Ce paramètre exporte les journaux vers le service et nécessite qu’un token_resolver soit fourni. Sinon, l’exportateur console est utilisé.

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

Le programme de résolution de jeton est exclu de la connexion à la console.

Vous pouvez personnaliser le comportement de l’exportateur en passant une instance de Agent365ExporterOptions à exporter_options. Lorsque exporter_options est fourni, il a priorité sur les paramètres token_resolver et 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,
)

La table suivante décrit les paramètres facultatifs à utiliser avec configure().

Paramètre	Description	Par défaut
logger_name	Nom du logger Python utilisé pour le débogage et la sortie des journaux de console.	microsoft_agents_a365.observability.core
exporter_options	Une instance Agent365ExporterOptions qui configure ensemble le programme de résolution de jeton et la catégorie de cluster.	None
suppress_invoke_agent_input	Lorsque True, les messages d’entrée dans les étendues InvokeAgent sont supprimés.	False

La table suivante décrit les propriétés facultatives à utiliser avec Agent365ExporterOptions.

Propriété	Description	Par défaut
use_s2s_endpoint	Lorsque True, le chemin du point de terminaison de service à service est utilisé.	False
max_queue_size	Taille maximale de la file d’attente pour le processeur par lots.	2048
scheduled_delay_ms	Délai en millisecondes entre les lots d’exportation.	5000
exporter_timeout_ms	Délai d’expiration en millisecondes pour l’opération d’exportation.	30000
max_export_batch_size	Taille maximale de lots pour les opérations d’exportation.	512

JavaScript

Définir la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur true pour l’observabilité. Ce paramètre exporte les journaux d’activité vers le service et nécessite qu’un résolveur de jeton soit fourni. Sinon, l’exportateur console est utilisé.

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

En tant qu’alternative aux variables d’environnement, vous pouvez configurer l’observabilité de manière programmatique en utilisant un fournisseur de configuration via la méthode withConfigurationProvider. Si vous utilisez également des méthodes builder individuelles (telles que withExporterOptions ou withClusterCategory), les méthodes builder individuelles prévalent sur les valeurs du fournisseur de configuration.

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

Vous pouvez personnaliser le comportement de l’exportateur en passant une instance de Agent365ExporterOptions à withExporterOptions. Cette option vous permet de contrôler le regroupement en lots, les délais d’attente et le mode de routage.

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

La table suivante décrit les propriétés facultatives à utiliser avec Agent365ExporterOptions.

Propriété	Description	Par défaut
useS2SEndpoint	Lorsque true, le chemin du point de terminaison de service à service est utilisé.	false
maxQueueSize	Taille maximale de la file d’attente pour le processeur par lots.	2048
scheduledDelayMilliseconds	Délai en millisecondes entre les lots d’exportation.	5000
exporterTimeoutMilliseconds	Délai d’expiration en millisecondes pour toute l’opération d’exportation.	90000
httpRequestTimeoutMilliseconds	Délai d’expiration en millisecondes pour chaque requête HTTP individuelle vers le backend.	30000
maxExportBatchSize	Taille maximale de lots pour les opérations d’exportation.	512

Vous pouvez également fournir un enregistreur personnalisé qui implémente l’interface ILogger (info, warn, error, event). Passez-le au builder en utilisant 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

Définissez EnableAgent365Exporter sur true dans appsettings.json.

Dans Program.cs, ajoutez Agent365ExporterOptions à la collection de services. Cette modification configure le délégué que l’exportateur de trace utilise pour récupérer le jeton.

Ajoutez des dépendances liées à l’observabilité à l’aide de 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();

Vous pouvez personnaliser le comportement de l’exportateur en passant un délégué de configuration et un type d’exportateur à AddA365Tracing().

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

La table suivante décrit les propriétés facultatives à utiliser avec Agent365ExporterOptions.

Propriété	Description	Par défaut
UseS2SEndpoint	Lorsque true, le chemin du point de terminaison de service à service est utilisé.	false
MaxQueueSize	Taille maximale de la file d’attente pour le processeur par lots.	2048
ScheduledDelayMilliseconds	Délai en millisecondes entre les lots d’exportation.	5000
ExporterTimeoutMilliseconds	Délai d’expiration en millisecondes pour l’opération d’exportation.	30000
MaxExportBatchSize	Taille maximale de lots pour les opérations d’exportation.	512

Attributs de bagage

Permet BaggageBuilder de définir des informations contextuelles qui transitent par toutes les étendues d’une requête. Le kit de développement logiciel (SDK) implémente une SpanProcessor et copie de toutes les entrées de bagages sans avoir à remplacer les attributs existants.

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

Pour remplir automatiquement le BaggageBuilder à partir du TurnContext, utilisez l’aide populate dans le package microsoft-agents-a365-observability-hosting. Cet utilitaire extrait automatiquement l’appelant, l’assistant, le locataire, le canal et les détails de conversation de l’activité.

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

Pour remplir automatiquement le BaggageBuilder à partir du TurnContext, utilisez l’aide fromTurnContext dans le package @microsoft/agents-a365-observability-hosting. Cet utilitaire extrait automatiquement l’appelant, l’assistant, le locataire, le canal et les détails de conversation de l’activité.

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.

Pour remplir automatiquement le BaggageBuilder à partir de ITurnContext, utilisez la méthode d’extension FromTurnContext dans le package Microsoft.Agents.A365.Observability.Hosting. Cette méthode extrait automatiquement l’appelant, l’assistant, le locataire, le canal et les détails de conversation de l’activité.

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

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

Intergiciel de bagages

Si votre assistant utilise le package d’intégration d’hébergement, enregistrez l’intergiciel de bagage pour renseigner automatiquement le bagage à chaque requête entrante. Cette étape élimine le besoin d’appeler BaggageBuilder manuellement dans chaque gestionnaire d’activité.

Python

Inscrivez BaggageMiddleware sur le jeu de logiciel intermédiaire adaptateur. Il extrait automatiquement l’appelant, l’assistant, le locataire, le canal et les détails de la conversation de chaque TurnContext entrant et encapsule la demande dans une étendue de bagages.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Vous pouvez également utiliser ObservabilityHostingManager pour configurer l’intergiciel de bagages avec d’autres fonctionnalités d’hébergement :

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

L’intergiciel ignore la configuration des bagages pour les réponses asynchrones (événements ContinueConversation) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

JavaScript

Enregistrez BaggageMiddleware sur l’adaptateur. Il extrait automatiquement l’appelant, l’assistant, le locataire, le canal et les détails de la conversation de chaque TurnContext entrant et encapsule la demande dans une étendue de bagages.

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

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

Vous pouvez également utiliser ObservabilityHostingManager pour configurer l’intergiciel de bagages avec d’autres fonctionnalités d’hébergement :

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

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

L’intergiciel ignore la configuration des bagages pour les réponses asynchrones (événements ContinueConversation) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

.NET

Enregistrez BaggageTurnMiddleware sur l’adaptateur. Il extrait automatiquement l’appelant, l’assistant, le locataire, le canal et les détails de la conversation de chaque ITurnContext entrant et encapsule la demande dans une étendue de bagages.

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

adapter.Use(new BaggageTurnMiddleware());

L’intergiciel ignore la configuration des bagages pour les réponses asynchrones (événements ContinueConversation) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

Si vous avez besoin d’un bagage au niveau HTTP (par exemple, pour définir des ID de locataire et d’assistant avant l’exécution du pipeline Bot Framework), enregistrez ObservabilityBaggageMiddleware dans le pipeline ASP.NET Core à l’aide de la méthode d’extension UseObservabilityRequestContext. Vous devez fournir une fonction de résolution qui extrait l’ID du locataire et l’ID de l’assistant du contexte 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);
});

Programme de résolution de jetons

Lorsque vous utilisez l’exportateur Agent 365, vous devez fournir une fonction de programme de résolution de jeton qui renvoie le jeton d’authentification. Lorsque vous utilisez le kit de développement logiciel (SDK) de l’observabilité d’Agent 365 avec l’infrastructure d’hébergement de l’assistant, vous pouvez générer des jetons à l’aide TurnContext des activités de l’assistant

Python

L’extrait suivant montre comment générer un jeton à l’aide du kit de développement logiciel microsoft_agents.hosting.core. Le jeton d’authentification généré ici est utilisé pour exporter les spans vers le service d’ingestion A365. Les assistants peuvent générer eux-mêmes un jeton, par exemple en utilisant Microsoft Authentication Library (MSAL), mais ils doivent s’assurer que le jeton contient la portée d’observabilité.

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

Pour un assistant créé avec la CLI A365 qui utilise un coéquipier IA et le package Bibliothèque d’hébergement Observabilité Microsoft Agent 365, utilisez AgenticTokenCache pour gérer automatiquement la mise en cache des jetons. Enregistrez le jeton une fois par assistant et par locataire dans un gestionnaire d’activité, puis passez cache.get_observability_token comme token_resolver dans votre configuration d’observabilité.

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

L’extrait suivant montre comment générer un jeton à l’aide du kit de développement logiciel @microsoft/agents-hosting. Le jeton d’authentification généré ici est utilisé pour exporter les spans vers le service d’ingestion A365. Les assistants peuvent générer eux-mêmes un jeton, par exemple en utilisant Microsoft Authentication Library (MSAL), mais ils doivent s’assurer que le jeton contient la portée d’observabilité.

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

Pour un assistant créé avec la CLI A365 qui utilise un coéquipier IA et le package @microsoft/agents-a365-observability-hosting, utilisez AgenticTokenCacheInstance pour gérer automatiquement la mise en cache des jetons. Appelez RefreshObservabilityToken une fois par assistant et par locataire dans un gestionnaire d’activité, puis passez AgenticTokenCacheInstance.getObservabilityToken comme tokenResolver dans votre configuration d’observabilité.

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

L’extrait suivant montre comment générer un jeton en utilisant le SDK d’hébergement Microsoft.Agents. Utilisez le jeton d’authentification généré pour exporter les spans vers le service d’ingestion A365. Les assistants peuvent générer eux-mêmes un jeton, par exemple en utilisant Microsoft Authentication Library (MSAL), mais ils doivent s’assurer que le jeton contient la portée d’observabilité.

Fournissez un résolveur de jetons en enregistrant Agent365ExporterOptions avec un délégué TokenResolver. Le délégué reçoit le agentId et tenantId et retourne un jeton d’authentification.

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

Pour un assistant créé avec la CLI A365 qui utilise un coéquipier IA et le package NuGet Microsoft.Agents.A365.Observability.Hosting, utilisez la méthode AddAgenticTracingExporter() pour gérer automatiquement la mise en cache des jetons via l’injection de dépendance.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Dans l’application de l’assistant, inscrivez le jeton.

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

Auto-instrumentation

L’instrumentation automatique écoute automatiquement les signaux de télémétrie existants des frameworks agentiques (SDK) pour les traces et les transfère au service d’observabilité Agent 365. Cela élimine la nécessité pour les développeurs d’écrire manuellement du code de surveillance, de simplifier la configuration et de garantir un suivi des performances cohérent.

Important

L’instrumentation automatique renseigne uniquement les attributs standard OTel. Vous devez ajouter des attributs spécifiques à Microsoft à l’aide de BaggageBuilder. Pour voir quels attributs sont manquants, validez la sortie des spans de la console par rapport aux journaux du stockage dans l’ensemble des différences.

L’instrumentation automatique est prise en charge sur plusieurs kits de développement logiciel et plateformes :

Plateforme	Kits de développement logiciel (SDK) / Frameworks pris en charge
.NET	Noyau sémantique, OpenAI, Agent Framework
Python	Noyau sémantique, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Remarque

La prise en charge de l’instrumentation automatique varie selon l’implémentation de la plateforme et du SDK.

Noyau sémantique

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’identifiant de l’assistant et l’identifiant de locataire à l’aide de BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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

Noyau sémantique n’est pas pris en charge avec JavaScript.

.NET

Ajoutez des dépendances à la collection de services.

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

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

Définissez AgentId et TenantId à l’aide de BaggageBuilder. Vérifiez que l’identifiant utilisé lors de la création d’un ChatCompletionAgent correspond à l’identifiant de l’assistant transmis à 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

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’identifiant de l’assistant et l’identifiant de locataire à l’aide de BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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

Installez le package .

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

Configurez l’observabilité.

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

Ajoutez des dépendances à la collection de services.

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

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

Définissez AgentId et TenantId à l’aide de BaggageBuilder. Pour les appels d’outils, démarrez une trace à l’aide de Trace() sur une instance 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

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’identifiant de l’assistant et l’identifiant de locataire à l’aide de BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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

Agent Framework n’est pas pris en charge avec JavaScript.

.NET

Ajoutez des dépendances à la collection de services.

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

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

Définissez AgentId et TenantId à l’aide de 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();
    }
}

LangChain Framework

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’identifiant de l’assistant et l’identifiant de locataire à l’aide de BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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

Installez le package .

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

Configurez l’observabilité.

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’est pas pris en charge par .NET.

Instrumentation manuelle

Utilisez le kit de développement logiciel (SDK) d’observabilité d’Agent 365 peut être utilisé pour comprendre le fonctionnement interne de l’assistant. Le kit de développement logiciel (SDK) fournit trois étendues qui peuvent être démarrées : InvokeAgentScope, ExecuteToolScope, InferenceScope et OutputScope.

Appel de l’assistant

Cette étendue doit être utilisée au début du processus de votre assistant. Avec l’étendue de l’assistant Invoke, capturez des propriétés telles que l’assistant actuel appelé, les données utilisateur de l’assistant, etc.

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

Si votre assistant utilise le package @microsoft/agents-a365-observability-hosting, vous pouvez utiliser ScopeUtils.populateInvokeAgentScopeFromTurnContext pour créer l’étendue avec les détails de l’assistant, de l’appelant et les informations relatives au canal automatiquement issues du 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; }
}

Exécution de l’outil

Les exemples suivants illustrent comment intégrer le suivi de l’observabilité à l’exécution des outils de votre assistant. Ce suivi capture la télémétrie à des fins de surveillance et d’audit.

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

Si votre assistant utilise le package @microsoft/agents-a365-observability-hosting, utilisez ScopeUtils.populateExecuteToolScopeFromTurnContext pour créer le scope avec les détails de l’assistant automatiquement dérivés 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.\"}");

Inférence

Les exemples suivants montrent comment instrumenter les appels d’inférence de modèle IA avec le suivi de l’observabilité pour capturer l’utilisation des jetons, les détails du modèle et les métadonnées de réponse.

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

Si votre assistant utilise le package @microsoft/agents-a365-observability-hosting, vous pouvez utiliser ScopeUtils.populateInferenceScopeFromTurnContext pour créer le scope avec les détails de l’assistant automatiquement dérivés 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);

Sortie

Utilisez ce scope pour les scénarios asynchrones où InvokeAgentScope, ExecuteToolScope ou InferenceScope ne peuvent pas capturer les données de sortie de façon synchrone. Démarrez OutputScope comme span enfant pour enregistrer les messages de sortie finaux une fois l’étendue parente terminée.

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

Valider localement

Pour vérifier que vous avez bien intégré avec le kit de développement logiciel d’observabilité, vérifiez les journaux de console générés par votre assistant ainsi que les journaux issus du kit de développement logiciel d’observabilité.

Python

Définissez la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur false. Ce paramètre exporte les étendues (traces) à la console.

Pour analyser les échecs d’exportation, activez la journalisation détaillée en définissant ENABLE_A365_OBSERVABILITY_EXPORTER sur true et en configurant la journalisation de débogage au démarrage de votre application :

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)

Messages clés du journal :

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

Définissez la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur false. Ce paramètre exporte les étendues (traces) à la console.

Pour étudier les échecs d’exportation, définissez des variables d’environnement dans .env ou shell :

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Vérifiez la sortie console pour des messages tels que :

[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

En option, utilisez un enregistreur personnalisé pour capturer les événements d’exportation dans un fichier :

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

Définissez EnableAgent365Exporter sur false dans appsettings.json. Ce paramètre exporte les étendues (traces) à la console.

Pour enquêter sur les échecs d’exportation, activez le mode de journalisation détaillée dans appsettings.json :

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

Ou définissez les variables d’environnement :

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

Messages clés du journal :

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.

Remarque

Si vous n’inscrivez pas de ILoggerFactory dans DI, l’exportateur bascule automatiquement vers un enregistreur de console.

Affichage des journaux exportés

Pour consulter la télémétrie des assistants dans Microsoft Purview ou Microsoft Defender, assurez-vous que les exigences suivantes sont remplies :

• Microsoft Purview : l’audit doit être activé pour votre organisation. Pour obtenir des instructions, voir Activer ou désactiver l’audit.
• Microsoft Defender : la fonctionnalité de recherche avancée doit être configurée pour accéder à la table CloudAppEvents. Pour plus de détails, voir table CloudAppEvents dans le schéma de recherche avancée.

Validation pour la publication sur le store

Important

Pour une validation réussie du store, votre assistant doit implémenter les InvokeAgentScope, InferenceScope et ExecuteToolScope scopes. Ces trois scopes sont nécessaires pour la publication.

Avant la publication, utilisez les journaux de la console pour valider l’intégration de l’observabilité de votre assistant en implémentant les étendues requises invoke agent, execute tool, inference et output. Comparez ensuite les journaux de votre assistant aux listes d’attributs suivantes pour vérifier que tous les attributs requis sont présents. Capturez les attributs dans chaque étendue ou via le générateur de contexte, et incluez des attributs optionnels à votre discrétion.

Pour plus d’informations sur les exigences de publication dans le store, consultez directives de validation du store.

Attributs InvokeAgentScope

La liste suivante résume les attributs de télémétrie obligatoires et facultatifs enregistrés lorsque vous démarrez un 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"
    }

Attributs ExecuteToolScope

La liste suivante résume les attributs de télémétrie obligatoires et facultatifs enregistrés lorsque vous démarrez un 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"
    }

Attributs InferenceScope

La liste suivante résume les attributs de télémétrie obligatoires et facultatifs enregistrés lorsque vous démarrez un 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"
    }

Attributs OutputScope

La liste suivante résume les attributs de télémétrie obligatoires et facultatifs enregistrés lorsque vous démarrez un OutputScope. Utilisez cette portée pour des scénarios asynchrones où la portée parente ne peut pas capturer les données de sortie de manière synchrone.

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

Tester votre assistant avec l’observabilité

Après avoir implémenté l’observabilité dans votre assistant, testez pour vérifier que la télémétrie est correctement capturée. Suivez le guide de test pour configurer votre environnement. Ensuite, concentrez-vous principalement sur la section Afficher les journaux d’observabilité pour valider que votre implémentation d’observabilité fonctionne comme prévu.

Vérification :

• Accéder à : https://admin.cloud.microsoft/#/agents/all
• Sélectionnez votre assistant > Activité
• Vous voyez des sessions et des appels d’outils

Résolution des problèmes

Cette section décrit les problèmes courants lors de la mise en œuvre et de l’utilisation de l’observabilité.

Problème	Description
Les données d’observabilité n’apparaissent pas	Aucune télémétrie n’est visible car l’exportation n’est pas activée, la configuration est incorrecte ou la résolution du jeton échoue.
ID de locataire ou ID d’assistant manquant : spans ignorés	Les segments sont exclus avant l’exportation lorsque les attributs d’identité requis pour le partitionnement sont manquants.
Échec de résolution de jeton : exportation ignorée ou non autorisée	Les requêtes d’exportation échouent ou sont ignorées lorsque le résolveur ne retourne aucun jeton ou rencontre une exception.
HTTP 401 Non autorisé	L’authentification réussit sur le plan syntaxique, mais le jeton n’est pas valide pour l’ingestion en raison de la portée, du type ou de l’expiration.
HTTP 403 Interdit	L’accès est refusé en raison de lacunes dans les licences locataires ou de l’absence d’autorisations d’observabilité.
HTTP 403 Interdit — incompatibilité d’ID d’assistant	La requête est rejetée lorsque l’identité de l’agent dans l’URL ne correspond pas à celle représentée par le jeton.
Erreurs HTTP 429 ou 5xx - Erreurs transitoires	Une limitation de requêtes temporaire ou des défaillances côté service interrompent l’exportation et peuvent nécessiter un ajustement des paramètres de nouvelle tentative.
Délai d’expiration de l’exportation	Les lots de télémétrie dépassent les délais d’expiration configurés en raison de la latence réseau ou du manque de réactivité de l’endpoint.
L’exportation réussit, mais la télémétrie n’apparaît ni dans Defender ni dans Purview	L’ingestion s’achève, mais la visibilité en aval est retardée ou bloquée par les prérequis du produit.

Astuce

Le Guide de dépannage Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

Les données d’observabilité n’apparaissent pas

Symptômes :

• L’assistant est en cours d’exécution
• Pas de télémétrie dans le centre d’administration
• Impossible de voir l’activité de l’assistant

Cause racine :

• L’observabilité n’est pas activée
• Erreurs de configuration
• Problèmes de résolution de jetons

Solutions : essayez les étapes suivantes pour résoudre le problème :

• Vérifiez que l’exportateur d’observabilité est activé

  Vous devez explicitement activer l’exportateur Agent 365. Lorsqu’il est désactivé, le SDK revient à un exportateur de console et la télémétrie n’est pas envoyée au service. Voir Configuration pour plus d’informations.

• Vérifier la configuration du programme de résolution de jetons

  L’exportateur nécessite un programme de résolution de jetons valide qui renvoie un jeton porteur pour chaque demande d’exportation. Si le résolveur de jeton est manquant ou retourne null, l’exportation est ignorée sans notification. Assurez-vous que votre code implémente correctement le programme de résolution de jetons. Pour plus d’informations, consultez Programme de résolution de jetons.

• Rechercher des erreurs dans les journaux

  Activez la journalisation des informations et utilisez la commande az webapp log tail pour rechercher dans les journaux des erreurs liées à l’observabilité. Pour plus de détails sur la façon d’activer la journalisation par plateforme, voir Valider localement.

  # Look for observability-related errors
  az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
  

• Vérifier l’exportation de télémétrie

  Confirmez que la télémétrie est générée et exportée comme prévu.

  • Ajoutez un exportateur de console et vérifiez si la télémétrie est générée localement. Pour des détails sur l’utilisation de l’exportateur de console et la validation de la sortie, voir Valider localement.

ID de locataire ou ID d’assistant manquant : spans ignorés

Symptômes : le système écarte silencieusement les spans et ne les exporte jamais. Certains SDK consignent un nombre de spans ignorés ou un message tel que « Aucun span trouvé avec l’identité de locataire/assistant ». D’autres les écarteront sans les enregistrer.

Solution :

• Avant l’exportation, le kit de développement logiciel (SDK) partitionne les spans selon l’identité du locataire et de l’assistant. Le système écarte les spans qui n’ont pas d’ID de locataire ou d’ID d’assistant et ne les envoie jamais au service.
• Assurez-vous que BaggageBuilder soit configuré avec l’ID de locataire et l’ID d’assistant avant de créer des spans. Ces valeurs se propagent via le contexte OpenTelemetry et s’attachent à tous les spans créés dans le contexte de bagages. Pour l’API spécifique à la plateforme, consultez Attributs des bagages.
• Vérifiez que l’activité TurnContext dispose d’un destinataire valide avec une identité d’assistant si vous utilisez l’intergiciel de bagages ou l’assistant de contexte de tour du package d’intégration d’hébergement pour renseigner ces ID.

Échec de résolution de jeton : exportation ignorée ou non autorisée

Symptômes : le programme de résolution de jetons renvoie null ou lance une erreur. Selon le kit de développement logiciel, l’exportation est soit entièrement ignorée, soit la requête est envoyée sans en-tête d’autorisation et échoue avec HTTP 401.

Solution :

• Le programme de résolution de jetons est requis lors de l’initialisation. S’il manque, l’exportateur affiche une erreur au démarrage. Vérifiez qu’un programme de résolution de jetons est fourni et retourne un jeton Bearer valide.
• Assurez-vous que l’identifiant de locataire et l’identifiant de l’agent corrects sont transmis à BaggageBuilder, car ces valeurs sont ensuite transmises au programme de résolution de jetons.
• Pour les assistants hébergés sur Azure, vérifiez que l’identité managée dispose des autorisations API requises pour la portée d’observabilité.

HTTP 401 Non autorisé

Symptômes : l’exportation échoue avec HTTP 401. L’exportateur ne réessaie pas cette erreur.

Solution :

• Vérifiez que l’audience du jeton correspond à l’étendue du point de terminaison d’observabilité.
• Vérifiez que le programme de résolution de jetons ne retourne pas un jeton d’utilisateur délégué, un jeton pour un public incorrect ou un jeton expiré.

HTTP 403 Interdit

Symptômes : l’exportation échoue avec HTTP 403. L’exportateur ne réessaie pas cette erreur.

Cause profonde : une erreur HTTP 403 peut avoir différentes causes. Consultez les résolutions suivantes dans l’ordre.

Solution :

• Licence manquante — Assurez-vous que votre locataire dispose de l’une des licences suivantes dans le centre d’administration Microsoft 365 :

  • Test - Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Autorisation Agent365.Observability.OtelWrite manquante : si vous avez récemment mis à niveau vos packages d’observabilité, vous devez accorder cette autorisation. Voir la note importante dans la section suivante.

Important

Les assistants existants à la mise à niveau vers ces versions de package nécessitent une étape supplémentaire

Cette étape ne s’applique que si vous mettez à niveau un assistant existant. L’installation de nouveaux assistants ne nécessite pas cette étape. Si vous mettez à niveau vers les versions suivantes du package ou plus récentes, vous devez accorder la nouvelle autorisation Agent365.Observability.OtelWrite à votre identité (Identité gérée ou enregistrement d’application). Sans cette autorisation, l’exportation de télémétrie échoue avec HTTP 403.

Plateforme	Version minimale nécessitant cette étape
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Autorisez en choisissant l’une des options suivantes.

Option A — CLI Agent 365 (nécessite un compte administrateur global ; exécuter depuis le répertoire du projet de l’assistant contenant a365.config.json, ou utiliser --agent-name)

a365 setup permissions bot

Ou, sans fichier de configuration :

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

Cette commande accorde toutes les autorisations manquantes sur le blueprint, y compris les portées d’observabilité.

Option B : Portail Entra (aucun fichier de configuration requis ; accès administrateur global requis à l’enregistrement de l’application Blueprint)

1. Allez dans le portail Entra>Inscriptions d’applications>, puis sélectionnez votre application Blueprint.
2. Allez dans Autorisations d’API>Ajouter une autorisation>Les API utilisées par mon organisation> recherchez 9b975845-388f-4429-889e-eab1ef63949c.
3. Sélectionnez Autorisations déléguées> cochez Agent365.Observability.OtelWrite>Ajouter des autorisations.
4. Répétez les étapes 2 et 3, cette fois sélectionnez Autorisations d’application> vérifiez Agent365.Observability.OtelWrite>Ajouter des autorisations.
5. Cliquez sur Accorder le consentement d’administrateur et confirmez.

Les deux Agent365.Observability.OtelWrite (délégué) et Agent365.Observability.OtelWrite (Application) doivent afficher l’état Granted.

HTTP 403 Interdit — incompatibilité d’ID d’assistant

Symptômes : l’exportation échoue avec HTTP 403 et un message du serveur similaire à 403 Forbidden, avec des échecs agent-ID-mismatch lors de l’appel aux points de terminaison de traces d’Agent 365.

Cause principale : cette erreur survient lorsque vous utilisez l’ID client blueprint au lieu de l’ID client de l’instance de l’assistant lors de la définition des détails de l’assistant. L’identifiant de l’assistant dans l’URL d’exportation ne correspond pas à l’identité autorisée par le jeton, donc le point de terminaison des traces rejette la requête.

Solution :

• Vérifiez si l’ID de locataire est ajouté à la liste des locataires autorisés d’Agent 365.
• Définissez les détails de l’assistant avec l’ID client de l’instance de l’assistant (et non l’ID client blueprint).
• Vérifiez l’URL d’exportation générée – elle est enregistrée si vous activez votre enregistreur. Confirmez que l’ID de l’assistant dans l’URL correspond à l’ID de l’assistant de l’instance de l’assistant.
• Pour activer la journalisation de diagnostic par kit de développement logiciel, voir Valider localement.

Erreurs HTTP 429 ou 5xx - Erreurs transitoires

Symptômes : l’exportation échoue avec un code de statut HTTP transitoire tel que 429 ou 5xx.

Solution :

• Ces erreurs sont généralement temporaires et se résolvent d’elles-mêmes. Les SDK Python et JavaScript réessaient automatiquement les requêtes en cas de codes d’état HTTP 408, 429 et 5xx jusqu’à trois fois, avec une stratégie de backoff exponentiel. Le SDK .NET ne réessaie pas automatiquement.
• Si les erreurs persistent, vérifiez le tableau de bord de santé du service.
• Envisagez de réduire la fréquence d’exportation en augmentant le délai prévu entre les lots ou en augmentant la taille maximale des lots à exporter. Pour les options de configuration par plateforme, voir la table Agent365ExporterOptions dans Configuration.

Délai d’expiration de l’exportation

Symptômes : les tentatives d’exportation expirent.

Solution :

• Vérifiez la connectivité réseau vers le point d’extrémité d’observabilité.
• Les délais d’expiration par défaut varient selon la plateforme. Le délai de demande HTTP par défaut est de 30 secondes. Certains kit de développement logiciel disposent également d’un délai d’expiration global distinct pour l’exportateur, qui couvre l’ensemble du cycle d’exportation, y compris les tentatives de réessai. Pour les propriétés exactes et les paramètres par défaut par plateforme, voir la table Agent365ExporterOptions dans Configuration.
• Si des délais d’expiration surviennent fréquemment, augmentez la valeur du délai d’expiration pertinente dans les options de votre exportateur.

L’exportation réussit, mais la télémétrie n’apparaît ni dans Defender ni dans Purview

Symptômes : les journaux indiquent une exportation réussie, mais la télémétrie n’est pas visible dans Microsoft Defender ou Microsoft Purview.

Solution :

• Vérifiez que vous remplissez les conditions préalables pour afficher les journaux exportés. Pour Purview, l’audit doit être activé. Pour Defender, il faut configurer la chasse avancée. Pour en savoir plus, consultez Affichage des journaux exportés.
• La télémétrie peut prendre plusieurs minutes pour être renseignée après une exportation réussie. Attendez que les données apparaissent avant d’enquêter davantage.

Pour en savoir plus sur les tests d’observabilité, voir :

• Guide de test - Consultez les journaux d’observabilité
• Configuration de l’observabilité

Contenu associé

• Concepts d’observabilité d’Agent 365 : flux de données, modèles d’identité, authentification, périmètres et limites applicables à chaque chemin d’intégration.
• Référence des attributs d’observabilité Agent 365 : schéma canonique des attributs de span auquel chaque span ingéré par Agent 365 doit se conformer.
• Microsoft OpenTelemetry Distro : le kit de développement logiciel unifié recommandé pour les nouvelles intégrations