SDK d’observabilité de l’Agent 365 obsolète

Important

Cet article documente le Agent 365 Observability SDK obsolète. Les intégrations existantes continuent de fonctionner, mais n’utilisez pas ce SDK pour les nouvelles intégrations. Pour le nouveau développement, utilisez la distribution OpenTelemetry de Microsoft. Avant de mettre à jour une intégration existante, consultez le guide de migration dans votre langue :

• 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, ainsi que les limites applicables à chaque chemin d’intégration, voir Agent 365 observability concepts.

Note

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

Pour participer à l’écosystème Agent 365, ajoutez des capacités d’observabilité Agent 365 à votre agent. Agent 365 Observability s’appuie sur OpenTelemetry (OTel) et offre un cadre unifié pour capturer la télémétrie de manière cohérente et sécurisée sur toutes les plateformes agents. En implémentant ce composant requis, vous permettez aux administrateurs informatiques de surveiller l’activité de votre agent dans le centre d’administration Microsoft et de permettre aux équipes de sécurité d’utiliser Defender et Purview pour la conformité et la détection des menaces.

Principaux avantages

• Visibilité de bout en bout : Capturez une télémétrie complète pour chaque invocation d’agent, y compris les sessions, appels d’outils et exceptions, vous offrant ainsi une traçabilité complète sur toutes les plateformes.
• Activation de la sécurité et de la conformité : alimentez les journaux d’audit unifiés dans Defender et Purview, ce qui permet des scénarios de sécurité avancés et des rapports de conformité pour votre agent.
• Flexibilité multiplateforme : s’appuyer sur des normes OTel et prendre en charge divers environnements d'exécution et plateformes comme Copilot Studio, Foundry et les futurs frameworks d'agents.
• Efficacité opérationnelle pour les administrateurs : fournissez une observabilité centralisée dans le centre d'administration de Microsoft 365, réduisant le temps de dépannage et améliorant la gouvernance avec des contrôles d'accès basés sur les rôles pour les équipes informatiques qui gèrent votre agent.

Agents pris en charge

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

• Agents compatibles avec Microsoft Agent 365 : utilisez le Kit de développement logiciel (SDK) d’observabilité pour instrumenter votre agent.
• Agents de moteur personnalisés : utilisez le Kit de développement logiciel (SDK) d’observabilité pour instrumenter votre agent.
• Agents déclaratifs : l’observabilité est prise en charge hors de la boîte de dialogue. Aucune implémentation du Kit de développement logiciel (SDK) n’est 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 de base. Tous les agents qui utilisent l’observabilité de l’agent 365 ont besoin de ces packages.

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

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

pip install microsoft-agents-a365-observability-hosting

Si votre agent utilise l’une des infrastructures IA prises en charge, installez l’extension d’instrumentation automatique correspondante pour capturer automatiquement les données de télémétrie sans code d’instrumentation manuel. Pour plus d’informations sur la configuration, consultez l’instrumentation automatique.

# 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 de base. Tous les agents qui utilisent l’observabilité de l’agent 365 ont besoin de ces packages.

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

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

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

Si votre agent utilise l’une des infrastructures IA prises en charge, installez l’extension d’instrumentation automatique correspondante pour capturer automatiquement les données de télémétrie sans code d’instrumentation manuel. Pour plus d’informations sur la configuration, consultez l’instrumentation automatique.

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

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

.NET

Installez le package d’observabilité et d’exécution de base. Tous les agents qui utilisent Agent 365 Observability ont besoin de ce package.

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

Si votre agent utilise le Microsoft. Agents.A365.Observability.Hosting NuGet package, 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 agent utilise l’une des infrastructures IA prises en charge, installez l’extension d’instrumentation automatique correspondante pour capturer automatiquement les données de télémétrie sans code d’instrumentation manuel. Pour plus d’informations sur la configuration, consultez l’instrumentation automatique.

// 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 l’observabilité de l’Agent 365 pour votre agent.

Python

Fixer la ENABLE_A365_OBSERVABILITY_EXPORTER variable environnement à true pour l’observabilité. Dans Agent 365 SDK 2.0 et versions ultérieures, l’exportateur utilise toujours la route service-à-service (S2S) et s’authentifie avec les informations d’identification app-only configurées token_resolver. Si vous activez l'exportateur sans résolveur, Python conserve l’exportateur de console de secours et n'envoie pas de télémétrie à l'Agent 365.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Return a validated app-only observability token for this agent and tenant.
    return "<app-only-observability-token>"

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

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

