SDK di osservabilità deprecato di Agent 365

Installa i pacchetti principali di osservabilità e runtime. Tutti gli agenti che usano Agent 365 Observability necessitano di questi pacchetti.

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

Se l'agente utilizza il pacchetto Microsoft Agents Hosting, è necessario installare il pacchetto di integrazione per l'hosting. Fornisce middleware che popola automaticamente bagagli e ambiti da TurnContexte include la memorizzazione nella cache dei token per l'utilità di esportazione dell'osservabilità.

pip install microsoft-agents-a365-observability-hosting

Se l'agente usa uno dei framework di intelligenza artificiale supportati, installare l'estensione di strumentazione automatica corrispondente per acquisire automaticamente i dati di telemetria senza codice di strumentazione manuale. Per informazioni dettagliate sulla configurazione, vedere Strumentazione automatica.

# 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

Installa i pacchetti principali di osservabilità e runtime. Tutti gli agenti che usano Agent 365 Observability necessitano di questi pacchetti.

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

Se l'agente usa il pacchetto @microsoft/agents-hosting, installare il pacchetto di integrazione dell'hosting. Fornisce middleware che popola automaticamente bagagli e ambiti da TurnContexte include la memorizzazione nella cache dei token per l'utilità di esportazione dell'osservabilità.

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

Se l'agente usa uno dei framework di intelligenza artificiale supportati, installare l'estensione di strumentazione automatica corrispondente per acquisire automaticamente i dati di telemetria senza codice di strumentazione manuale. Per informazioni dettagliate sulla configurazione, vedere Strumentazione automatica.

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

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

Installare il pacchetto principale di osservabilità e runtime. Tutti gli agenti che usano Agent 365 Observability necessitano di questo pacchetto.

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

Se l'agente utilizza il pacchetto NuGet Microsoft.Agents.A365.Observability.Hosting, installare il pacchetto di integrazione dell'hosting. Fornisce middleware che popola automaticamente i dati da TurnContext e include il caching dei token per l'esportatore di osservabilità.

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

Se l'agente usa uno dei framework di intelligenza artificiale supportati, installare l'estensione di strumentazione automatica corrispondente per acquisire automaticamente i dati di telemetria senza codice di strumentazione manuale. Per informazioni dettagliate sulla configurazione, vedere Strumentazione automatica.

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

Imposta la ENABLE_A365_OBSERVABILITY_EXPORTER variabile ambiente a true per l'osservabilità. In Agent 365 SDK 2.0 e versioni successive, l'esportatore utilizza sempre la route service-to-service (S2S) e si autentica con l'autenticazione app-only configurata token_resolver. Se abiliti l'esportatore senza un risolver, Python mantiene il fallback dell'exporter console e non invia telemetria all'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,
)

Il risolver dei token è escluso dal login alla console.

È possibile personalizzare il comportamento del componente di esportazione passando un'istanza Agent365ExporterOptions a exporter_options. Quando exporter_options viene specificato, ha la precedenza sui token_resolver parametri e cluster_category .

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

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

Nella tabella seguente vengono descritti i parametri facoltativi per configure().

Nella tabella seguente vengono descritte le proprietà facoltative per Agent365ExporterOptions.

Imposta la ENABLE_A365_OBSERVABILITY_EXPORTER variabile ambiente a true per l'osservabilità. Nell'Agent 365 SDK 2.0 e versioni successive, l'esportatore utilizza sempre il percorso S2S e si autentica con il token resolver configurato solo per l'app. Se abiliti l'esportatore Agent 365 senza un risolver, la configurazione fallisce.

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

In alternativa alle variabili di ambiente, è possibile configurare l'osservabilità a livello di codice usando un provider di configurazione tramite withConfigurationProvider il metodo . Se si usano anche metodi di generatore singoli (ad esempio withExporterOptions o withClusterCategory), i singoli metodi del generatore hanno la precedenza sui valori del provider di configurazione.

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

È possibile personalizzare il comportamento del componente di esportazione passando un'istanza Agent365ExporterOptions a withExporterOptions. Questa opzione ti permette di controllare il batching e i timeout. Non cambia la rotta di esportazione.

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

Nella tabella seguente vengono descritte le proprietà facoltative per Agent365ExporterOptions.

Puoi anche fornire un logger personalizzato che implementi l'interfaccia ILogger (info, warn, error, event). Passalo al costruttore usando withCustomLogger.

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

builder.start();

