Osservabilità dell'agente

Importante

È necessario far parte del programma di anteprima Frontier per ottenere l'accesso early a Microsoft Agent 365. Frontier ti connette direttamente con le ultime innovazioni di intelligenza artificiale di Microsoft. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

Per partecipare all'ecosistema Agent 365, aggiungi capacità di osservabilità Agent 365 al tuo agente. Agent 365 Observability si basa su OpenTelemetry (OTel) e fornisce un framework unificato per catturare telemetria in modo coerente e sicuro su tutte le piattaforme agent. Implementando questo componente necessario, si abilitano gli amministratori IT a monitorare l'attività dell'agente nell'interfaccia di amministrazione di Microsoft e consentire ai team di sicurezza di usare Defender e Purview per la conformità e il rilevamento delle minacce.

Vantaggi chiave

• Visibilità end-to-end: acquisisci dati di telemetria completi per ogni chiamata dell'agente, incluse sessioni, chiamate agli strumenti ed eccezioni, offrendo la tracciabilità completa tra le piattaforme.
• Abilitazioni di sicurezza e conformità: inserire log di controllo unificati in Defender e Purview, abilitando scenari di sicurezza avanzati e report di conformità per l'agente.
• Flessibilità multipiattaforma: Basarsi sugli standard OTel e supportare runtime e piattaforme diverse, come Copilot Studio, Foundry e futuri framework di agenti.
• Efficienza operativa per gli amministratori: offrire un'osservabilità centralizzata in interfaccia di amministrazione di Microsoft 365, ridurre i tempi di risoluzione dei problemi e migliorare la governance con i controlli degli accessi in base al ruolo per i team IT che gestiscono l'agente.

Installazione

Usa questi comandi per installare i moduli di osservabilità per le lingue supportate da Agent 365.

Python

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

JavaScript

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

.NET

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

Configurazione

Usa le seguenti impostazioni per abilitare e personalizzare l'Osservabilità dell'Agente 365 per il tuo agente.

Python

Imposta la ENABLE_A365_OBSERVABILITY_EXPORTER variabile ambiente a true per l'osservabilità. Questa impostazione esporta i log nel servizio e richiede che venga fornito un oggetto token_resolver . Altrimenti, viene utilizzato l'esportatore della console.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Implement secure token retrieval here
    return "Bearer <token>"

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

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

Parametro	Descrizione	Default
logger_name	Nome del logger Python usato per il debug e l'output del log della console.	microsoft_agents_a365.observability.core
exporter_options	Agent365ExporterOptions Istanza che configura insieme il sistema di risoluzione dei token e la categoria di cluster.	None
suppress_invoke_agent_input	Quando True, elimina i messaggi di input su InvokeAgent intervalli.	False

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

Proprietà	Descrizione	Default
use_s2s_endpoint	Quando True, utilizza il percorso dell'endpoint tra servizi.	False
max_queue_size	Dimensione massima della coda per il processore batch.	2048
scheduled_delay_ms	Ritardo in millisecondi tra batch di esportazione.	5000
exporter_timeout_ms	Timeout in millisecondi per l'operazione di esportazione.	30000
max_export_batch_size	Dimensioni massime del batch per le operazioni di esportazione.	512

JavaScript

Imposta la ENABLE_A365_OBSERVABILITY_EXPORTER variabile ambiente a true per l'osservabilità. Questa impostazione esporta i log nel servizio e richiede che venga fornito un sistema di risoluzione dei token. Altrimenti, viene utilizzato l'esportatore della console.

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

// Define a token resolver to authenticate with the observability service for exporting logs
const tokenResolver = (agentId, tenantId) => {
    // Your token resolution logic here
    return "your-token";
};

// Advanced configuration with builder pattern
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

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 consente di controllare l'invio in batch, i timeout e la modalità di route.

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.