Vous pouvez personnaliser le comportement de l’exportateur en passant une Agent365ExporterOptions instance à exporter_options. Quand exporter_options est fourni, il prend le pas 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,
)

Le tableau suivant décrit les paramètres facultatifs pour configure().

Paramètre	Description	Default
logger_name	Nom de l’enregistreur d’événements Python utilisé pour le débogage et la sortie du journal de la console.	microsoft_agents_a365.observability.core
exporter_options	Instance Agent365ExporterOptions qui configure ensemble le résolveur de jetons et la catégorie de cluster.	None
suppress_invoke_agent_input	Lorsque True, cela supprime les messages d’entrée sur les portées de InvokeAgent.	False

Le tableau suivant décrit les propriétés facultatives pour Agent365ExporterOptions.

Propriété	Description	Default
use_s2s_endpoint	Obsolète et ignoré. L’Agent 365 SDK 2.0 et versions ultérieures utilise toujours la route S2S, même lorsque cette valeur est False.	False (ignoré)
max_queue_size	Taille de file d’attente maximale pour le processeur par lots.	2048
scheduled_delay_ms	Retard 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 de lot maximale pour les opérations d’exportation.	512

JavaScript

Fixer la ENABLE_A365_OBSERVABILITY_EXPORTER variable environnement à true pour l’observabilité. Dans Agent 365 SDK 2.0 et versions ultérieures, l’exportateur utilise toujours la route S2S et s’authentifie avec le résolveur de jeton d’application uniquement configuré. Si vous activez l’exportateur Agent 365 sans résolveur, la configuration échoue.

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

// Define a token resolver that returns a validated app-only observability token.
const tokenResolver = (agentId, tenantId) => {
    // Your app-only 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 guise d’alternative aux variables d’environnement, vous pouvez configurer l’observabilité par programmation à l’aide d’un fournisseur de configuration par le biais withConfigurationProvider de la méthode. Si vous utilisez également des méthodes de générateur individuelles (par exemple withExporterOptionswithClusterCategory), les méthodes de générateur individuelles sont prioritaires 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 Agent365ExporterOptions instance à withExporterOptions. Cette option vous permet de contrôler le batching et les délais d’attente. Cela ne change pas la route d’exportation.

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

Le tableau suivant décrit les propriétés facultatives pour Agent365ExporterOptions.

Propriété	Description	Default
useS2SEndpoint	Déprécié et ignoré. Agent 365 SDK 2.0 et versions ultérieures utilise toujours la route S2S, même lorsque cette valeur est false.	true (ignoré)
maxQueueSize	Taille de file d’attente maximale pour le processeur par lots.	2048
scheduledDelayMilliseconds	Retard en millisecondes entre les lots d’exportation.	5000
exporterTimeoutMilliseconds	Délai d’expiration en millisecondes pour l’ensemble de l’opération d’exportation.	90000
httpRequestTimeoutMilliseconds	Délai d’expiration en millisecondes pour chaque requête HTTP individuelle vers le back-end.	30000
maxExportBatchSize	Taille de lot maximale 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 constructeur 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 Agent 365 SDK 2.0 et ultérieurs, l’exportateur utilise toujours la route S2S et s’authentifie avec le résolveur de jeton app-only configuré. Si vous activez l’exportateur sans TokenResolver ou ContextualTokenResolver, la construction de l’exportateur échoue.

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.

Ajouter des dépendances liées à l’observabilité en utilisant 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) =>
            {
                // Return a cached, validated app-only observability token for this agent and tenant.
                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
);

Le tableau suivant décrit les propriétés facultatives pour Agent365ExporterOptions.

Propriété	Description	Default
UseS2SEndpoint	Obsolète et ignoré. Agent 365 SDK 2.0 et versions ultérieures utilise toujours la route S2S, même lorsque cette valeur est false.	false (ignoré)
MaxQueueSize	Taille de file d’attente maximale pour le processeur par lots.	2048
ScheduledDelayMilliseconds	Retard en millisecondes entre les lots d’exportation.	5000
ExporterTimeoutMilliseconds	Délai d’expiration en millisecondes pour l’opération d’exportation.	30000
MaxExportBatchSize	Taille de lot maximale pour les opérations d’exportation.	512

