Observabilidad del agente

Importante

Para obtener acceso anticipado a Microsoft Agent 365, debe formar parte del programa de versión preliminar Frontier. Frontier le conecta directamente con las últimas innovaciones de inteligencia artificial de Microsoft. Las versiones preliminares de Frontier están sujetas a los términos de vista previa existentes en tus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

Para participar en el ecosistema de Agent 365, añade capacidades de observabilidad de Agent 365 a tu agente. Agent 365 Observability se basa en OpenTelemetry (OTel) y proporciona un marco unificado para capturar telemetría de forma coherente y segura en todas las plataformas de agentes. Al implementar este componente necesario, permite a los administradores de TI supervisar la actividad del agente en Microsoft centro de administración y permitir que los equipos de seguridad usen Defender y Purview para la detección de amenazas y cumplimiento.

Beneficios clave

Visibilidad de extremo a extremo: Captura una telemetría completa para cada invocación de agente, incluyendo sesiones, llamadas a herramientas y excepciones, dándote trazabilidad total entre plataformas.
Seguridad y habilitación de cumplimiento: envíe registros de auditoría unificados a Defender y Purview, lo que permite escenarios de seguridad avanzados e informes de cumplimiento para el agente.
Flexibilidad multiplataforma: Construir sobre los estándares de OTel y admitir diversos entornos de ejecución y plataformas como Copilot Studio, Foundry y futuros marcos de agentes.
Operational efficiency for admins: Proporcionar observabilidad centralizada en Microsoft 365 admin center, reduciendo el tiempo de solución de problemas y mejorando la gobernanza con controles de acceso basados en rol para los equipos de TI que administran el agente.

Agentes compatibles

Los siguientes tipos de agente admiten la observabilidad del Agente 365:

Agentes habilitados para Microsoft Agent 365: use el SDK de observabilidad para instrumentar el agente.
Agentes de motor personalizados: use el SDK de observabilidad para instrumentar el agente.
Agentes declarativos: la observabilidad se admite de forma predeterminada. No se requiere ninguna implementación del SDK.

Instalación

Use estos comandos para instalar los módulos de observabilidad para los idiomas admitidos por Agent 365.

Instale los paquetes principales de observabilidad y tiempo de ejecución. Todos los agentes que usan la observabilidad del Agente 365 necesitan estos paquetes.

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

Si el agente usa el paquete Microsoft Agents Hosting, instale el paquete de integración de hospedaje. Proporciona un middleware que rellena automáticamente el equipaje y los ámbitos desde el TurnContext e incluye el almacenamiento en caché de tokens para el exportador de observabilidad.

pip install microsoft-agents-a365-observability-hosting

Si el agente usa uno de los marcos de inteligencia artificial admitidos, instale la extensión de instrumentación automática correspondiente para capturar automáticamente la telemetría sin código de instrumentación manual. Para obtener más información sobre la configuración, consulte Instrumentación automática.

# 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

Instale los paquetes principales de observabilidad y tiempo de ejecución. Todos los agentes que usan la observabilidad del Agente 365 necesitan estos paquetes.

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

Si el agente usa el paquete de hospedaje de @microsoft/agents , instale el paquete de integración de hospedaje. Proporciona un middleware que rellena automáticamente el equipaje y los ámbitos desde el TurnContext e incluye el almacenamiento en caché de tokens para el exportador de observabilidad.

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

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

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

Instale el paquete principal de observabilidad y tiempo de ejecución. Todos los agentes que usan la observabilidad del Agente 365 necesitan este paquete.

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

Si el agente usa el Microsoft. Agents.A365.Observability.Hosting Paquete NuGet, instale el paquete de integración de hospedaje. Proporciona un middleware que rellena automáticamente el equipaje desde el TurnContext e incluye el almacenamiento en caché de tokens para el exportador de observabilidad.

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

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

Configuración

Utiliza las siguientes configuraciones para habilitar y personalizar la observabilidad del Agente 365 para tu agente.

Establece la ENABLE_A365_OBSERVABILITY_EXPORTER variable de entorno en true para observabilidad. Esta configuración exporta los registros al servicio y requiere que se proporcione un token_resolver. En caso contrario, se utiliza el exportador de consola.

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

El resolutor de tokens está excluido del registro en la consola.

Puede personalizar el comportamiento del exportador pasando una Agent365ExporterOptions instancia a exporter_options. Cuando exporter_options se proporciona, tiene prioridad sobre los token_resolver parámetros y 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,
)