Proprietà	Descrizione	Default
useS2SEndpoint	Quando true, utilizza il percorso dell'endpoint tra servizi.	false
maxQueueSize	Dimensione massima della coda per il processore batch.	2048
scheduledDelayMilliseconds	Ritardo in millisecondi tra batch di esportazione.	5000
exporterTimeoutMilliseconds	Timeout in millisecondi per l'intera operazione di esportazione.	90000
httpRequestTimeoutMilliseconds	Timeout in millisecondi per ogni singola richiesta HTTP al back-end.	30000
maxExportBatchSize	Dimensioni massime del batch per le operazioni di esportazione.	512

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

.NET

Impostare EnableAgent365Exporter su true in appsettings.json.

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) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                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.

Proprietà	Descrizione	Default
UseS2SEndpoint	Quando true, utilizza il percorso dell'endpoint tra servizi.	false
MaxQueueSize	Dimensione massima della coda per il processore batch.	2048
ScheduledDelayMilliseconds	Ritardo in millisecondi tra batch di esportazione.	5000
ExporterTimeoutMilliseconds	Timeout in millisecondi per l'operazione di esportazione.	30000
MaxExportBatchSize	Dimensioni massime del batch per le operazioni di esportazione.	512

Attributi di bagaglio

Utilizza BaggageBuilder per impostare informazioni contestuali che passano attraverso tutti gli intervalli di una richiesta. L'SDK implementa una SpanProcessor copia di tutte le voci di baggage non interrotte in intervalli appena avviati senza sovrascrivere gli attributi esistenti.

Python

from microsoft_agents_a365.observability.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

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

JavaScript

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

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

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

.NET

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

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

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

Middleware per la gestione dei bagagli

Se l'agente usa il pacchetto di integrazione dell'hosting, registrare il middleware del bagaglio per popolare automaticamente i bagagli per ogni richiesta in ingresso. Questo passaggio rimuove la necessità di chiamare BaggageBuilder manualmente in ogni gestore attività.

Python

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.

JavaScript

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 arrivo ed racchiude la 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, utilizzare ObservabilityHostingManager per configurare il middleware per i dati accessori 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.

.NET

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 entrata e avvolge la 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);
});

Sistema di risoluzione dei token

Quando si usa l'utilità di esportazione di Agent 365, è necessario fornire una funzione resolver token che restituisce un token di autenticazione. Quando si utilizza l'Agent 365 Observability SDK con il framework di hosting dell'agente, è possibile generare token utilizzando il TurnContext dalle attività dell'agente.

Python

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

Per lo scenario di lavoro digitale, se l'agente usa il pacchetto Microsoft Agent 365 Observability Hosting Library, usare AgenticTokenCache per gestire automaticamente la memorizzazione nella cache dei token. Registrare il token una volta per agente e tenant durante un gestore di attività e passare cache.get_observability_token come token_resolver nella configurazione di osservabilità.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

JavaScript

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

const storage = new MemoryStorage();

export const agentApplication = new AgentApplication<ApplicationTurnState>({
  authorization: {
    agentic: {}, // We have the type and scopes set in the .env file
  },
  storage,
});

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const aauAuthToken = await agentApplication.authorization.exchangeToken(context, 'agentic', {
      scopes: getObservabilityAuthenticationScope()
    });
    // cache this auth token and return via token resolver
  }
);

Per lo scenario del lavoratore digitale, se il tuo agente usa il pacchetto @microsoft/agents-a365-observability-hosting, usa AgenticTokenCacheInstance per gestire automaticamente la memorizzazione nella cache dei token. Chiamare RefreshObservabilityToken una volta per agente e tenant durante un gestore attività e passare AgenticTokenCacheInstance.getObservabilityToken come tokenResolver nella configurazione di osservabilità.

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

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

.NET

Fornire un resolver di token eseguendo la registrazione Agent365ExporterOptions con un TokenResolver delegato. Il delegato riceve agentId e tenantId restituisce un token di autenticazione.

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

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Implement your token retrieval logic here
                return await GetTokenAsync(agentId, tenantId);
            }
        };
    });