Attributs des bagages

Utilisez BaggageBuilder pour définir des informations contextuelles qui transitent par toutes les portées d’une requête. Le SDK implémente un SpanProcessor qui copie toutes les entrées de bagages non vides dans les spans nouvellement lancés sans écraser 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’outil populate dans le package microsoft-agents-a365-observability-hosting. Cette assistance extrait automatiquement l’appelant, l’agent, le client, 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’outil fromTurnContext dans le package @microsoft/agents-a365-observability-hosting. Cette assistance extrait automatiquement l’appelant, l’agent, le client, 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 du ITurnContext, utilisez la méthode d’extension FromTurnContext dans le package Microsoft.Agents.A365.Observability.Hosting. Cette méthode extrait automatiquement l’appelant, l’agent, 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();

Intergiciels de bagages

Si votre agent utilise le package d’intégration d’hébergement, inscrivez l’intergiciel des bagages pour remplir automatiquement les bagages pour chaque demande entrante. Cette étape supprime la nécessité d’appeler BaggageBuilder manuellement dans chaque gestionnaire d’activités.

Python

Enregistrez BaggageMiddleware dans l'ensemble de middlewares de l'adaptateur. Il extrait automatiquement l’appelant, l’agent, le locataire, le canal et les détails de conversation de chaque entrant TurnContext 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 le middleware de gestion des 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 (ContinueConversation événements) 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’agent, le locataire, le canal et les détails de conversation de chaque entrant TurnContext 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 le middleware de gestion des 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 (ContinueConversation événements) 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’agent, le locataire, le canal et les détails de conversation de chaque entrant ITurnContext 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 (ContinueConversation événements) 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’agent 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 programme de résolution qui extrait l’ID de locataire et l’ID de l’agent à partir 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 dans le SDK Agent 365 2.0 et ultérieur, fournissez un résolveur de jeton qui retourne le jeton d’observabilité final réservé à l’application pour l’instance de l’agent exportateur. L’exportateur envoie toujours la télémétrie vers la route S2S et ne bascule pas vers la route déléguée. Une instance d’agent Agent 365 enregistrée n’a pas besoin de l’autorisation Agent365.Observability.OtelWrite ni du consentement administrateur pour exporter sur cette route.

Utilisez l’échange en deux étapes Identité managée fédérée (FMI) pour obtenir le jeton d’application uniquement :

1. Obtenez un jeton blueprint client_credentials pour api://AzureADTokenExchange/.default avec fmi_path défini sur l’ID client de l’instance agent.
2. Obtenez un jeton agent-instance client_credentials pour api://9b975845-388f-4429-889e-eab1ef63949c/.default. Passez le jeton d’étape 1 sous la forme de client_assertion, et définissez client_assertion_type sur urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Pour la configuration complète de l’authentification, voir Agent 365 compatible S2S. Pour des implémentations complètes de service de jetons, voir les exemples Agent 365 pour Node.js, Python et .NET.

Votre résolveur DNS doit :

• Retournez un jeton d’application uniquement pour l’instance de l’agent d’exportation et le locataire. Ne retournez jamais l’assertion intermédiaire de blueprint, un jeton blueprint, un token utilisateur ou un token OBO.
• Validez le jeton avant de le renvoyer. Acceptez idtyp=app. Si idtyp est absent, on n’accepte qu’un jeton ayant une déclaration roles non vide ou une déclaration oid non vide égale à sub. Rejetez les jetons qui ont une revendication scp ou une autre valeur idtyp, les jetons expirés, et ceux dont aud n’est ni 9b975845-388f-4429-889e-eab1ef63949c ni api://9b975845-388f-4429-889e-eab1ef63949c.
• Mettez le jeton en cache et rafraîchissez-le avant qu’il n’expire. L’exportateur appelle le résolveur une fois pour chaque locataire et chaque identité d’agent dans chaque lot d’exportation.

Note

Migrer depuis le SDK 1.x : Le SDK 2.0 supprime l’échange de jetons délégué pour l’exportation d’observabilité. Remplacez le code de jeton délégué dans votre agent par un résolveur uniquement applicatif, comme montré dans les exemples suivants. Les agents qui restent sur le SDK 1.x et exportent sur la route déléguée ont toujours besoin de l’autorisation déléguée Agent365.Observability.OtelWrite et du consentement administrateur. La commande a365 setup all ne configure pas cette permission pour les agents blueprint. Pour l’accorder, consultez Accorder l’autorisation.

