@microsoft/agents-a365-observability package

Maximum aantal spanten per exportbatch.

Per aanvraag bagagebouwer voor doorgifte van openTelemetry-context.

Deze klasse biedt een fluent-API voor het instellen van bagagewaarden die worden doorgegeven in de OpenTelemetry-context.

Voorbeeld

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

Contextmanager voor bagagebereik.

Deze klasse beheert de levenscyclus van bagagewaarden, stelt deze in bij het invoeren en herstellen van de vorige context bij het afsluiten.

Opbouwfunctie voor het configureren van Agent 365 met OpenTelemetry-tracering

Biedt openTelemetry-traceringsbereik voor uitvoeringsbewerkingen van AI-hulpprogramma's.

Biedt openTelemetry-traceringsbereik voor generatieve AI-deductiebewerkingen.

Biedt openTelemetry-traceringsbereik voor aanroepbewerkingen voor AI-agents.

Configuratie voor waarneembaarheidspakket. Neemt runtime-instellingen over en voegt waarneembaarheidsspecifieke instellingen toe.

Hoofdinvoerpunt voor Agent 365 die OpenTelemetry-tracering biedt voor AI-agents en -hulpprogramma's

OpenTelemetry-constanten voor Agent 365

Basisklasse voor OpenTelemetry-traceringsbereiken

Biedt openTelemetry-traceringsbereik voor tracering van uitvoerberichten met bovenliggende spankoppeling.

Configuratie voor PerRequestSpanProcessor. Neemt runtime-instellingen (clusterCategory, isNodeEnvDevelopment) over en voegt processorbeveiligingen per aanvraag toe.

Dit is gescheiden van ObservabilityConfiguration omdat PerRequestSpanProcessor alleen wordt gebruikt in specifieke scenario's en deze instellingen mogen niet worden weergegeven in de algemene ObservabilityConfiguration.

Details over een AI-agent

Inline binaire gegevens (base64-gecodeerd).

Configuratieopties voor Agent 365 Observability Builder

Details van beller voor het maken van een bereik. Ondersteunt menselijke bellers, agentoproepers of beide (A2A met een mens in de keten).

Opmerking over migratie: In v1 verwijst de naam CallerDetails naar de identiteit van de menselijke beller (nu UserDetails). In v2 werd het opnieuw gebruikt als een wrapper die zowel menselijke als agentaanroepergegevens groepeerde.

Zie UserDetails — identiteit voor menselijke aanroeper (eerder CallerDetails) Zie CHANGELOG.md — sectie met wijzigingen die fouten veroorzaken voor migratierichtlijnen

Vertegenwoordigt het kanaal voor een aanroep

Een invoerbericht dat wordt verzonden naar een model (semantische conventies van OTEL gen-ai).

Verwijzing naar een vooraf geüpload bestand.

Uitbreidbaar onderdeel voor aangepaste/toekomstige typen.

Uitbreidbare serverhulpprogramma roept details aan met een typediscriminator.

Uitbreidbaar serverhulpprogramma roept antwoord aan met een typediscriminator.

Aangepaste logboekinterface voor agent 365 waarneembaarheid Implementeer deze interface ter ondersteuning van back-ends voor logboekregistratie

Details voor een deductieaanroep

Details voor het opnemen van het antwoord van een deductieaanroep

Details voor het aanroepen van agentbereik.

Een uitvoerbericht dat wordt geproduceerd door een model (semantische conventies van OTEL gen-ai).

Vertegenwoordigt een antwoord met uitvoerberichten van een agent. Wordt gebruikt met OutputScope voor tracering van uitvoerberichten. Accepteert gewone tekenreeksen, gestructureerde OTEL OutputMessage-objecten of een onbewerkte dict (behandeld als een resultaat van een hulpprogramma-aanroep per OTEL-specificatie).

Verwijzing naar een bovenliggend bereik voor expliciete bovenliggende en onderliggende koppelingen tussen asynchrone grenzen. Wordt gebruikt wanneer automatische doorgifte van context mislukt (bijvoorbeeld WebSocket-callbacks, externe gebeurtenis-handlers).