Impostare EnableAgent365Exporter su true in appsettings.json. Nell'Agent 365 SDK 2.0 e versioni successive, l'esportatore utilizza sempre il percorso S2S e si autentica con il resolver di token app-only configurato. Se abiliti l'esportatore senza TokenResolver o ContextualTokenResolver, la costruzione dell'esportatore fallisce.

In Program.csaggiungi Agent365ExporterOptions alla raccolta di servizi. Questa modifica configura il delegato che l'esportatore di tracce utilizza per recuperare il token.

Aggiungi dipendenze legate all'osservabilità usando AddA365Tracing().

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Return a cached, validated app-only observability token for this agent and tenant.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

È possibile personalizzare il comportamento dell'esportatore passando un delegato di configurazione e un tipo di esportatore a AddA365Tracing().

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

Nella tabella seguente vengono descritte le proprietà facoltative per 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

Per popolare automaticamente il BaggageBuilder dal TurnContext, usare l'helper populate nel pacchetto microsoft-agents-a365-observability-hosting. Questo helper estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione dall'attività.

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

Per popolare automaticamente il BaggageBuilder dal TurnContext, usare l'helper fromTurnContext nel pacchetto @microsoft/agents-a365-observability-hosting. Questo helper estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione dall'attività.

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.

Per popolare automaticamente il BaggageBuilder dal ITurnContext, usare il metodo di estensione FromTurnContext nel pacchetto Microsoft.Agents.A365.Observability.Hosting. Questo metodo estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione dall'attività.

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

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

Registra BaggageMiddleware nel set di middleware dell'adattatore. Estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione da ogni TurnContext in ingresso e esegue il wrapping della richiesta in un ambito di contesto.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

In alternativa, usare ObservabilityHostingManager per configurare il middleware di contesto insieme ad altre funzionalità di hosting.

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Il middleware ignora la configurazione del bagaglio per risposte asincrone (ContinueConversation eventi) per evitare di sovrascrivere il bagaglio già impostato dalla richiesta di origine.

Eseguire la registrazione BaggageMiddleware nell'adattatore. Estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione da ogni TurnContext in ingresso e esegue il wrapping della richiesta in un ambito di contesto.

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

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

In alternativa, usare ObservabilityHostingManager per configurare il middleware di contesto insieme ad altre funzionalità di hosting.

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

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

Il middleware ignora la configurazione del bagaglio per risposte asincrone (ContinueConversation eventi) per evitare di sovrascrivere il bagaglio già impostato dalla richiesta di origine.

Eseguire la registrazione BaggageTurnMiddleware nell'adattatore. Estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione da ogni ITurnContext in ingresso e esegue il wrapping della richiesta in un ambito di contesto.

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

adapter.Use(new BaggageTurnMiddleware());

Il middleware ignora la configurazione del bagaglio per risposte asincrone (ContinueConversation eventi) per evitare di sovrascrivere il bagaglio già impostato dalla richiesta di origine.

Se è necessario un bagaglio a livello HTTP(ad esempio, per impostare ID tenant e agente prima dell'esecuzione della pipeline di Bot Framework), registrare ObservabilityBaggageMiddleware nella pipeline di ASP.NET Core usando il metodo di estensione UseObservabilityRequestContext. È necessario fornire una funzione resolver che estrae l'ID tenant e l'ID agente dal contesto 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);
});

Chiama AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, acquire_app_only_obs_token) dal tuo token_resolver. La cache trasferisce l'ambito di osservabilità /.default al tuo callback di acquisizione e restituisce il token cacheato.

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 supporta anche un resolver sincrono che restituisce un token da una cache thread-safe. I campioni di Agent 365 utilizzano questo pattern, che evita i vincoli di eseguire un resolver asincrono sul thread di esportazione.

Per migrare dall'SDK 1.x, rimuovere la AGENT_APP.auth.exchange_token chiamata che richiedeva l'ambito di osservabilità e quella AgenticTokenCache.register_observability che passava un AgenticTokenStruct. In SDK 2.0, register_observability è un no-op obsoleto.

Uso di withTokenResolver con AgenticTokenCacheInstance.RefreshObservabilityToken(agentId, tenantId, acquireAppOnlyObsToken). Il callback di acquisizione riceve (agentId, tenantId, scopes) e restituisce il token di osservabilità finale per la sola applicazione. Leggi il token memorizzato nella cache con 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();