Python

Appelez AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, acquire_app_only_obs_token) depuis votre token_resolver. Le cache transmet le scope d’observabilité /.default à votre callback d’acquisition et retourne le jeton mis en cache.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import AgenticTokenCache

cache = AgenticTokenCache()

async def acquire_app_only_obs_token(
    agent_id: str,
    tenant_id: str,
    scopes: list[str],
) -> str:
    # Run the FMI exchange described earlier, validate the token, and return it.
    return "<app-only-observability-token>"

async def token_resolver(agent_id: str, tenant_id: str) -> str:
    return await cache.refresh_observability_token(
        agent_id, tenant_id, acquire_app_only_obs_token
    )

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

Python prend également en charge un résolveur synchrone qui renvoie un jeton depuis un cache sécurisé pour threads. Les exemples Agent 365 utilisent ce schéma, ce qui évite les contraintes d’exécuter un résolveur asynchrone sur le thread exportateur.

Pour migrer depuis le SDK 1.x, supprimez l’appel AGENT_APP.auth.exchange_token qui demandait le scope d’observabilité et celui AgenticTokenCache.register_observability qui transmettait un AgenticTokenStruct. Dans le SDK 2.0, register_observability est un no-op déprécié.

JavaScript

utiliser withTokenResolver avec AgenticTokenCacheInstance.RefreshObservabilityToken(agentId, tenantId, acquireAppOnlyObsToken). Le callback d’acquisition reçoit (agentId, tenantId, scopes) et retourne le jeton d’observabilité final de l’application seule. Lisez le jeton mis en cache avec AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId).

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

async function acquireAppOnlyObsToken(
  agentId: string,
  tenantId: string,
  scopes: readonly string[]
): Promise<string> {
  // Run the FMI exchange described earlier, validate the token, and return it.
  return "<app-only-observability-token>";
}

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver(async (agentId, tenantId) => {
      await AgenticTokenCacheInstance.RefreshObservabilityToken(
        agentId, tenantId, acquireAppOnlyObsToken
      );
      return AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId);
    })
);

builder.start();

Pour migrer depuis le SDK 1.x, supprimez l’appel agentApplication.authorization.exchangeToken qui demandait la portée d’observabilité, et remplacez RefreshObservabilityToken(agentId, tenantId, context, authorization, scopes) par la forme du résolveur dans l’exemple. Le SDK 2.0 supprime la surcharge déléguée : les appelants TypeScript reçoivent une erreur de compilation, et ceux non typés obtiennent une entrée de journal d’erreur consignée une seule fois et aucun jeton.

.NET

Utilisez AddAgenticTracingExporter() pour enregistrer IExporterTokenCache<ObservabilityTokenResolver> et les options de l’exportateur qui lisent les jetons du cache.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Dans l’application d’agent, enregistrez un resolveur application uniquement pour l’agent et le locataire en appelant RegisterObservability(agentId, tenantId, resolver, scopes). La première inscription pour un agent et un locataire est retenue.

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

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<ObservabilityTokenResolver> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<ObservabilityTokenResolver> agentTokenCache)
        : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var agentId = turnContext.Activity.Recipient.AgenticAppId;
        var tenantId = turnContext.Activity.Recipient.TenantId;

        _agentTokenCache.RegisterObservability(
            agentId,
            tenantId,
            AcquireAppOnlyObservabilityTokenAsync,
            EnvironmentUtils.GetObservabilityAuthenticationScope());

        using var baggageScope = new BaggageBuilder()
            .TenantId(tenantId)
            .AgentId(agentId)
            .Build();

        // Handle the message.
    }

    private static Task<string?> AcquireAppOnlyObservabilityTokenAsync(
        string agentId,
        string tenantId,
        string[] observabilityScopes)
    {
        // Run the FMI exchange described earlier, validate the token, and return it.
        return Task.FromResult<string?>("<app-only-observability-token>");
    }
}

Si vous gérez une AgenticTokenCache instance directement, appelez RefreshObservabilityToken(agentId, tenantId, resolver) pour utiliser le scope d’observabilité par défaut, ou RefreshObservabilityToken(agentId, tenantId, resolver, scopes) pour passer explicitement des scopes.