Modelredenering/ keten-van-gedachte-inhoud.

Vertegenwoordigt een aanvraag met telemetriecontext. Wordt gebruikt voor alle bereiktypen voor kanaal- en gesprekstracering.

Aanroepen van hulpprogramma aan de serverzijde.

Reactie op het hulpprogramma aan de serverzijde.

Vertegenwoordigt een eindpunt voor agentaanroep

Bespan de configuratiedetails voor het maken van een bereik. Groepen OpenTelemetry span options into a single object so the scope method signature blijft stabiel terwijl er nieuwe opties worden toegevoegd.

Tekst zonder opmaak.

Details van een aanroep van een hulpprogramma door een agent

Een door het model aangevraagde hulpprogramma-aanroep.

Resultaat van een aanroep van een hulpprogramma.

Externe URI-verwijzing.

Details over de beller van de menselijke gebruiker.

Type provider voor HTTP-headers die worden gebruikt bij traceringscontextdoorgifte. Compatibel met Node.js IncomingHttpHeaders en tekenreekstoewijzingen zonder opmaak.

Geaccepteerde invoer voor recordInputMessages. Ondersteunt één tekenreeks, een matrix met tekenreeksen (achterwaartse compatibiliteit) of de geversiede wrapper.

Samenvoeging van alle typen berichtenonderdelen per semantische conventies van OTEL gen-ai.

Opmerking: GenericPart fungeert als een catch-all voor doorstuurcompatibiliteit met aangepaste of toekomstige onderdelentypen. Omdat het type is string (niet een letterlijke), zal uitputtendswitch/caseop part.type niet-verwerkte gevallen geen compilatiefouten produceren.

Configuratieopties voor waarneembaarheid: breidt runtime-opties uit. Alle onderdrukkingen zijn functies die worden aangeroepen voor elke toegang tot eigenschappen.

Overgenomen van RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Opmerking: isDevelopmentEnvironment is een afgeleide getter voor de configuratieklasse (op basis van clusterCategory), niet een overschrijfbare optie.

Geaccepteerde invoer voor recordOutputMessages. Ondersteunt één tekenreeks, een matrix met tekenreeksen (achterwaartse compatibiliteit) of de geversiede wrapper.

Een bovenliggende context voor het maken van spanen. Accepteert ofwel:

• ParentSpanRef: expliciet traceId/spanId-paar (handmatige benadering)
• ParentContext: een OTel-context, meestal van extractContextFromHeaders of propagation.extract()

Configuratieopties voor PerRequestSpanProcessor - breidt runtime-opties uit. Alle onderdrukkingen zijn functies die worden aangeroepen voor elke toegang tot eigenschappen.

Overgenomen van RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Geaccepteerde invoer voor OutputResponse.messages. Ondersteunt gewone tekenreeksen, gestructureerde OutputMessages of een onbewerkte dict (behandeld als een resultaat van het aanroepen van een hulpprogramma per OTEL-specificatie en rechtstreeks geserialiseerd via JSON.stringify).

Gebeurtenisnamen die worden gebruikt door Agent365Exporter voor logboekregistratie en bewaking. Dit zijn gebeurtenistypen met lage kardinaliteit om efficiënte bewaking en aggregatie te garanderen.

Reden waarom een model is gestopt met het genereren van semantische conventies per OTEL gen-ai.

Vertegenwoordigt verschillende bewerkingen voor typen voor modeldeductie

Vertegenwoordigt verschillende rollen die een agent kunnen aanroepen

Rol van een deelnemer aan een bericht per semantische conventies van OTEL gen-ai.

Mediamodale media voor blob-, bestands- en URI-onderdelen.

Hiermee maakt u een nieuwe context met een expliciete bovenliggende spanreferentie. Hierdoor kunnen onderliggende spanen correct worden parented, zelfs wanneer de asynchrone context wordt verbroken.