Per lo scenario di lavoro digitale, se l'agente usa il pacchetto NuGet Microsoft.Agents.A365.Observability.Hosting, usa il metodo AddAgenticTracingExporter() per gestire automaticamente la memorizzazione nella cache dei token tramite l'inserimento delle dipendenze.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Nell'applicazione dell'agente, registra il token.

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

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct(
                    userAuthorization: UserAuthorization,
                    turnContext: turnContext,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Strumentazione automatica

La strumentazione automatica rileva automaticamente i segnali di telemetria esistenti dai framework agentici (SDK) per il tracciamento e li inoltra al servizio di osservabilità di Agent 365. Questa funzione elimina la necessità per gli sviluppatori di scrivere manualmente il codice di monitoraggio, semplifica la configurazione e garantisce un monitoraggio costante delle prestazioni.

Molteplici SDK e piattaforme supportano l'auto-strumentazione:

Piattaforma	SDK/framework supportati
.NET	Kernel semantico, OpenAI, Agent Framework
Python	Kernel semantico, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Nota

Il supporto per la strumentazione automatica varia in base all'implementazione della piattaforma e dell'SDK.

Nucleo Semantico

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

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

JavaScript

Kernel semantico non è supportato con JavaScript.

.NET

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

OpenAI

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

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

JavaScript

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

.NET

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 agli strumenti, avvia una traccia usando Trace() in 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>);
    }
}

Framework dell'agente

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

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

JavaScript

Agent Framework non è supportato con JavaScript.

.NET

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

Framework di LangChain

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

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

JavaScript

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

.NET

LangChain non è supportato con .NET.

Strumentazione manuale

Usa l'SDK di osservabilità dell'Agent 365 per comprendere il funzionamento interno dell'agente. L'SDK fornisce ambiti che è possibile avviare: InvokeAgentScope, ExecuteToolScope, InferenceScopee OutputScope.

Invocazione dell'agente

Usa questo ambito all'inizio del processo dell'agente. Utilizzando l'ambito dell'agente invoke, puoi catturare proprietà come l'agente attualmente invocato, i dati utente dell'agente e altro ancora.

Python

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

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

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

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

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

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

JavaScript

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

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

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

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

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

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

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

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

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

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

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

        var scopeDetails = new InvokeAgentScopeDetails(
            endpoint: new Uri("https://myagent.contoso.com")
        );

        var request = new Request(
            content: userInput,
            sessionId: "session-abc",
            channel: new Channel("msteams"),
            conversationId: "conv-xyz"
        );

        var callerDetails = new CallerDetails(
            userDetails: new UserDetails(
                userId: "user-123",
                userEmail: "jane.doe@contoso.com",
                userName: "Jane Doe"
            )
        );

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            request: request,
            scopeDetails: scopeDetails,
            agentDetails: agentDetails,
            callerDetails: callerDetails
        );

        // Record input messages
        scope.RecordInputMessages(new[] { userInput });

        // ... your agent logic here ...

        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        return new AgentResponse { Content = output };
    }
}

public class AgentResponse
{
    public string Content { get; set; }
}

Esecuzione dello strumento

I seguenti esempi mostrano come aggiungere il tracciamento dell'osservabilità all'esecuzione dello strumento del tuo agente. Questo tracciamento cattura la telemetria a scopo di monitoraggio e audit.

Python

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

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

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

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

JavaScript

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

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

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

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

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

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

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

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

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

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

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

// ... your tool logic here ...

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

Inferenza

Gli esempi seguenti illustrano come instrumentare le chiamate di inferenza del modello di intelligenza artificiale con il rilevamento dell'osservabilità per acquisire l'utilizzo dei token, i dettagli del modello e i metadati della risposta.

Python

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

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

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

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

JavaScript

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

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

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

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

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

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

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

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

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

.NET

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

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

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

// ... your inference logic here ...

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

Risultato

