@microsoft/agents-a365-observability package

Número máximo de intervalos por lote de exportación.

Generador de equipaje por solicitud para la propagación de contexto de OpenTelemetry.

Esta clase proporciona una API fluida para establecer valores de equipaje que se propagarán en el contexto de OpenTelemetry.

Ejemplo

const scope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .build();

scope.enter();
// Baggage is set in this context
// ... do work ...
scope.exit();
// Baggage is restored after exiting the context

Administrador de contexto para el ámbito del equipaje.

Esta clase administra el ciclo de vida de los valores de equipaje y los establece al entrar y restaurar el contexto anterior al salir.

Generador para configurar el agente 365 con seguimiento de OpenTelemetry

Proporciona el ámbito de seguimiento de OpenTelemetry para las operaciones de ejecución de herramientas de IA.

Proporciona el ámbito de seguimiento de OpenTelemetry para las operaciones de inferencia de IA generativas.

Proporciona el ámbito de seguimiento de OpenTelemetry para las operaciones de invocación del agente de IA.

Configuración del paquete de observabilidad. Hereda la configuración del entorno de ejecución y agrega configuraciones específicas de observabilidad.

Punto de entrada principal para el Agente 365 que proporciona seguimiento de OpenTelemetry para agentes y herramientas de IA

Constantes de OpenTelemetry para el Agente 365

Clase base para ámbitos de seguimiento de OpenTelemetry

Proporciona el ámbito de seguimiento de OpenTelemetry para el seguimiento de mensajes de salida con la vinculación del intervalo primario.

Configuración de PerRequestSpanProcessor. Hereda la configuración del entorno de ejecución (clusterCategory, isNodeEnvDevelopment) y agrega límites de protección de procesador por solicitud.

Esto se separa de ObservabilityConfiguration porque PerRequestSpanProcessor solo se usa en escenarios específicos y esta configuración no debe exponerse en la configuración común ObservabilityConfiguration.

Detalles sobre un agente de IA

Datos binarios insertados (codificados en base64).

Opciones de configuración del Generador de observabilidad del Agente 365

Detalles del autor de la llamada para la creación del ámbito. Admite autores de llamadas humanas, llamadores de agente o ambos (A2A con un humano en la cadena).

Nota de migración: En la versión 1, el nombre CallerDetails al que se hace referencia a la identidad del autor de la llamada humana (ahora UserDetails). En la versión 2 se ha reasignado como contenedor que agrupa la información del autor de llamada de agente y humano.

Consulte UserDetails : identidad del autor de la llamada humana (anteriormente CallerDetails) Consulte la sección CHANGELOG.md: cambios importantes para obtener instrucciones sobre la migración.

Representa el canal de una invocación.

Un mensaje de entrada enviado a un modelo (convenciones semánticas de OTEL gen-ai).

Referencia a un archivo cargado previamente.

Parte extensible para tipos personalizados y futuros.

Detalles de la llamada de la herramienta servidor extensible con un discriminador de tipos.

Respuesta de llamada de herramienta de servidor extensible con un discriminador de tipos.

Interfaz de registrador personalizada para la observabilidad del Agente 365 Implementa esta interfaz para admitir los back-end de registro

Detalles de una llamada de inferencia

Detalles para registrar la respuesta desde una llamada de inferencia

Detalles para invocar el ámbito del agente.

Un mensaje de salida generado por un modelo (convenciones semánticas de OTEL gen-ai).

Representa una respuesta que contiene mensajes de salida de un agente. Se usa con OutputScope para el seguimiento de mensajes de salida. Acepta cadenas sin formato, objetos OutputMessage estructurados de OTEL o un dict sin procesar (tratado como resultado de llamada de herramienta por especificación de OTEL).

Referencia a un intervalo primario para la vinculación explícita de elementos primarios y secundarios a través de límites asincrónicos. Se usa cuando se produce un error en la propagación automática del contexto (por ejemplo, devoluciones de llamada de WebSocket, controladores de eventos externos).

Razonamiento del modelo/contenido de cadena de pensamiento.

Representa una solicitud con contexto de telemetría. Se usa en todos los tipos de ámbito para el seguimiento de canales y conversaciones.

Invocación de herramientas del lado servidor.

Respuesta de la herramienta del lado servidor.

Representa un punto de conexión para la invocación del agente.

Detalles de configuración del intervalo para la creación del ámbito. Agrupa las opciones de intervalo de OpenTelemetry en un único objeto, por lo que la firma del método de ámbito permanece estable a medida que se agregan nuevas opciones.

Contenido de texto sin formato.

Detalles de una llamada de herramienta realizada por un agente

Una llamada de herramienta solicitada por el modelo.

Resultado de una llamada a herramienta.

Referencia de URI externo.

Detalles sobre el autor de la llamada del usuario humano.

Tipo de operador para encabezados HTTP usados en la propagación del contexto de seguimiento. Compatible con Node.js IncomingHttpHeaders y mapas de cadenas sin formato.

Entrada aceptada para recordInputMessages. Admite una sola cadena, una matriz de cadenas (compatibilidad con versiones anteriores) o el contenedor con versiones.

Unión de todos los tipos de elementos de mensaje por convenciones semánticas de OTEL gen-ai.

Nota: GenericPart actúa como un punto de referencia para la compatibilidad directa con tipos de elementos personalizados o futuros. Dado que es type (no es un literal), exhaustivo switch/case en part.type no producirá errores en tiempo de compilación para casos no controladas.string

Opciones de configuración de observabilidad: amplía las opciones de tiempo de ejecución. Todas las invalidaciones son funciones a las que se llama en cada acceso a propiedades.