Extraheert traceringscontext uit binnenkomende HTTP-headers met behulp van de wereldwijd geregistreerde W3C-doorgifte. Hiermee wordt een OTel ParentContext geretourneerd die als ParentContext kan worden doorgegeven aan bereikklassen.

Voorbeeld

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

Foutobject opmaken voor logboekregistratie met bericht- en stacktracering

Haal het exporttoken per aanvraag op uit een bepaalde OTel-context (of de actieve).

Het huidige logboekregistratieexemplaren ophalen

Injecteert de huidige traceringscontext (traceparent/tracestate headers) in het opgegeven headers-object met behulp van de wereldwijd geregistreerde W3C-doorgifte.

Voorbeeld

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

Controleer of export per aanvraag is ingeschakeld. Prioriteit: interne overschrijft omgevingsvariabele > van de configuratieprovider > . Als deze optie is ingeschakeld, wordt de PerRequestSpanProcessor gebruikt in plaats van BatchSpanProcessor. Het token wordt doorgegeven via OTel Context (asynchrone lokale opslag) tijdens de export.

Normaliseert een InputMessagesParam naar een geversiede InputMessages wrapper.

• string / string[] → geconverteerd naar ChatMessage[] en verpakt
• InputMessages → geretourneerde as-is

Normaliseert een OutputMessagesParam naar een geversiede OutputMessages wrapper.

• string / string[] → geconverteerd naar OutputMessage[] en verpakt
• OutputMessages → geretourneerde as-is

Opnieuw instellen op de standaardconsolelogger (voornamelijk voor testen)

Voer een functie uit binnen een context die het exporttoken per aanvraag bevat. Hierdoor blijft het token alleen in OTel Context (ALS), nooit in een register.

Het token kan later updateExportToken() worden bijgewerkt voordat de tracering wordt leeggemaakt, handig wanneer de callback lang actief is en het oorspronkelijke token kan verlopen voordat de export wordt uitgevoerd.

Extraheert traceringscontext uit binnenkomende HTTP-headers en voert de callback uit binnen die context. Alle spanten die in de callback zijn gemaakt, worden bovenliggend aan de geëxtraheerde tracering.

Voorbeeld

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

Voert een callback-functie uit binnen een context met een expliciete bovenliggende spanreferentie. Dit is handig voor het maken van onderliggende spanten in asynchrone callbacks waarbij contextdoorgifte wordt verbroken.

Zorgt ervoor dat de waarde altijd een JSON-parseerbare tekenreeks is.

• Objecten worden geserialiseerd via JSON.stringify.
• Tekenreeksen die al geldige JSON-objecten/matrices zijn, worden doorgegeven.
• Alle andere tekenreeksen (inclusief bare JSON-primitieven) worden verpakt: { [key]: value }.

Serialiseert een versie van een bericht-wrapper naar JSON.

De uitvoer is het volledige wrapperobject: {"version":"0.1.0","messages":[...]}.

De try/catch zorgt ervoor dat telemetrie-opname niet genereert, zelfs wanneer berichtonderdelen niet-JSON-serialiseerbare waarden bevatten (bijvoorbeeld BigInt, kringverwijzingen).

Een aangepaste logboekregistratie-implementatie instellen voor de waarneembaarheids-SDK

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

Werk het exporttoken bij in de actieve OTel-context. Roep dit aan om het token te vernieuwen voordat het hoofdbereik wordt beëindigd wanneer het oorspronkelijke token mogelijk is verlopen tijdens een langlopende aanvraag.

Moet worden aangeroepen binnen dezelfde asynchrone context die is gemaakt door runWithExportToken.

Gedeelde standaardprovider voor ObservabilityConfiguration.

Gedeelde standaardprovider voor PerRequestSpanProcessorConfiguration.

Standaardloggerexemplaren voor achterwaartse compatibiliteit. Gemachtigden voor de globale logboekregistratie die kan worden vervangen via setLogger().