@microsoft/agents-a365-observability package

Nombre maximal d’étendues par lot d’exportation.

Par générateur de bagages de demande pour la propagation du contexte OpenTelemetry.

Cette classe fournit une API Fluent pour définir les valeurs de bagages qui seront propagées dans le contexte OpenTelemetry.

Exemple

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

Gestionnaire de contexte pour l’étendue des bagages.

Cette classe gère le cycle de vie des valeurs de bagages, en les définissant sur entrée et en restaurant le contexte précédent lors de la sortie.

Générateur de configuration de l’agent 365 avec le suivi OpenTelemetry

Fournit l’étendue de suivi OpenTelemetry pour les opérations d’exécution d’outils IA.

Fournit l’étendue de suivi OpenTelemetry pour les opérations d’inférence IA génératives.

Fournit l’étendue de suivi OpenTelemetry pour les opérations d’appel d’agent IA.

Configuration du package d’observabilité. Hérite des paramètres d’exécution et ajoute des paramètres spécifiques à l’observabilité.

Point d’entrée principal de l’agent 365 fournissant le suivi OpenTelemetry pour les agents et outils IA

Constantes OpenTelemetry pour Agent 365

Classe de base pour les étendues de suivi OpenTelemetry

Fournit l’étendue de suivi OpenTelemetry pour le suivi des messages de sortie avec la liaison d’étendue parente.

Configuration de PerRequestSpanProcessor. Hérite des paramètres d’exécution (clusterCategory, isNodeEnvDevelopment) et ajoute des garde-fous de processeur par requête.

Cela est séparé de ObservabilityConfiguration, car PerRequestSpanProcessor est utilisé uniquement dans des scénarios spécifiques et ces paramètres ne doivent pas être exposés dans la common ObservabilityConfiguration.

Détails sur un agent IA

Données binaires inline (encodées en base64).

Options de configuration pour Agent 365 Observability Builder

Détails de l’appelant pour la création de l’étendue. Prend en charge les appelants humains, les appelants d’agent ou les deux (A2A avec un humain dans la chaîne).

Remarque sur la migration : Dans v1, le nom CallerDetails fait référence à l’identité de l’appelant humain (maintenant UserDetails). Dans la version 2, elle a été réaffectée en tant que wrapper qui regroupe les informations de l’appelant humain et de l’agent.

Voir UserDetails — Identité de l’appelant humain (précédemment CallerDetails) Voir CHANGELOG.md — section changements cassants pour obtenir des conseils sur la migration

Représente le canal d’un appel

Message d’entrée envoyé à un modèle (conventions sémantiques TELLI gen-ai).

Référence à un fichier préchargement chargé.

Partie extensible pour les types personnalisés/ futurs.

Détails de l’appel de l’outil serveur extensible avec un discriminateur de type.

Réponse d’appel de l’outil serveur extensible avec un discriminateur de type.

Interface d’enregistreur d’événements personnalisé pour l’observabilité Agent 365 Implémenter cette interface pour prendre en charge la journalisation des back-ends

Détails d’un appel d’inférence

Détails de l’enregistrement de la réponse à partir d’un appel d’inférence

Détails de l’appel de l’étendue de l’agent.

Message de sortie généré par un modèle (conventions sémantiques TELLI gen-ai).

Représente une réponse contenant des messages de sortie d’un agent. Utilisé avec OutputScope pour le suivi des messages de sortie. Accepte des chaînes simples, des objets OutputMessage ISTO structurés ou une dictée brute (traitée comme un résultat d’appel d’outil par spécification EAP).

Référence à une étendue parente pour la liaison parent-enfant explicite entre les limites asynchrones. Utilisé lorsque la propagation automatique du contexte échoue (par exemple, rappels WebSocket, gestionnaires d’événements externes).

Raisonnement du modèle / contenu chaîné de pensée.

Représente une requête avec le contexte de télémétrie. Utilisé dans tous les types d’étendue pour le suivi des canaux et des conversations.

Appel de l’outil côté serveur.

Réponse de l’outil côté serveur.

Représente un point de terminaison pour l’appel d’agent

Étendez les détails de configuration pour la création de l’étendue. Regroupe les options d’étendue OpenTelemetry dans un seul objet afin que la signature de la méthode d’étendue reste stable à mesure que de nouvelles options sont ajoutées.

Contenu en texte brut.

Détails d’un appel d’outil effectué par un agent

Un appel d’outil demandé par le modèle.

Résultat d’un appel d’outil.

Référence d’URI externe.

Détails sur l’appelant d’utilisateur humain.

Type de transporteur pour les en-têtes HTTP utilisés dans la propagation du contexte de trace. Compatible avec Node.js IncomingHttpHeaders et les mappages de chaînes simples.

Entrée acceptée pour recordInputMessages. Prend en charge une seule chaîne, un tableau de chaînes (compat descendant) ou le wrapper avec version.

Union de tous les types de parties de message par conventions sémantiques AUTHENTIFICATION gen-ai.

Remarque : GenericPart agit comme un catch-all pour la compatibilité ascendante avec les types de composants personnalisés ou futurs. Étant donné qu’il type est string (pas un littéral), exhaustifcaseswitch/sur part.type ne produit pas d’erreurs au moment de la compilation pour les cas non gérés.

Options de configuration de l’observabilité : étend les options d’exécution. Toutes les substitutions sont des fonctions appelées sur chaque accès aux propriétés.

Hérité de RuntimeConfigurationOptions :

• clusterCategory
• isNodeEnvDevelopment

Remarque : isDevelopmentEnvironment est un getter dérivé sur la classe de configuration (basé sur clusterCategory), et non une option substituable.

