@microsoft/agents-a365-observability package

Numero massimo di intervalli per batch di esportazione.

Generatore di bagagli per richiesta per la propagazione del contesto OpenTelemetry.

Questa classe fornisce un'API Fluent per impostare i valori dei bagagli che verranno propagati nel contesto OpenTelemetry.

Esempio

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

Gestore del contesto per l'ambito dei bagagli.

Questa classe gestisce il ciclo di vita dei valori dei bagagli, impostandoli in entrata e ripristinando il contesto precedente all'uscita.

Generatore per la configurazione dell'agente 365 con la traccia OpenTelemetry

Fornisce l'ambito di traccia OpenTelemetry per le operazioni di esecuzione degli strumenti di intelligenza artificiale.

Fornisce l'ambito di traccia OpenTelemetry per le operazioni di inferenza di intelligenza artificiale generative.

Fornisce l'ambito di traccia OpenTelemetry per le operazioni di chiamata dell'agente di intelligenza artificiale.

Configurazione per il pacchetto di osservabilità. Eredita le impostazioni di runtime e aggiunge impostazioni specifiche dell'osservabilità.

Punto di ingresso principale per Agent 365 che fornisce la traccia OpenTelemetry per gli agenti e gli strumenti di intelligenza artificiale

Costanti OpenTelemetry per Agent 365

Classe base per gli ambiti di traccia OpenTelemetry

Fornisce l'ambito di traccia OpenTelemetry per la traccia dei messaggi di output con il collegamento dell'intervallo padre.

Configurazione per PerRequestSpanProcessor. Eredita le impostazioni di runtime (clusterCategory, isNodeEnvDevelopment) e aggiunge protezioni del processore per richiesta.

Questa opzione è separata da ObservabilityConfiguration perché PerRequestSpanProcessor viene usato solo in scenari specifici e queste impostazioni non devono essere esposte in Common ObservabilityConfiguration.

Dettagli su un agente di intelligenza artificiale

Dati binari inline (con codifica Base64).

Opzioni di configurazione per Agent 365 Observability Builder

Dettagli del chiamante per la creazione dell'ambito. Supporta chiamanti umani, chiamanti agente o entrambi (A2A con un essere umano nella catena).

Nota sulla migrazione: Nella versione 1 il nome CallerDetails a cui si fa riferimento all'identità del chiamante umano (ora UserDetails). Nella versione 2 è stato reimpierito come wrapper che raggruppa le informazioni del chiamante sia umano che dell'agente.

Per indicazioni sulla migrazione, vedere UserDetails - Identità chiamante umana (in precedenza CallerDetails) Vedere CHANGELOG.md - Modifiche che causano interruzioni

Rappresenta il canale per una chiamata

Messaggio di input inviato a un modello (convenzioni semantiche di generazione ROUTE).

Riferimento a un file precaricati.

Parte estendibile per i tipi personalizzati/futuri.

Dettagli delle chiamate dello strumento server estendibili con un discriminante di tipo.

Risposta di chiamata dello strumento server estendibile con un discriminante di tipo.

Interfaccia del logger personalizzata per l'osservabilità di Agent 365 Implementare questa interfaccia per supportare i back-end di registrazione

Dettagli per una chiamata di inferenza

Dettagli per registrare la risposta da una chiamata di inferenza

Dettagli per richiamare l'ambito dell'agente.

Messaggio di output generato da un modello (convenzioni semantiche di generazione ROUTE).

Rappresenta una risposta contenente i messaggi di output di un agente. Usato con OutputScope per la traccia dei messaggi di output. Accetta stringhe semplici, oggetti OutputMessage strutturati INTUNE o un dict non elaborato (considerato come risultato di una chiamata dello strumento per ogni specifica INTUNE).

Riferimento a un intervallo padre per il collegamento esplicito padre-figlio attraverso i limiti asincroni. Usato quando la propagazione automatica del contesto ha esito negativo (ad esempio, callback WebSocket, gestori eventi esterni).

Ragionamento del modello/contenuto concatenato.

Rappresenta una richiesta con contesto di telemetria. Usato in tutti i tipi di ambito per il rilevamento di canali e conversazioni.

Chiamata dello strumento sul lato server.

Risposta dello strumento sul lato server.

Rappresenta un endpoint per la chiamata dell'agente

Estendere i dettagli di configurazione per la creazione dell'ambito. Raggruppa le opzioni dell'intervallo OpenTelemetry in un singolo oggetto in modo che la firma del metodo di ambito rimanga stabile man mano che vengono aggiunte nuove opzioni.

Contenuto testo normale.

Dettagli di una chiamata di strumento effettuata da un agente

Chiamata dello strumento richiesta dal modello.

Risultato di una chiamata di strumento.

Riferimento URI esterno.

Dettagli sul chiamante dell'utente umano.

Tipo di vettore per le intestazioni HTTP usate nella propagazione del contesto di traccia. Compatibile con Node.js IncomingHttpHeaders e le mappe di stringhe semplici.

Input accettato per recordInputMessages. Supporta una singola stringa, una matrice di stringhe (compatibilità con le versioni precedenti) o il wrapper con versione.

Unione di tutti i tipi di parti di messaggio per ogni convenzione semantica di generazione-intelligenza artificiale di ROUTE.

Nota: GenericPart funge da catch-all per la compatibilità con i tipi di parte personalizzati o futuri. type Poiché è string (non un valore letterale), esaustivocaseswitch/su part.type non produrrà errori in fase di compilazione per i casi non gestiti.

Opzioni di configurazione osservabilità: estende le opzioni di runtime. Tutte le sostituzioni sono funzioni chiamate per ogni accesso alle proprietà.

Ereditato da RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Nota: isDevelopmentEnvironment è un getter derivato nella classe di configurazione (basata su clusterCategory), non un'opzione sottoponibile a override.