Per migrare da SDK 1.x, rimuovere la chiamata agentApplication.authorization.exchangeToken che richiedeva l'ambito di osservabilità e sostituire RefreshObservabilityToken(agentId, tenantId, context, authorization, scopes) con la forma resolver nell'esempio. L'SDK 2.0 elimina il sovraccarico delegato: i chiamanti TypeScript ricevono un errore di compilazione, mentre quelli non tipizzati ricevono un messaggio di errore registrato una sola volta e nessun token.

Usalo AddAgenticTracingExporter() per registrare IExporterTokenCache<ObservabilityTokenResolver> e le opzioni dell'esportatore che leggono i token dalla cache.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Nell'applicazione agente, registra un resolver solo app per l'agente e il tenant chiamando RegisterObservability(agentId, tenantId, resolver, scopes). La prima registrazione per agente e inquilino ha la precedenza.

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

Se gestisci un'istanza AgenticTokenCache direttamente, chiama RefreshObservabilityToken(agentId, tenantId, resolver) per usare l'ambito di osservabilità predefinito, o RefreshObservabilityToken(agentId, tenantId, resolver, scopes) per passare esplicitamente gli ambiti.

Per migrare dall'SDK 1.x, sostituire IExporterTokenCache<AgenticTokenStruct> e la chiamata a RegisterObservability che passava un AgenticTokenStruct con il resolver solo app nell'esempio. Non usare ExchangeTurnTokenAsync per l'esportazione dell'osservabilità. Nell'SDK 2.0, il AgenticTokenStruct sovraccarico di registrazione è obsoleto e causa un errore di compilazione.

Installare il pacchetto .

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

Configura l'osservabilità.

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

Kernel semantico non è supportato con JavaScript.

Aggiungi dipendenze alla raccolta di servizi.

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

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

Imposta AgentId e TenantId usando BaggageBuilder. Assicurati che l'ID che usi per creare un ChatCompletionAgent corrisponda all'ID dell'agente che passi a 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>,
          ...
      };
    }
}

Installare il pacchetto .

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

Configura l'osservabilità.

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

Installare il pacchetto .

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

Configura l'osservabilità.

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

Aggiungi dipendenze alla raccolta di servizi.

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

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

Imposta AgentId e TenantId usando BaggageBuilder. Per le chiamate a strumenti, inizia una traccia utilizzando Trace() su un'istanza ChatToolCall.

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

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

Installare il pacchetto .

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

Configura l'osservabilità.

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 non è supportato con JavaScript.

Aggiungi dipendenze alla raccolta di servizi.

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

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

Imposta AgentId e TenantId usando BaggageBuilder.

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

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

Installare il pacchetto .

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

Configura l'osservabilità.

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

Installare il pacchetto .

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

Configura l'osservabilità.

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 non è supportato con .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();
}

Se l'agente usa il @microsoft/agents-a365-observability-hosting pacchetto, è possibile usare ScopeUtils.populateInvokeAgentScopeFromTurnContext per creare l'ambito con i dettagli dell'agente, i dettagli del chiamante e le informazioni sul canale derivate automaticamente da 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();
}

Se l'agente utilizza il pacchetto @microsoft/agents-a365-observability-hosting, usare ScopeUtils.populateExecuteToolScopeFromTurnContext per creare l'ambito con i dettagli dell'agente derivati automaticamente dal 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();
}

Se il tuo agente utilizza il pacchetto @microsoft/agents-a365-observability-hosting, puoi usare ScopeUtils.populateInferenceScopeFromTurnContext per creare lo scopo con i dettagli dell'agente derivati automaticamente da 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

Impostare la variabile di ambiente ENABLE_A365_OBSERVABILITY_EXPORTER su false. Questa impostazione esporta gli intervalli (tracce) sulla console.

Per analizzare gli errori di esportazione, abilitate la registrazione dettagliata impostando ENABLE_A365_OBSERVABILITY_EXPORTER su true e configurando la registrazione di debug all'avvio dell'applicazione.

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)

Messaggi chiave del log

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

Impostare la variabile di ambiente ENABLE_A365_OBSERVABILITY_EXPORTER su false. Questa impostazione esporta gli intervalli (tracce) sulla console.

Per analizzare gli errori di esportazione, impostare le variabili di ambiente in .env o nella shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Esaminare l'output della console per i messaggi come:

[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

Facoltativamente, usare un logger personalizzato per acquisire gli eventi di esportazione in un file:

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

Impostare EnableAgent365Exporter su false in appsettings.json. Questa impostazione esporta gli intervalli (tracce) sulla console.

Per investigare i guasti di esportazione, configurare la registrazione verbosa in appsettings.json:

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

In alternativa, impostare le variabili di ambiente:

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

Messaggi chiave del log

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