Usare questo ambito per scenari asincroni in cui InvokeAgentScope, ExecuteToolScopeo InferenceScope non è in grado di acquisire i dati di output in modo sincrono. Avviare OutputScope come intervallo figlio per registrare i messaggi di output finali al termine dell'ambito padre.

Python

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

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

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

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

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

JavaScript

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

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

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

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

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

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

.NET

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

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

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

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

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

Valida localmente

Per verificare che sia stata completata l'integrazione con l'SDK di osservabilità, esaminare i log della console generati dall'agente e dai log dell'SDK di osservabilità.

Python

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.

JavaScript

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

.NET

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.

Nota

Se non si registra un ILoggerFactory in DI, l'esportatore esegue automaticamente il fallback a un logger di console.

Visualizzazione dei log esportati

Per visualizzare i dati di telemetria dell'agente in Microsoft Purview o Microsoft Defender, assicurarsi che siano soddisfatti i requisiti seguenti:

• Microsoft Purview: il controllo deve essere attivato per l'organizzazione. Per istruzioni, vedere Attivare o disattivare il controllo.
• Microsoft Defender: la ricerca avanzata deve essere configurata per accedere alla tabella CloudAppEvents. Per informazioni dettagliate, vedere la tabella CloudAppEvents nello schema di ricerca avanzata.

Valida per la pubblicazione su piattaforma

Prima della pubblicazione, utilizzare i log della console per convalidare l'integrazione dell'osservabilità per l'agente implementando gli scope necessari invoke agent, execute tool, inference e output. Poi confronta i log del tuo agente con le seguenti liste di attributi per verificare che tutti gli attributi richiesti siano presenti. Acquisisce attributi su ogni ambito o tramite il generatore di baggage e includi attributi opzionali a tua discrezione.

Per maggiori informazioni sui requisiti di pubblicazione dei negozi, consulta le linee guida per la validazione dei negozi.

attributi InvokeAgentScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia un InvokeAgentScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "microsoft.a365.caller.agent.blueprint.id": "Optional",
        "microsoft.a365.caller.agent.id": "Optional",
        "microsoft.a365.caller.agent.name": "Optional",
        "microsoft.a365.caller.agent.platform.id": "Optional",
        "microsoft.a365.caller.agent.user.email": "Optional",
        "microsoft.a365.caller.agent.user.id": "Optional",
        "microsoft.a365.caller.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "server.address": "Required",
        "server.port": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

attributi ExecuteToolScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia un ExecuteToolScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.tool.call.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.call.result": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

attributi InferenceScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia un InferenceScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.a365.agent.thought.process": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "gen_ai.provider.name": "Required",
        "gen_ai.request.model": "Required",
        "gen_ai.response.finish_reasons": "Optional",
        "gen_ai.usage.input_tokens": "Optional",
        "gen_ai.usage.output_tokens": "Optional",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.tenant.id": "Required"
    }

attributi OutputScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia un OutputScope. Usare questo contesto per scenari asincroni in cui il contesto padre non può acquisire i dati di output in modo sincrono.