Input accettato per recordOutputMessages. Supporta una singola stringa, una matrice di stringhe (compatibilità con le versioni precedenti) o il wrapper con versione.

Contesto padre per la creazione dell'intervallo. Accetta una:

• ParentSpanRef: coppia traceId/spanId esplicita (approccio manuale)
• ParentContext: un contesto OTel, in genere da extractContextFromHeaders o propagation.extract()

Opzioni di configurazione per PerRequestSpanProcessor: estende le opzioni di runtime. Tutte le sostituzioni sono funzioni chiamate per ogni accesso alle proprietà.

Ereditato da RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Input accettato per OutputResponse.messages. Supporta stringhe semplici, outputMessage strutturati o un dict non elaborato (considerato come risultato della chiamata dello strumento per specifica INTUNE e serializzato direttamente tramite JSON.stringify).

Nomi di eventi usati da Agent365Exporter per la registrazione e il monitoraggio. Si tratta di tipi di evento a cardinalità bassa per garantire un monitoraggio e un'aggregazione efficienti.

Motivo per cui un modello ha smesso di generare le convenzioni semantiche di generazione ROUTE gen-ai.

Rappresenta un'operazione diversa per i tipi per l'inferenza del modello

Rappresenta ruoli diversi che possono richiamare un agente

Ruolo di un partecipante di un messaggio per convenzioni semantiche di intelligenza artificiale di generazione ROUTE.

Modalità multimediale per parti BLOB, file e URI.

Crea un nuovo contesto con un riferimento esplicito all'intervallo padre. In questo modo, gli intervalli figlio devono essere correttamente padre anche quando il contesto asincrono viene interrotto.

Estrae il contesto di traccia dalle intestazioni HTTP in ingresso usando il propagatore W3C registrato a livello globale. Restituisce un oggetto OTel ParentContext che può essere passato alle classi di ambito come ParentContext.

Esempio

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

Formattare l'oggetto errore per la registrazione con il messaggio e l'analisi dello stack

Recuperare il token di esportazione per richiesta da un determinato contesto OTel (o da quello attivo).

Ottenere l'istanza del logger corrente

Inserisce il contesto di traccia corrente (traceparent/tracestate intestazioni) nell'oggetto intestazioni fornito usando il propagatore W3C registrato a livello globale.

Esempio

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

Controllare se l'esportazione per richiesta è abilitata. Precedenza: la variabile di ambiente del provider di > configurazione esegue l'override > interno. Se abilitata, viene usato PerRequestSpanProcessor anziché BatchSpanProcessor. Il token viene passato tramite OTel Context (archiviazione locale asincrona) in fase di esportazione.

Normalizza un oggetto InputMessagesParam in un wrapper con InputMessages controllo delle versioni.

• string / string[] → convertito in e sottoposto a ChatMessage[] wrapping
• InputMessages → restituito as-is

Normalizza un oggetto OutputMessagesParam in un wrapper con OutputMessages controllo delle versioni.

• string / string[] → convertito in e sottoposto a OutputMessage[] wrapping
• OutputMessages → restituito as-is

Ripristinare il logger di console predefinito (principalmente per i test)

Eseguire una funzione all'interno di un contesto che contiene il token di esportazione per richiesta. In questo modo il token viene mantenuto solo in OTel Context (ALS), mai in alcun Registro di sistema.

Il token può essere aggiornato in un secondo momento tramite updateExportToken() prima che la traccia venga scaricata, utile quando il callback è a esecuzione prolungata e il token originale può scadere prima dell'esportazione.

Estrae il contesto di traccia dalle intestazioni HTTP in ingresso ed esegue il callback all'interno di tale contesto. Qualsiasi intervallo creato all'interno del callback verrà padre della traccia estratta.

Esempio

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

Esegue una funzione di callback all'interno di un contesto con un riferimento esplicito all'intervallo padre. Ciò è utile per la creazione di intervalli figlio in callback asincroni in cui la propagazione del contesto viene interrotta.

Assicura che il valore sia sempre una stringa analizzabile JSON.

• Gli oggetti vengono serializzati tramite JSON.stringify.
• Le stringhe che sono già oggetti/matrici JSON validi vengono passate.
• Tutte le altre stringhe (incluse le primitive JSON bare) vengono incapsulate: { [key]: value }.

Serializza un wrapper di messaggi con versione in JSON.

L'output è l'oggetto wrapper completo: {"version":"0.1.0","messages":[...]}.

Il try/catch garantisce che la registrazione dei dati di telemetria non venga generata anche quando le parti del messaggio contengono valori non serializzabili JSON ,ad esempio BigInt, ref circolari.

Impostare un'implementazione del logger personalizzata per l'SDK di osservabilità

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

Tronca un valore stringa per MAX_ATTRIBUTE_LENGTH caratteri. Se il valore supera il limite, viene tagliato e viene aggiunto un suffisso di troncamento, con la lunghezza totale limitata esattamente MAX_ATTRIBUTE_LENGTH.

Aggiornare il token di esportazione nel contesto OTel attivo. Chiamare questa opzione per aggiornare il token prima di terminare l'intervallo radice quando il token originale potrebbe essere scaduto durante una richiesta con esecuzione prolungata.

Deve essere chiamato all'interno dello stesso contesto asincrono creato da runWithExportToken.

Lunghezza massima per i valori dell'attributo span. I valori che superano questo limite verranno troncati con un suffisso.

Provider predefinito condiviso per ObservabilityConfiguration.

Provider predefinito condiviso per PerRequestSpanProcessorConfiguration.

Istanza del logger predefinita per la compatibilità con le versioni precedenti. Delegati al logger globale che può essere sostituito tramite setLogger().