Pour migrer depuis le SDK 1.x, remplacez IExporterTokenCache<AgenticTokenStruct> et l’appel RegisterObservability qui transmettait un AgenticTokenStruct par le résolveur de l’application uniquement dans l’exemple. N’utilisez pas ExchangeTurnTokenAsync pour l’export d’observabilité. Dans le SDK 2.0, la surcharge d’enregistrement AgenticTokenStruct est obsolète et produit une erreur de compilation.

Instrumentation automatique

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. Cette fonctionnalité élimine le besoin pour les développeurs d’écrire manuellement du code de surveillance, simplifie la configuration et assure un suivi cohérent des performances.

Important

L’instrumentation automatique renseigne uniquement les attributs standard OTel. Vous devez ajouter des attributs spécifiques à Microsoft via 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.

Plusieurs SDK et plateformes prennent en charge l’auto-instrumentation :

Platform	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

Note

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 d’un baggage builder. Définissez l’ID de l’agent et l’ID du locataire en utilisant 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

Le Noyau sémantique n'est pas pris en charge par JavaScript.

.NET

Ajoutez des dépendances à la collection de services.

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

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

On peut définir AgentId et TenantId en utilisant BaggageBuilder. Assurez-vous que l’identifiant que vous utilisez lors de la création d’un ChatCompletionAgent correspond à l’identifiant de l’agent que vous transmettez à 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 d’un générateur de baggage. Définissez l’ID de l’agent et l’ID du locataire en utilisant 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());

On peut définir AgentId et TenantId en utilisant BaggageBuilder. Pour les appels d’outils, lancez une trace en utilisant Trace() sur une ChatToolCall instance.

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

Infrastructure de l’agent

L’instrumentation automatique nécessite l’utilisation d’un baggage builder. Définissez l’ID de l’agent et l’ID du locataire en utilisant 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 par JavaScript.

.NET

Ajoutez des dépendances à la collection de services.

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

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

On peut définir AgentId et TenantId en utilisant 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();
    }
}

Cadre LangChain

Note

L’instrumentation automatique pour l’infrastructure LangChain prend également en charge LangGraph et Deep Agents. La même extension capture automatiquement la télémétrie des agents créés avec l’un de ces frameworks.

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’ID de l’agent et l’ID du locataire en utilisant 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 avec .NET.

Instrumentation manuelle

Utilisez le SDK d’observabilité de l’Agent 365 pour comprendre le fonctionnement interne de l’agent. Le Kit de développement logiciel (SDK) fournit des étendues que vous pouvez démarrer : InvokeAgentScope, ExecuteToolScope, InferenceScope, et OutputScope.

Invocation de l’agent

Utilisez cette portée au début de votre processus d’agent. En utilisant la portée de l’agent invoke, vous pouvez capturer des propriétés comme l’agent en cours d’invocation, les données utilisateur de l’agent, et plus encore.

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 agent utilise le paquet @microsoft/agents-a365-observability-hosting, vous pouvez utiliser ScopeUtils.populateInvokeAgentScopeFromTurnContext pour créer l’étendue avec les détails de l’agent, les détails de l’appelant et les informations de canal dérivées automatiquement 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 montrent comment ajouter un suivi d'observabilité à l'exécution des outils de votre agent. 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 agent utilise le paquet @microsoft/agents-a365-observability-hosting, utilisez ScopeUtils.populateExecuteToolScopeFromTurnContext pour créer la portée avec les détails de l'agent automatiquement dérivés du 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 agent utilise le @microsoft/agents-a365-observability-hosting package, vous pouvez utiliser ScopeUtils.populateInferenceScopeFromTurnContext pour créer l’étendue avec les détails de l’agent automatiquement dérivés du 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);

Output

Utilisez cette étendue pour les scénarios asynchrones où InvokeAgentScope, ExecuteToolScopeou InferenceScope ne peut pas capturer les données de sortie de manière synchrone. Commencez OutputScope en tant qu’étendue 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 réussi à vous intégrer avec le SDK d’observabilité, examinez les journaux de console générés par votre agent ainsi que les journaux issus du SDK d’observabilité.

Python

Définissez la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur false. Ce réglage exporte les spans (traces) vers la console.

Pour examiner les échecs d’exportation, activez la journalisation détaillée en définissant ENABLE_A365_OBSERVABILITY_EXPORTERtrue 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 de journal clés :

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 réglage exporte les spans (traces) vers la console.

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

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Passez en revue la sortie de la console pour les 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