En la tabla siguiente se describen los parámetros opcionales para configure().

Parámetro	Descripción	Predeterminado
`logger_name`	Nombre del registrador de Python usado para la depuración y la salida del registro de consola.	`microsoft_agents_a365.observability.core`
`exporter_options`	Una instancia `Agent365ExporterOptions` que configura conjuntamente el resolutor de tokens y la categoría de clúster.	`None`
`suppress_invoke_agent_input`	Cuando `True`, suprime los mensajes de entrada en los segmentos de `InvokeAgent`.	`False`

En la tabla siguiente se describen las propiedades opcionales de Agent365ExporterOptions.

Propiedad	Descripción	Predeterminado
`use_s2s_endpoint`	Cuando `True` usa la ruta de acceso del punto de conexión de servicio a servicio.	`False`
`max_queue_size`	Tamaño máximo de cola para el procesador por lotes.	`2048`
`scheduled_delay_ms`	Retraso en milisegundos entre lotes de exportación.	`5000`
`exporter_timeout_ms`	Tiempo de espera en milisegundos para la operación de exportación.	`30000`
`max_export_batch_size`	Tamaño máximo del lote para las operaciones de exportación.	`512`

Establece la ENABLE_A365_OBSERVABILITY_EXPORTER variable de entorno en true para observabilidad. Esta configuración exporta los registros al servicio y requiere que se proporcione un solucionador de tokens. En caso contrario, se utiliza el exportador de consola.

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

Como alternativa a las variables de entorno, puede configurar la observabilidad programáticamente usando un proveedor de configuración a través del método withConfigurationProvider. Si también usa métodos de generador individuales (como withExporterOptions o withClusterCategory), los métodos de generador individuales tienen prioridad sobre los valores del proveedor de configuración.

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

Puede personalizar el comportamiento del exportador pasando una Agent365ExporterOptions instancia a withExporterOptions. Esta opción permite controlar el procesamiento por lotes, los tiempos de espera y el modo de ruta.

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

En la tabla siguiente se describen las propiedades opcionales de Agent365ExporterOptions.

Propiedad	Descripción	Predeterminado
`useS2SEndpoint`	Cuando `true` usa la ruta de acceso del punto de conexión de servicio a servicio.	`false`
`maxQueueSize`	Tamaño máximo de cola para el procesador por lotes.	`2048`
`scheduledDelayMilliseconds`	Retraso en milisegundos entre lotes de exportación.	`5000`
`exporterTimeoutMilliseconds`	Tiempo de espera en milisegundos para toda la operación de exportación.	`90000`
`httpRequestTimeoutMilliseconds`	Tiempo de espera en milisegundos para cada solicitud HTTP individual al back-end.	`30000`
`maxExportBatchSize`	Tamaño máximo del lote para las operaciones de exportación.	`512`

También puedes proporcionar un registrador personalizado que implemente la ILogger interfaz (info, warn, error, event). Pásalo al constructor 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();

Establezca EnableAgent365Exporter en trueappsettings.json.

En Program.cs, agregue Agent365ExporterOptions a la colección de servicios. Este cambio configura el delegado que usa el exportador de seguimiento para recuperar el token.

Añadir dependencias relacionadas con la observabilidad 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();

Puede personalizar el comportamiento del exportador pasando un delegado de configuración y un tipo de exportador a AddA365Tracing().

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

En la tabla siguiente se describen las propiedades opcionales de Agent365ExporterOptions.

Propiedad	Descripción	Predeterminado
`UseS2SEndpoint`	Cuando `true` usa la ruta de acceso del punto de conexión de servicio a servicio.	`false`
`MaxQueueSize`	Tamaño máximo de cola para el procesador por lotes.	`2048`
`ScheduledDelayMilliseconds`	Retraso en milisegundos entre lotes de exportación.	`5000`
`ExporterTimeoutMilliseconds`	Tiempo de espera en milisegundos para la operación de exportación.	`30000`
`MaxExportBatchSize`	Tamaño máximo del lote para las operaciones de exportación.	`512`

Atributos de equipaje

Use BaggageBuilder para establecer información contextual que fluye a través de todos los intervalos de una solicitud. El SDK implementa una SpanProcessor que copia de todas las entradas de equipaje no vacías en intervalos recién iniciados sin sobrescribir los atributos existentes.

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