Entrée acceptée pour recordOutputMessages. Prend en charge une seule chaîne, un tableau de chaînes (compat descendant) ou le wrapper avec version.

Contexte parent pour la création d’étendues. Accepte soit :

• ParentSpanRef : paire traceId/spanId explicite (approche manuelle)
• ParentContext: un contexte OTel, généralement à partir d’extractContextFromHeaders ou propagation.extract()

Options de configuration pour PerRequestSpanProcessor : étend les options d’exécution. Toutes les substitutions sont des fonctions appelées sur chaque accès aux propriétés.

Hérité de RuntimeConfigurationOptions :

• clusterCategory, isNodeEnvDevelopment

Entrée acceptée pour OutputResponse.messages. Prend en charge les chaînes simples, les OutputMessages structurés ou une dictée brute (traitée comme un résultat d’appel d’outil par spécification EAP et sérialisée directement via JSON.stringify).

Noms d’événements utilisés par Agent365Exporter pour la journalisation et la surveillance. Il s’agit de types d’événements de faible cardinalité pour garantir une surveillance et une agrégation efficaces.

Raison pour laquelle un modèle a cessé de générer par conventions sémantiques gen-ai TELLI.

Représente une opération différente pour les types pour l’inférence de modèle

Représente différents rôles qui peuvent appeler un agent

Rôle d’un participant au message par conventions sémantiques TELLI gen-ai.

Modalité multimédia pour les parties blob, fichier et URI.

Crée un contexte avec une référence d’étendue parente explicite. Cela permet aux étendues enfants d’être correctement parentées même lorsque le contexte asynchrone est rompu.

Extrait le contexte de trace des en-têtes HTTP entrants à l’aide du propagateur W3C enregistré globalement. Retourne un OTel ParentContext qui peut être passé aux classes d’étendue en tant que ParentContext.

Exemple

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

Format d’objet d’erreur pour la journalisation avec la trace de message et de pile

Récupérez le jeton d’exportation par requête à partir d’un contexte OTel donné (ou actif).

Obtenir l’instance d’enregistreur d’événements actuel

Injecte le contexte de trace actuel (traceparent/tracestate en-têtes) dans l’objet d’en-têtes fourni à l’aide du propageur W3C enregistré globalement.

Exemple

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

Vérifiez si l’exportation par demande est activée. Priorité : variable d’environnement du fournisseur > de configuration de remplacement > interne. Lorsqu’il est activé, perRequestSpanProcessor est utilisé au lieu de BatchSpanProcessor. Le jeton est transmis via OTel Context (stockage local asynchrone) au moment de l’exportation.

Normalise un InputMessagesParam wrapper avec version.InputMessages

• string / string[]→ converties en wrapper et encapsulées ChatMessage[]
• InputMessages → retourné as-is

Normalise un OutputMessagesParam wrapper avec version.OutputMessages

• string / string[]→ converties en wrapper et encapsulées OutputMessage[]
• OutputMessages → retourné as-is

Rétablir l’enregistreur d’événements de console par défaut (principalement pour les tests)

Exécutez une fonction dans un contexte qui contient le jeton d’exportation par requête. Cela conserve le jeton uniquement dans OTel Context (ALS), jamais dans un registre.

Le jeton peut être mis à jour ultérieurement avant updateExportToken() le vidage de la trace . Utile lorsque le rappel est long et que le jeton d’origine peut expirer avant l’exportation.

Extrait le contexte de trace des en-têtes HTTP entrants et exécute le rappel dans ce contexte. Toutes les étendues créées à l’intérieur du rappel sont parentées de la trace extraite.

Exemple

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

Exécute une fonction de rappel dans un contexte qui a une référence d’étendue parente explicite. Cela est utile pour créer des étendues enfants dans des rappels asynchrones où la propagation du contexte est interrompue.

Garantit que la valeur est toujours une chaîne d’analyse JSON.

• Les objets sont sérialisés via JSON.stringify.
• Les chaînes qui sont déjà des objets/tableaux JSON valides sont passées.
• Toutes les autres chaînes (y compris les primitives JSON nues) sont encapsulées : { [key]: value }.

Sérialise un wrapper de message versionné au format JSON.

La sortie est l’objet wrapper complet : {"version":"0.1.0","messages":[...]}.

La méthode try/catch garantit que l’enregistrement de télémétrie n’est pas levée même si les parties de message contiennent des valeurs non-JSON sérialisables (par exemple, BigInt, refs circulaires).

Définir une implémentation d’enregistreur d’événements personnalisée pour le Kit de développement logiciel (SDK) observabilité

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

Tronquer une valeur de chaîne pour MAX_ATTRIBUTE_LENGTH caractères. Si la valeur dépasse la limite, elle est rognée et un suffixe de troncation est ajouté, avec la longueur totale limitée à exactement MAX_ATTRIBUTE_LENGTH.

Mettez à jour le jeton d’exportation dans le contexte OTel actif. Appelez-le pour actualiser le jeton avant de mettre fin à l’étendue racine lorsque le jeton d’origine a expiré pendant une demande de longue durée.

Doit être appelé dans le même contexte asynchrone créé par runWithExportToken.

Longueur maximale pour les valeurs d’attribut d’étendue. Les valeurs dépassant cette limite sont tronquées avec un suffixe.

Fournisseur par défaut partagé pour ObservabilityConfiguration.

Fournisseur par défaut partagé pour PerRequestSpanProcessorConfiguration.

Instance d’enregistreur d’événements par défaut pour la compatibilité descendante. Délégués à l’enregistreur d’événements global qui peuvent être remplacés via setLogger().