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

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

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

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

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

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

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 voie 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.

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

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.

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

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

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

Enregistrez BaggageMiddleware dans l'ensemble de middlewares de 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.

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 (événements ContinueConversation) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

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 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 (événements ContinueConversation) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

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

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é.

utiliser withTokenResolver avec AgenticTokenCacheInstance.RefreshObservabilityToken(agentId, tenantId, acquireAppOnlyObsToken). Le rappel d’acquisition reçoit (agentId, tenantId, scopes) et renvoie le jeton d’observabilité d’application uniquement final. 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 à partir du SDK 1.x, supprimez l’appel agentApplication.authorization.exchangeToken qui demandait l’étendue d’observabilité, puis remplacez RefreshObservabilityToken(agentId, tenantId, context, authorization, scopes) par la forme utilisant un résolveur présentée 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.

Utilisez AddAgenticTracingExporter() pour inscrire 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’assistant, inscrivez un résolveur de jetons d’application uniquement pour l’assistant 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.

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

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

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>,
          ...
      };
    }
}

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

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

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

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

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

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

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

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

LangChain n'est pas pris en charge avec .NET.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Définissez la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur false. Ce réglage exporte les spans (traces) vers 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 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.

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

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.