Para rellenar automáticamente el BaggageBuilder desde el TurnContext, use la herramienta populate del paquete microsoft-agents-a365-observability-hosting. Este asistente extrae automáticamente los detalles del autor de la llamada, el agente, el inquilino, el canal y la conversación de la actividad.

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

Para rellenar automáticamente el BaggageBuilder desde el TurnContext, use la herramienta fromTurnContext del paquete @microsoft/agents-a365-observability-hosting. Este asistente extrae automáticamente los detalles del autor de la llamada, el agente, el inquilino, el canal y la conversación de la actividad.

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.

Para rellenar automáticamente el BaggageBuilder desde el ITurnContext, use el método de extensión FromTurnContext en el paquete de Microsoft.Agents.A365.Observability.Hosting. Este método extrae automáticamente los detalles del autor de la llamada, el agente, el inquilino, el canal y la conversación de la actividad.

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

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

Middleware para gestión de equipaje

Si el agente usa el paquete de integración de hospedaje, registre el middleware de equipaje para rellenar automáticamente el equipaje para cada solicitud entrante. Este paso quita la necesidad de llamar BaggageBuilder manualmente en cada controlador de actividad.

Regístrese BaggageMiddleware en el conjunto de middleware del adaptador. Extrae automáticamente los detalles de llamada, agente, arrendatario, canal y conversación de cada entrada TurnContext y ajusta la solicitud en un contexto de equipaje.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Como alternativa, use ObservabilityHostingManager para configurar middleware de contexto junto con otras características de alojamiento:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

El middleware omite la configuración de la información de contexto para las respuestas asincrónicas (eventos ContinueConversation) para evitar sobrescribir la información de contexto que la solicitud de origen ya ha establecido.

Regístrese BaggageMiddleware en el adaptador. Extrae automáticamente los detalles de llamada, agente, arrendatario, canal y conversación de cada entrada TurnContext y ajusta la solicitud en un contexto de equipaje.

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

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

Como alternativa, use ObservabilityHostingManager para configurar middleware de contexto junto con otras características de alojamiento:

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

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

Regístrese BaggageTurnMiddleware en el adaptador. Extrae automáticamente los detalles de llamada, agente, arrendatario, canal y conversación de cada entrada ITurnContext y ajusta la solicitud en un contexto de equipaje.

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

adapter.Use(new BaggageTurnMiddleware());

Si necesita información de contexto a nivel HTTP (por ejemplo, para establecer los identificadores de entidad y agente antes de que se ejecute la canalización de Bot Framework), registre ObservabilityBaggageMiddleware en la canalización de ASP.NET Core mediante el método de extensión UseObservabilityRequestContext. Debe proporcionar una función de resolución que extraiga el identificador de inquilino y el identificador del agente del contexto 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);
});

Resolución de token

Al usar el exportador del Agente 365, debe proporcionar una función de resolución de tokens que devuelva un token de autenticación. Cuando usa el SDK de observabilidad de Agent 365 con el marco de hospedaje del agente, puede generar tokens mediante TurnContext de las actividades del agente.

En el fragmento de código siguiente se muestra cómo se puede generar un token mediante el microsoft_agents.hosting.core SDK. El token de autenticación generado aquí se usa para exportar los intervalos al servicio de ingesta de A365. Los agentes pueden generar un token por sí mismos, por ejemplo, mediante la Biblioteca de autenticación de Microsoft (MSAL), pero deben asegurarse de que el token tiene el ámbito de observabilidad.

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

Para un agente creado con la CLI de A365 que usa un compañero de equipo de IA y el paquete Microsoft Agent 365 Observability Hosting Library, use AgenticTokenCache para gestionar el almacenamiento en caché de tokens automáticamente. Registre el token una vez por agente y arrendatario durante un controlador de actividad y pase cache.get_observability_token como token_resolver en su configuración de observabilidad.

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

En el fragmento de código siguiente se muestra cómo se puede generar un token mediante el @microsoft/agents-hosting SDK. El token de autenticación generado aquí se usa para exportar los intervalos al servicio de ingesta de A365. Los agentes pueden generar un token por sí mismos, por ejemplo, mediante la Biblioteca de autenticación de Microsoft (MSAL), pero deben asegurarse de que el token tiene el ámbito de observabilidad.

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