Heredado de RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Nota: isDevelopmentEnvironment es un captador derivado de la clase de configuración (basada en clusterCategory), no una opción reemplazable.

Entrada aceptada para recordOutputMessages. Admite una sola cadena, una matriz de cadenas (compatibilidad con versiones anteriores) o el contenedor con versiones.

Un contexto primario para la creación del intervalo. Acepta cualquiera de:

• ParentSpanRef: par traceId/spanId explícito (enfoque manual)
• ParentContext: un contexto de OTel, normalmente de extractContextFromHeaders o propagation.extract()

Opciones de configuración para PerRequestSpanProcessor: amplía las opciones de tiempo de ejecución. Todas las invalidaciones son funciones a las que se llama en cada acceso a propiedades.

Heredado de RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Entrada aceptada para OutputResponse.messages. Admite cadenas sin formato, OutputMessages estructurados o un dict sin formato (tratado como resultado de llamada de herramienta por especificación de OTEL y serializado directamente a través de JSON.stringify).

Nombres de eventos usados por Agent365Exporter para el registro y la supervisión. Estos son tipos de eventos de baja cardinalidad para garantizar una supervisión y agregación eficaces.

Motivo por el que un modelo dejó de generarse por convenciones semánticas de OTEL gen-ai.

Representa una operación diferente para los tipos de inferencia del modelo.

Representa distintos roles que pueden invocar un agente.

Rol de un participante de mensajes por convenciones semánticas de OTEL gen-ai.

Modalidad multimedia para elementos de blob, archivo y URI.

Crea un nuevo contexto con una referencia explícita de intervalo primario. Esto permite que los intervalos secundarios estén correctamente primarios incluso cuando se interrumpe el contexto asincrónico.

Extrae el contexto de seguimiento de los encabezados HTTP entrantes mediante el propagador W3C registrado globalmente. Devuelve un objeto OTel ParentContext que se puede pasar a las clases de ámbito como ParentContext.

Ejemplo

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });

Dar formato al objeto de error para el registro con seguimiento de mensajes y pila

Recupere el token de exportación por solicitud de un contexto de OTel determinado (o el activo).

Obtención de la instancia del registrador actual

Inserta el contexto de seguimiento actual (traceparent/tracestate encabezados) en el objeto de encabezados proporcionado mediante el propagador W3C registrado globalmente.

Ejemplo

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });

Compruebe si la exportación por solicitud está habilitada. Precedencia: invalida internamente la > variable de entorno del proveedor > de configuración. Cuando está habilitada, se usa PerRequestSpanProcessor en lugar de BatchSpanProcessor. El token se pasa a través de OTel Context (almacenamiento local asincrónico) en el momento de la exportación.

Normaliza un objeto InputMessagesParam en un contenedor con InputMessages versiones.

• string / string[] → convertido en ChatMessage[] y encapsulado
• InputMessages → devuelto as-is

Normaliza un objeto OutputMessagesParam en un contenedor con OutputMessages versiones.

• string / string[] → convertido en OutputMessage[] y encapsulado
• OutputMessages → devuelto as-is

Restablecer al registrador de consola predeterminado (principalmente para pruebas)

Ejecute una función dentro de un contexto que contenga el token de exportación por solicitud. Esto mantiene el token solo en OTel Context (ALS), nunca en ningún registro.

El token se puede actualizar más adelante a través updateExportToken() de antes de vaciar el seguimiento, útil cuando la devolución de llamada es de larga duración y el token original puede expirar antes de la exportación.

Extrae el contexto de seguimiento de los encabezados HTTP entrantes y ejecuta la devolución de llamada dentro de ese contexto. Los intervalos creados dentro de la devolución de llamada se asociarán al seguimiento extraído.

Ejemplo

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});

Ejecuta una función de devolución de llamada dentro de un contexto que tiene una referencia explícita de intervalo primario. Esto resulta útil para crear intervalos secundarios en devoluciones de llamada asincrónicas en las que se interrumpe la propagación del contexto.

Garantiza que el valor siempre es una cadena que se puede analizar con JSON.

• Los objetos se serializan a través de JSON.stringify.
• Las cadenas que ya son objetos o matrices JSON válidos se pasan a través.
• Todas las demás cadenas (incluidas las primitivas JSON sin sistema operativo) se encapsulan: { [key]: value }.

Serializa un contenedor de mensajes con versiones en JSON.

La salida es el objeto contenedor completo: {"version":"0.1.0","messages":[...]}.

El try/catch garantiza que la grabación de telemetría no se produzca incluso cuando las partes del mensaje contienen valores no serializables JSON (por ejemplo, BigInt, referencias circulares).

Establecimiento de una implementación de registrador personalizado para el SDK de observabilidad

Ejemplo con Winston:

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});

Truncar un valor de cadena para MAX_ATTRIBUTE_LENGTH caracteres. Si el valor supera el límite, se recorta y se anexa un sufijo de truncamiento, con la longitud total limitada exactamente MAX_ATTRIBUTE_LENGTH.

Actualice el token de exportación en el contexto de OTel activo. Llame a esto para actualizar el token antes de finalizar el intervalo raíz cuando el token original haya expirado durante una solicitud de larga duración.

Debe llamarse a dentro del mismo contexto asincrónico creado por runWithExportToken.

Longitud máxima para los valores de atributo de intervalo. Los valores que superen este límite se truncarán con un sufijo.

Proveedor predeterminado compartido para ObservabilityConfiguration.

Proveedor predeterminado compartido para PerRequestSpanProcessorConfiguration.

Instancia predeterminada del registrador para la compatibilidad con versiones anteriores. Delega al registrador global que se puede reemplazar a través de setLogger().