Si vous le souhaitez, utilisez un enregistreur d’événements personnalisé pour capturer des événements d’exportation vers 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 réglage exporte les spans (traces) vers la console.

Pour examiner les échecs d’exportation, configurez la journalisation détaillée dans appsettings.json:

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

Ou définissez des 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 de journal clés :

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.

Note

Si vous n’inscrivez pas de ILoggerFactory dans DI, l’exportateur revient automatiquement à un journaliseur de console.

Affichage des journaux exportés

Pour consulter la télémétrie des agents dans Microsoft Purview ou Microsoft Defender, assurez-vous de respecter les exigences suivantes :

• Microsoft Purview : l’audit doit être activé pour votre organisation. Pour obtenir des instructions, consultez Activer ou désactiver l’audit.
• Microsoft Defender : la recherche avancée doit être configurée pour permettre l'accès à la table CloudAppEvents. Pour plus d’informations, consultez la table CloudAppEvents dans le schéma de repérage avancé.

Validation pour la publication en boutique

Important

Pour une validation réussie de la boutique, votre agent doit implémenter les périmètres InvokeAgentScope, InferenceScope et ExecuteToolScope. Ces trois étendues sont requises pour la publication.

Avant de publier, utilisez les journaux de console pour valider votre intégration d’observabilité pour l’agent en implémentant les étendues requises invoke agent, execute tool, inference, et output. Ensuite, comparez les journaux de votre agent avec les listes d’attributs suivantes pour vérifier que tous les attributs requis sont présents. Capturez les attributs dans chaque portée 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 en magasin, consultez les directives de validation des magasins.

Attributs InvokeAgentScope

La liste suivante résume les attributs de télémétrie requis et optionnels 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 requis et optionnels 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 requis et optionnels 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 requis et optionnels enregistrés lorsque vous démarrez un OutputScope. Utilisez cette étendue pour les scénarios asynchrones où l’étendue 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"
    }

Testez votre agent avec l’observabilité

Après avoir implémenté l’observabilité dans votre agent, testez-la pour vous assurer qu’elle capture correctement les données de télémétrie. Suivez le guide de test pour configurer votre environnement. Ensuite, concentrez-vous principalement sur la section Afficher les journaux d’observation pour valider votre implémentation d’observabilité fonctionne comme prévu.

Vérification :

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

Troubleshooting

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 de jeton échoue.
ID du locataire ou ID de l’agent manquant - segments ignorés	Les segments sont exclus avant l’exportation lorsque les attributs d’identité requis pour le partitionnement sont manquants.
Échec de la résolution du jeton - export ignoré ou non autorisé	L’exportation échoue 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 la licence du locataire, d’une absence d’enregistrement Agent 365, ou d’une autorisation d’observabilité manquante lorsqu’elle est requise.
HTTP 403 Interdit - Incompatibilité de l’ID de l’agent	La demande est rejetée lorsque l’identité de l’agent dans l’URL ne correspond pas à l’identité représentée par le jeton.
Erreurs HTTP 429 ou 5xx - Erreurs temporaires	Un bridage 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 d’exportation	Les lots de télémétrie dépassent les fenêtres de délai d’attente configurées en raison de la latence réseau ou de la réactivité du point de terminaison.
L'exportation réussit, mais la télémétrie n'apparaît pas dans Defender ou Purview	L’ingestion se termine, mais la visibilité en aval est retardée ou bloquée par les prérequis du produit.

Tip

Le Guide de dépannage de l’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’agent est en fuite
• Pas de télémétrie dans le centre administratif
• Impossible de voir l’activité des agents

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érifier que l’exportateur d’observabilité est activé

  Vous devez activer explicitement l’exportateur Agent 365. En cas de désactivation, le SDK revient à un exportateur de console et la télémétrie n’est pas envoyée au service. Pour plus d’informations sur la configuration, consultez Configuration.

• Vérifier la configuration du résolveur de jeton

  L’exportateur nécessite un résolveur de jeton valide qui renvoie un jeton d’observabilité d’application uniquement pour chaque demande d’exportation. Si le résolveur est absent, ne renvoie aucun jeton ou lève une exception, l’export n’envoie pas de requête. Assurez-vous que votre code implémente le résolveur de jetons. Pour plus d’informations, consultez résolveur de jeton.