Para un agente construido con la CLI de A365 que usa un colega de IA y el paquete @microsoft/agents-a365-observability-hosting, use AgenticTokenCacheInstance para gestionar el almacenamiento en caché de tokens automáticamente. Llame a RefreshObservabilityToken una vez por cada agente y tenant durante un manejador de actividades y pase AgenticTokenCacheInstance.getObservabilityToken como tokenResolver en su configuración de observabilidad.

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

En el fragmento de código siguiente se muestra cómo generar un token mediante el SDK de Microsoft.Agents hospedaje. El token de autenticación que genera se usa para exportar los intervalos al servicio de ingesta de A365. Los agentes pueden generar un token por sí mismos, por ejemplo, mediante la Biblioteca de autenticación de Microsoft (MSAL), pero deben asegurarse de que el token tiene el ámbito de observabilidad.

Proporcione un solucionador de tokens al registrar Agent365ExporterOptions con un TokenResolver delegado. El delegado recibe agentId y tenantId y devuelve un token de autenticación.

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

Para un agente compilado con la CLI de A365 que usa un compañero de equipo de IA, y el paquete NuGet Microsoft.Agents.A365.Observability.Hosting, use el método AddAgenticTracingExporter() para controlar el almacenamiento de caché de tokens de forma automática a través de la inserción de dependencias.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

En la aplicación del agente, registre el 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}");
        }
    }
}

Instrumentación automática

La instrumentación automática escucha automáticamente las señales de telemetría existentes de marcos de agente (SDK) para seguimientos y las reenvía al servicio de observabilidad de Agent 365. Esta función elimina la necesidad de que los desarrolladores escriban código de monitorización manualmente, simplifica la configuración y garantiza un seguimiento consistente del rendimiento.

Múltiples SDKs y plataformas soportan auto-instrumentación:

Plataforma	SDK y frameworks admitidos
.NET	Kernel semántico, OpenAI, Agent Framework
Python	Kernel semántico, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Nota

La compatibilidad con la instrumentación automática varía según la plataforma y la implementación del SDK.

Núcleo Semántico

La instrumentación automática requiere el uso del generador de equipaje. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Instale el paquete .

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

Configure la observabilidad.

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

Agregue dependencias a la colección de servicios.

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

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

Establece AgentId y TenantId usando BaggageBuilder. Asegúrate de que el ID que usas al crear un ChatCompletionAgent coincida con el ID de agente que pasas 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 instrumentación automática requiere el uso del generador de equipaje. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Instale el paquete .

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

Configure la observabilidad.

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

Instale el paquete .

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

Configure la observabilidad.

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

Agregue dependencias a la colección de servicios.

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

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

Establece AgentId y TenantId usando BaggageBuilder. Para llamadas a herramientas, inicia una traza usando Trace() en una instancia 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>);
    }
}

Marco de trabajo del agente

La instrumentación automática requiere el uso del generador de equipaje. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Instale el paquete .

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

Configure la observabilidad.

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

Agregue dependencias a la colección de servicios.

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

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

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

Marco de LangChain

La instrumentación automática requiere el uso del constructor de contenedores. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Instale el paquete .

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

Configure la observabilidad.

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

Instale el paquete .

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

Configure la observabilidad.

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

Instrumentación manual

Utiliza el SDK de observabilidad del Agente 365 para entender el funcionamiento interno del agente. El SDK proporciona ámbitos que puede iniciar: InvokeAgentScope, ExecuteToolScope, InferenceScope, y OutputScope.

Invocación del agente

Use este ámbito al principio del proceso del agente. Al usar el ámbito del agente de invocación, se pueden capturar propiedades como el agente actual que se invoca, los datos de usuario del agente, etc.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Si el agente usa el paquete @microsoft/agents-a365-observability-hosting, puede usar ScopeUtils.populateInvokeAgentScopeFromTurnContext para crear el alcance con los detalles del agente, los detalles del quién llama y la información del canal derivada automáticamente del 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; }
}

Ejecución de herramientas

Los siguientes ejemplos muestran cómo agregar el seguimiento de la observabilidad a la ejecución de herramientas de su agente. Este seguimiento captura la telemetría para fines de monitorización y auditoría.

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

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

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

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

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

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

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

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

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

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

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

Si el agente utiliza el paquete @microsoft/agents-a365-observability-hosting, utilice ScopeUtils.populateExecuteToolScopeFromTurnContext para crear el ámbito con los detalles del agente derivados automáticamente del 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.\"}");

Inferencia