"attributes": {
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

Testare l'agente utilizzando funzioni di monitoraggio e analisi

Dopo aver implementato l'osservabilità nell'agente, testarla per assicurarsi che acquisisca correttamente i dati di telemetria. Segui la guida ai test per impostare il tuo ambiente. Concentrarsi quindi principalmente sulla sezione Visualizza log di osservabilità per verificare che l'implementazione dell'osservabilità funzioni come previsto.

Verifica:

• Passa a: https://admin.cloud.microsoft/#/agents/all
• Seleziona il tuo agente > Attività
• Vedi le sessioni e le chiamate agli strumenti

Risoluzione dei problemi

Questa sezione descrive i problemi comuni durante l'implementazione e l'utilizzo dell'osservabilità.

Suggerimento

La Guida alla risoluzione dei problemi dell'Agente 365 contiene raccomandazioni di alto livello, best practice e link a contenuti di risoluzione dei problemi per ogni fase del ciclo di sviluppo dell'Agente 365.

I dati di osservabilità non compaiono

Sintomi:

• L'agente è in corsa
• Niente telemetria nel centro amministrativo
• Non si vede l'attività degli agenti

Causa radice:

• L'osservabilità non è abilitata
• Errori di configurazione
• Problemi di risoluzione dei token

Soluzioni: Prova i seguenti passaggi per risolvere il problema:

• Controllare che l'esportatore di osservabilità sia abilitato

  È necessario abilitare in modo esplicito l'utilità di esportazione di Agent 365. Se disabilitato, l'SDK passa a un'utilità di esportazione su console e i dati di telemetria non vengono inviati al servizio. Per informazioni dettagliate sulla configurazione, vedere Configurazione.

• Controlla la configurazione del token resolver

  L'utilità di esportazione richiede un resolver di token valido che restituisce un token Bearer per ogni richiesta di esportazione. Se il resolver del token è mancante o restituisce null, l'esportazione viene ignorata automaticamente. Assicurati che il tuo codice implementi correttamente il risolver dei token. Per informazioni dettagliate, vedere Sistema di risoluzione dei token.

• Controlla la presenza di errori nei log

  Abilitare la registrazione dettagliata e usare il az webapp log tail comando per cercare nei log gli errori correlati all'osservabilità. Per informazioni dettagliate su come abilitare la registrazione per ogni piattaforma, vedere Convalidare localmente.

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

• Verifica l'esportazione della telemetria

  Conferma che la telemetria è generata ed esportata come previsto.

  • Aggiungere un esportatore della console e verificare se la telemetria viene generata localmente. Per informazioni dettagliate su come usare l'utilità di esportazione della console e convalidare l'output, vedere Convalidare localmente.

ID tenant o ID agente mancanti: intervalli ignorati

Sintomi: Il sistema elimina silenziosamente i segmenti e non li esporta mai. Alcuni SDK registrano un conteggio degli intervalli ignorati o un messaggio, ad esempio "Nessun intervallo con l'identità tenant/agente trovata". Altri li rilasciano senza registrazione.

Risoluzione:

• Prima dell'esportazione, le partizioni SDK si estendono in base all'identità del tenant e dell'agente. Il sistema elimina gli intervalli che mancano di un ID tenant o di un ID agente e non li invia mai al servizio.
• Assicurarsi che BaggageBuilder sia configurato con l'ID tenant e l'ID agente prima di creare intervalli. Questi valori vengono propagati attraverso il contesto OpenTelemetry e si collegano a tutti gli intervalli creati nell'ambito del bagaglio. Per l'API specifica della piattaforma, vedere Attributi del bagaglio.
• Verificare che l'attività TurnContext abbia un destinatario valido con identità agente se si utilizza il baggage middleware o il turn context helper dal pacchetto di integrazione dell'hosting per popolare gli ID.

Errore di risoluzione del token: esportazione ignorata o non autorizzata

Sintomi: Il resolver del token restituisce null o genera un errore. A seconda dell'SDK, l'esportazione viene ignorata completamente o la richiesta viene inviata senza un'intestazione di autorizzazione e ha esito negativo con HTTP 401.

Risoluzione:

• Il sistema di risoluzione dei token è necessario all'inizializzazione. Se manca, l'esportatore genera un errore all'avvio. Verificare che venga fornito un risolutore di token e che restituisca un token Bearer valido.
• Assicurarsi che l'ID tenant e l'ID agente corretti vengano usati per BaggageBuilder, perché questi valori vengono passati al resolver del token.
• Per gli agenti Azure ospitati, verificare che l'identità gestita disponga dell'autorizzazione API necessaria per l'ambito di osservabilità.

HTTP 401 Non autorizzato

Sintomi: L'esportazione non riesce con HTTP 401. L'esportatore non ritenta di risolvere questo errore.

Risoluzione:

• Verificare che il gruppo di destinatari del token corrisponda all'ambito dell'endpoint di osservabilità. L'ambito predefinito è https://api.powerplatform.com/.default per un agente agentico.
• Verificare che l'identità (identità gestita o registrazione dell'app) disponga delle autorizzazioni di osservabilità di Agent 365.
• Verificare che il resolver del token non restituisca un token utente delegato, un token per un gruppo di destinatari non corretto o un token scaduto.