• Vérifier les erreurs dans les journaux

  Activez la journalisation détaillée et utilisez la commande pour rechercher des erreurs liées à l’observabilitéaz webapp log tail. Pour plus d’informations sur l’activation de la journalisation par plateforme, consultez 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 plus d’informations sur l’utilisation de l’exportateur de console et la validation de la sortie, consultez Valider localement.

ID de locataire ou ID d’agent manquant : sections ignorées

Symptômes: Le système supprime silencieusement les étendues et ne les exporte jamais. Certains SDK consigneront un nombre d’étendues ignorées ou un message tel que « Aucune étendue avec l’identité de locataire/agent trouvée ». D’autres les supprimeront sans les enregistrer.

Résolution :

• Avant l'exportation, le Kit de développement logiciel (SDK) partitionne les intervalles selon l'identité du locataire et de l'agent. Le système supprime les portées qui n’ont pas d’ID de locataire ou d’ID d’agent et ne les envoie jamais au service.
• Vérifiez que BaggageBuilder soit configuré avec l’ID de locataire et l’ID de l’agent avant de créer des spans. Ces valeurs se propagent via le contexte OpenTelemetry et s’attachent à toutes les traces créées dans le contexte du baggage. Pour obtenir l’API spécifique à la plateforme, consultez les attributs de bagages.
• Vérifiez que l’activité TurnContext a un destinataire valide avec l’identité de l’agent si vous utilisez l’intergiciel de bagages ou tournez l’assistance de contexte à partir du package d’intégration d’hébergement pour remplir ces ID.

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

Symptômes : Le résolveur de jeton renvoie null, renvoie un jeton vide, ou lance une erreur. L’exportation échoue sans envoyer de requête, et l’exportateur ne bascule pas sur la route déléguée.

Résolution :

• Fournir un résolveur qui renvoie le jeton d’observabilité final en mode application seule pour l’instance et le locataire de l’agent d’exportation.
• Vérifiez que l’ID de locataire et l’ID d’agent appropriés sont utilisés pour BaggageBuilder, car ces valeurs sont passées au programme de résolution de jeton.
• Vérifiez le comportement de démarrage spécifique à la langue. la configuration de Node.js échoue lorsque l’exportateur Agent 365 est activé sans résolveur, .NET échoue à construire l’exportateur, et Python revient à l’exportateur console lorsqu’aucun résolveur n’est configuré.
• Vérifiez que votre résolveur valide le jeton avant de le retourner. Il doit rejeter les jetons délégués avec une scp claim ainsi que ceux émis pour la mauvaise audience.

HTTP 401 Non autorisé

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

Résolution :

• Vérifiez que l’audience du jeton est 9b975845-388f-4429-889e-eab1ef63949c ou api://9b975845-388f-4429-889e-eab1ef63949c.
• Vérifiez que le résolveur de jeton ne retourne pas un jeton utilisateur délégué, un jeton avec une revendication scp, un jeton pour un destinataire incorrect ou un jeton expiré.
• Confirmez que le résolveur retourne le jeton final d’instance d’agent, et non l’assertion intermédiaire du plan.

HTTP 403 Interdit

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

Cause: Une erreur HTTP 403 peut avoir des causes différentes. Vérifiez les résolutions suivantes dans l’ordre.

Résolution :

• Licence manquante — Vérifiez que votre client dispose de l'une des licences suivantes attribuées dans le Centre d'administration Microsoft 365 :

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

• L’instance de l’agent n’est pas enregistrée — La route S2S n’accepte un jeton d’application uniquement sans le rôle Agent365.Observability.OtelWrite que d’une instance d’agent enregistrée par Agent 365. Sinon, il retourne HTTP 403 insufficient_scope. Pour les agents blueprint, a365 setup all enregistre l’instance de l’agent. Pour relancer un enregistrement échoué, exécutez a365 setup all --agent-registration-only. Créer une identité Microsoft Entra seule ne permet pas d'enregistrer l'instance de l'agent.

• Le jeton n’est pas réservé à l’application — Vérifiez que le jeton ne contient pas de claim scp. La route S2S nécessite un jeton d’application uniquement.

• L’identité non enregistrée n’a pas le rôle d’application — Les identités non enregistrées, y compris les enregistrements standards d’applications utilisées par les agents de moteurs personnalisés, nécessitent le rôle d’application Agent365.Observability.OtelWrite . Pour l’accorder, consultez Accorder l’autorisation.