En los ejemplos siguientes se muestra cómo instrumentar llamadas de inferencia del modelo de IA con seguimiento de observabilidad para capturar el uso de tokens, los detalles del modelo y los metadatos de respuesta.

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

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

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

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

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

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

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

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

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

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

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

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

Si el agente usa el paquete @microsoft/agents-a365-observability-hosting, puede usar ScopeUtils.populateInferenceScopeFromTurnContext para crear el ámbito con los detalles del agente que se derivan automáticamente de TurnContext.

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

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

const scope = ScopeUtils.populateInferenceScopeFromTurnContext(
  inferenceDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
  });
} finally {
  scope.dispose();
}

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

Salida

Utilice este ámbito para escenarios asincrónicos donde InvokeAgentScope, ExecuteToolScope o InferenceScope no puedan capturar datos de salida de forma sincrónica. Comience OutputScope como un intervalo secundario para registrar los mensajes de salida finales después de que finalice el ámbito primario.

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

Validar localmente

Para comprobar que se ha integrado correctamente con el SDK de observabilidad, examine los registros de consola generados por el agente y los registros del SDK de observabilidad.

Establezca la variable de entorno ENABLE_A365_OBSERVABILITY_EXPORTER en false. Esta configuración exporta los tramos (trazas) a la consola.

Para investigar los errores de exportación, habilite el registro detallado estableciendo ENABLE_A365_OBSERVABILITY_EXPORTERtrue en y configurando el registro de depuración en el inicio de la aplicación:

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)

Mensajes de registro clave

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.

Establezca la variable de entorno ENABLE_A365_OBSERVABILITY_EXPORTER en false. Esta configuración exporta los tramos (trazas) a la consola.

Para investigar errores de exportación, establezca variables de entorno en .env o shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Verifique la salida de la consola para mensajes tales como:

[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

Opcionalmente, use un registrador personalizado para capturar eventos de exportación a un archivo:

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

Establezca EnableAgent365Exporter en falseappsettings.json. Esta configuración exporta los tramos (trazas) a la consola.

Para investigar los errores de exportación, configure el registro detallado en appsettings.json:

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

O bien, establezca variables de entorno:

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

Mensajes de registro clave

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

Si no registra un ILoggerFactory en DI, el exportador vuelve automáticamente a un console logger.

Visualización de registros exportados

Para ver la telemetría del agente en Microsoft Purview o Microsoft Defender, asegúrese de que se cumplen los siguientes requisitos:

Microsoft Purview: la auditoría debe estar activada para su organización. Para obtener instrucciones, consulte Activar o desactivar la auditoría.
Microsoft Defender: La búsqueda avanzada debe configurarse para acceder a la tabla CloudAppEvents. Para obtener más información, consulte la tabla CloudAppEvents en el esquema de búsqueda avanzada.

Validar para la publicación en la tienda

Importante

Para una validación exitosa del almacén, el agente debe implementar las InvokeAgentScope, InferenceScope, y ExecuteToolScope ámbitos. Estos tres ámbitos son necesarios para la publicación.

Antes de publicar, use los registros de consola para validar la integración de observabilidad para el agente mediante la implementación de los ámbitos necesarios invoke agent, execute tool, inference, y output. Luego compara los registros de tu agente con las siguientes listas de atributos para verificar que todos los atributos requeridos estén presentes. Defina los atributos en cada ámbito o mediante el generador de equipaje, e incluya atributos opcionales según considere oportuno.

Para más información sobre los requisitos de publicación en tiendas, consulte las directrices de validación de tiendas.

atributos de `InvokeAgentScope`

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar 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"
    }

atributos de `ExecuteToolScope`

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar 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"
    }

atributos de `InferenceScope`

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar 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"
    }

atributos de `OutputScope`

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar un OutputScope. Use este ámbito para escenarios asincrónicos en los que el ámbito primario no puede capturar datos de salida de forma sincrónica.

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

Prueba del agente con observabilidad

Después de implementar la observabilidad en el agente, pruóbelo para asegurarse de que captura la telemetría correctamente. Sigue la guía de pruebas para configurar tu entorno. A continuación, céntrese principalmente en la sección Ver registros de observabilidad para validar que la implementación de observabilidad funciona según lo previsto.

Comprobación:

Vaya a: https://admin.cloud.microsoft/#/agents/all
Selecciona tu agente > Actividad
Verá las sesiones y las llamadas a herramientas