Importante

Gli agenti esistenti che si aggiornano a queste versioni del pacchetto richiedono un passaggio aggiuntivo

Questo passaggio si applica solo se si sta aggiornando un agente esistente. Le nuove installazioni di agenti non richiedono questo passaggio. Se si esegue l'aggiornamento alle versioni del pacchetto seguenti o versioni successive, è necessario concedere la nuova Agent365.Observability.OtelWrite autorizzazione all'identità (identità gestita o registrazione dell'app). Senza questa autorizzazione, l'esportazione dei dati di telemetria non riesce con HTTP 401.

Piattaforma	Versione minima che richiede questo passaggio
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Per i passaggi necessari, vedere il registro delle modifiche nel pacchetto in fase di aggiornamento.

HTTP 403 Non consentito

Sintomi: L'esportazione non riesce con HTTP 403. L'utilità di esportazione non riprova in caso di questo errore.

Risoluzione:

• Verificare se l'ID Tenant viene aggiunto all'elenco dei tenant consentiti di Agent 365 per l'inserimento di tracce.
• Verificare che l'identità dell'agente abbia il ruolo o l'autorizzazione necessari per il tenant di destinazione.

HTTP 429/ 5xx - Errori temporanei

Sintomi: L'esportazione non riesce con un codice di stato HTTP temporaneo, ad esempio 429 o 5xx.

Risoluzione:

• Questi errori sono in genere temporanei e risolti autonomamente. Gli SDK Python e JavaScript riprovano automaticamente per i codici di stato HTTP 408, 429 e 5xx fino a tre volte con backoff esponenziale. L'SDK di .NET non riprova automaticamente.
• Se gli errori continuano a verificarsi, controlla il dashboard dello stato del servizio.
• Valutare la possibilità di ridurre la frequenza di esportazione aumentando il ritardo pianificato tra batch o aumentando le dimensioni massime del batch di esportazione. Per le opzioni di configurazione per piattaforma, vedere la Agent365ExporterOptions tabella in Configurazione.

Il timeout di esportazione

Sintomi: Timeout dei tentativi di esportazione.

Risoluzione:

• Controllare la connettività di rete all'endpoint di osservabilità.
• Le impostazioni predefinite di timeout variano in base alla piattaforma. Il timeout predefinito della richiesta HTTP è di 30 secondi. Alcuni SDK hanno anche un timeout di esportazione complessivo separato che copre tutto il ciclo di esportazione, inclusi i tentativi di ripetizione. Per le proprietà esatte e le impostazioni predefinite per ogni piattaforma, vedere la Agent365ExporterOptions tabella in Configurazione.
• Se i timeout si verificano frequentemente, aumentare il valore di timeout pertinente nelle opzioni di esportazione.

L'esportazione ha esito positivo, ma i dati di telemetria non vengono visualizzati in Defender o Purview

Symptoms: I log mostrano un'esportazione riuscita, ma i dati di telemetria non sono visibili in Microsoft Defender o Microsoft Purview.

Risoluzione:

• Verificare di soddisfare i prerequisiti per la visualizzazione dei log esportati. Per Purview, il controllo deve essere attivato. Per Defender, è necessario configurare la ricerca avanzata. Per altre informazioni, vedere Visualizzazione dei log esportati.
• La compilazione dei dati di telemetria può richiedere alcuni minuti dopo un'esportazione riuscita. Attendere che i dati vengano visualizzati prima di analizzare ulteriormente.

Per altre informazioni sul test dell'osservabilità, vedere:

• Guida al test - Visualizza i log di osservabilità
• Configurazione dell'osservabilità