• Agent SDK 1.x sur la route déléguée — La route déléguée nécessite l’autorisation déléguée Agent365.Observability.OtelWrite et le consentement administrateur, que a365 setup all ne configure pas pour les agents blueprint. Mettez à niveau vers le SDK 2.0, ou accordez l’autorisation.

• L’identifiant de l’agent ne correspond pas au jeton — voir HTTP 403 Forbidden - Incompatibilité d’identifiant d’agent.

HTTP 403 Interdit — Incompatibilité de l’ID de l’agent

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 traçage d’Agent 365.

Cause: Cette erreur se produit lorsque vous utilisez l’ID client du blueprint au lieu de l’ID client de l’instance de l’agent lors de la définition des détails de l’agent. L’ID de l’agent dans l’URL d’exportation ne correspond pas à l’identité autorisée par le jeton. Par conséquent, le point de terminaison de trace rejette la requête.

Résolution :

• Vérifiez si l’identifiant du locataire figure dans la liste des locataires autorisés d’Agent 365.
• Définissez les détails de l’agent avec l’ID client de l’instance de l’agent (et non l’ID client du blueprint).
• Vérifiez l’URL d’exportation générée : elle est journalisée si vous activez votre enregistreur d’événements. Vérifiez que l’ID de l’agent dans l’URL correspond à l’ID client de l’instance de l’agent.
• Pour activer la journalisation des diagnostics par kit SDK, consultez Valider localement.

Erreurs HTTP 429 ou 5xx - Erreurs temporaires

Symptômes: L’exportation échoue avec un code d’état HTTP temporaire tel que 429 ou 5xx.

Résolution :

• Ces erreurs sont généralement temporaires et résolues par elles-mêmes. Les SDK Python et JavaScript tentent de nouveau automatiquement sur les codes d’état HTTP 408, 429 et 5xx jusqu’à trois fois avec une temporisation exponentielle. Le sdk .NET ne réessaye pas automatiquement.
• Si les erreurs persistent, consultez le tableau de bord d’intégrité du service.
• Envisagez de réduire la fréquence d’exportation en augmentant le délai planifié entre les lots ou en augmentant la taille maximale du lot d’exportation. Pour connaître les options de configuration par plateforme, consultez le Agent365ExporterOptions tableau dans Configuration.

Délai d’expiration de l’exportation

Symptômes: Les tentatives d’exportation expirent.

Résolution :

• Vérifiez la connectivité réseau au point de terminaison d’observabilité.
• Les valeurs par défaut du délai d’expiration varient selon la plateforme. Le délai d’expiration de la requête HTTP par défaut est de 30 secondes. Certains kits SDK ont également un délai d’expiration global d’exportation distinct qui couvre l’ensemble du cycle d’exportation, y compris les nouvelles tentatives. Pour connaître les propriétés exactes et les valeurs par défaut par plateforme, consultez la Agent365ExporterOptions table dans Configuration.
• Si des délais d’expiration se produisent fréquemment, augmentez la valeur de délai d’expiration appropriée dans vos options d’exportation.

L'exportation réussit, mais la télémétrie n'apparaît pas dans Defender ou Purview

Symptoms : Les journaux indiquent une exportation réussie, mais la télémétrie n'est pas visible dans Microsoft Defender ou Microsoft Purview.

Résolution :

• Vérifiez que vous remplissez les conditions préalables à l’affichage des journaux exportés. Pour Purview, l’audit doit être activé. Pour Defender, vous devez configurer la chasse avancée. Pour en savoir plus, consultez Consulter les journaux exportés.
• La télémétrie peut prendre plusieurs minutes pour se mettre à jour après une exportation réussie. Attendez que les données apparaissent avant d’examiner plus en détail.

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

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

Contenu connexe

• Concepts d’observabilité de l’agent 365 : flux de données, modèles d’identité, authentification, étendues et limites qui s’appliquent à chaque chemin d’intégration.
• Référence d’attribut d’observabilité de l’agent 365 : schéma d’attribut d’étendue canonique auquel chaque étendue ingérée par l’agent 365 doit être conforme.
• Microsoft OpenTelemetry Distro - Kit de développement logiciel (SDK) unifié recommandé pour les nouvelles intégrations.