Solución de problemas

Esta sección describe problemas comunes al implementar y utilizar la observabilidad.

Sugerencia

La Guía de Resolución de Problemas del Agente 365 contiene recomendaciones de alto nivel para la solución de problemas, mejores prácticas y enlaces a contenido de solución de problemas para cada parte del ciclo de vida del desarrollo del Agente 365.

Los datos de observabilidad no aparecen

Síntomas:

El agente está huyendo
No hay telemetría en el centro de administración
No se puede ver la actividad de los agentes

Causa principal:

La observabilidad no está habilitada
Errores de configuración
Problemas con el resolutor de tokens

Soluciones: Prueba los siguientes pasos para resolver el problema:

Comprobación de que el exportador de observabilidad está habilitado

Debe habilitar explícitamente el exportador del Agente 365. Cuando está deshabilitado, el SDK vuelve a un exportador de consola y la telemetría no se envía al servicio. Para obtener más información sobre la configuración, consulte Configuración.
Comprobar la configuración del resolutor de tokens

El exportador requiere un solucionador de tokens válido que devuelva un token de portador para cada solicitud de exportación. Si falta el solucionador de tokens o devuelve null, la exportación se omite silenciosamente. Asegúrate de que tu código implemente correctamente el resolvedor de tokens. Para más información, consulte Resolución de tokens.
Comprobar errores en los registros

Habilite el registro detallado y use el az webapp log tail comando para buscar registros de errores relacionados con la observabilidad. Para más información sobre cómo habilitar el registro por plataforma, consulte Validar localmente.
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
Verificar exportación de telemetría

Confirma que la telemetría se ha generado y exportado como se espera.
- Agregue un exportador de consola y compruebe si la telemetría se genera localmente. Para más información sobre cómo usar el exportador de la consola y validar la salida, consulte Validar localmente.

Falta el identificador de inquilino o el identificador del agente: intervalos omitidos

Síntomas: El sistema quita silenciosamente los intervalos y nunca los exporta. Algunos SDK registran un recuento de fragmentos omitidos o un mensaje como "No se encontraron fragmentos con identidad de inquilino/agente". Otros los descartan sin registrarlos.

Resolución:

Antes de la exportación, el SDK divide los segmentos por las identidades de los inquilinos y de los agentes. El sistema quita intervalos que carecen de un identificador de inquilino o de agente y nunca los envía al servicio.
Asegúrese BaggageBuilder de que está configurado con el identificador de inquilino y el identificador del agente antes de crear intervalos. Estos valores se propagan a través del contexto de OpenTelemetry y se adjuntan a todos los intervalos creados dentro del ámbito del equipaje. Para obtener la API específica de la plataforma, consulte Atributos de equipaje.
Confirme que la TurnContext actividad tiene un destinatario válido con la identidad del agente si usa el middleware de equipaje o activa el asistente de contexto del paquete de integración de hospedaje para rellenar esos identificadores.

Error de resolución de tokens: exportación omitida o no autorizada

Síntomas: El solucionador de tokens devuelve null o produce un error. En función del SDK, la exportación se omite por completo o la solicitud se envía sin un encabezado de autorización y se produce un error con HTTP 401.

Resolución:

El resolutor de tokens es necesario en la inicialización. Si falta, el exportador genera un error al iniciarse. Asegúrese de que se proporciona un solucionador de tokens y devuelva un token Bearer válido.
Asegúrese de que se usan el identificador de inquilino y el identificador de agente correctos para BaggageBuilder, ya que estos valores se pasan al solucionador de tokens.
Para los agentes hospedados Azure, compruebe que la identidad administrada tiene el permiso de API necesario para el ámbito de observabilidad.

HTTP 401 No autorizado

Síntomas: Se produce un error en la exportación con HTTP 401. El exportador no vuelve a intentar este error.

Resolución:

Compruebe que la audiencia del token coincide con el alcance del endpoint de observabilidad. El ámbito predeterminado es https://api.powerplatform.com/.default para un agente de tipo agentic.
Asegúrese de que la identidad (identidad administrada o registro de aplicaciones) tiene permisos de observabilidad del Agente 365.
Compruebe que la resolución de tokens no devuelve un token de usuario delegado, un token para una audiencia incorrecta o un token expirado.

Importante

Los agentes existentes que actualizan a estas versiones de paquete requieren un paso adicional

Este paso solo se aplica si va a actualizar un agente existente. Las nuevas instalaciones del agente no requieren este paso. Si va a actualizar a las siguientes versiones de paquete o versiones más recientes, debe conceder el nuevo Agent365.Observability.OtelWrite permiso a la identidad (identidad administrada o registro de aplicaciones). Sin este permiso, se produce un error en la exportación de telemetría con HTTP 401.

Plataforma	Versión mínima que requiere este paso
.NET	`0.3-beta`
Node.js.	`0.2.0-preview.1`
Python	`0.3.0`

Para conocer los pasos necesarios, consulte el registro de cambios en el paquete que va a actualizar.

HTTP 403 Prohibido

Síntomas: Se produce un error en la exportación con HTTP 403. El exportador no vuelve a intentar este error.

Resolución:

Compruebe si el ID de inquilino se agrega a la lista de inquilinos permitidos del Agente 365 para la ingesta de trazas.
Confirme que la identidad del agente tiene el rol o permiso necesarios para el inquilino de destino.

HTTP 429 / 5xx: errores transitorios

Síntomas: La exportación produce un error con un código de estado HTTP transitorio, como 429 o 5xx.

Resolución:

Estos errores suelen ser transitorios y se resuelven por sí mismos. Los SDK de Python y JavaScript vuelven a intentarlo automáticamente en códigos de estado HTTP 408, 429 y 5xx hasta tres veces con retroceso exponencial. El SDK de .NET no vuelve a intentarlo automáticamente.
Si los errores persisten, compruebe el panel de estado del servicio.
Considere la posibilidad de reducir la frecuencia de exportación aumentando el retraso programado entre lotes o aumentando el tamaño máximo del lote de exportación. Para ver las opciones de configuración por plataforma, consulte la Agent365ExporterOptions tabla en Configuración.

Tiempo de espera de exportación

Síntomas: Se agota el tiempo de espera de los intentos de exportación.

Resolución:

Verifique la conectividad de la red al endpoint de observabilidad.
Los valores predeterminados de tiempo de espera varían según la plataforma. El tiempo de espera de solicitud HTTP predeterminado es de 30 segundos. Algunos SDKs también tienen un tiempo de espera general e independiente del exportador que cubre todo el proceso de exportación, incluidos los reintentos. Para ver las propiedades exactas y los valores predeterminados por plataforma, consulte la Agent365ExporterOptions tabla en Configuración.
Si se producen tiempos de espera con frecuencia, aumente el valor de tiempo de espera pertinente en las opciones del exportador.

La exportación se realiza correctamente, pero la telemetría no aparece en Defender o Purview

Symptoms: Los registros muestran una exportación correcta, pero la telemetría no está visible en Microsoft Defender o Microsoft Purview.

Resolución:

Compruebe que cumple los requisitos previos para ver los registros exportados. Para Purview, la auditoría debe estar activada. Para Defender, debe configurar la búsqueda avanzada. Para obtener más información, consulte Visualización de registros exportados.
La telemetría puede tardar varios minutos en actualizarse después de una exportación correcta. Espere a que aparezcan los datos antes de investigar más.

Para más información sobre las pruebas de observabilidad, consulte:

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-22

Observabilidad del agente

Beneficios clave

Agentes compatibles

Instalación

Configuración

Atributos de equipaje

Middleware para gestión de equipaje

Resolución de token

Instrumentación automática

Núcleo Semántico

OpenAI

Marco de trabajo del agente

Marco de LangChain

Instrumentación manual

Invocación del agente

Ejecución de herramientas

Inferencia

Salida

Validar localmente

Visualización de registros exportados

Validar para la publicación en la tienda

atributos de InvokeAgentScope

atributos de ExecuteToolScope

atributos de InferenceScope

atributos de OutputScope

Prueba del agente con observabilidad

Solución de problemas

Los datos de observabilidad no aparecen

Falta el identificador de inquilino o el identificador del agente: intervalos omitidos

Error de resolución de tokens: exportación omitida o no autorizada

HTTP 401 No autorizado

HTTP 403 Prohibido

HTTP 429 / 5xx: errores transitorios

Tiempo de espera de exportación

La exportación se realiza correctamente, pero la telemetría no aparece en Defender o Purview

Comentarios

Recursos adicionales

atributos de `InvokeAgentScope`

atributos de `ExecuteToolScope`

atributos de `InferenceScope`

atributos de `OutputScope`