@microsoft/agents-a365-observability package

Maksymalna liczba zakresów na partię eksportu.

Na żądanie konstruktor bagażu dla propagacji kontekstu OpenTelemetry.

Ta klasa zapewnia płynny interfejs API do ustawiania wartości bagażu, które będą propagowane w kontekście OpenTelemetry.

Przykład

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

Menedżer kontekstu dla zakresu bagażu.

Ta klasa zarządza cyklem życia wartości bagażu, ustawiając je podczas wprowadzania i przywracania poprzedniego kontekstu podczas zamykania.

Konstruktor do konfigurowania agenta 365 przy użyciu śledzenia OpenTelemetry

Udostępnia zakres śledzenia OpenTelemetry dla operacji wykonywania narzędzi sztucznej inteligencji.

Udostępnia zakres śledzenia OpenTelemetry dla operacji wnioskowania generowania sztucznej inteligencji.

Udostępnia zakres śledzenia OpenTelemetry dla operacji wywołania agenta sztucznej inteligencji.

Konfiguracja pakietu do obserwowania. Dziedziczy ustawienia środowiska uruchomieniowego i dodaje ustawienia specyficzne dla obserwacji.

Główny punkt wejścia dla agenta 365 udostępniający śledzenie OpenTelemetry dla agentów i narzędzi sztucznej inteligencji

Stałe OpenTelemetry dla agenta 365

Klasa bazowa dla zakresów śledzenia OpenTelemetry

Zapewnia zakres śledzenia openTelemetry dla śledzenia komunikatów wyjściowych z nadrzędnym łączeniem zakresu.

Konfiguracja narzędzia PerRequestSpanProcessor. Dziedziczy ustawienia środowiska uruchomieniowego (clusterCategory, isNodeEnvDevelopment) i dodaje zabezpieczenia procesora na żądanie.

Jest to oddzielone od funkcji ObservabilityConfiguration, ponieważ narzędzie PerRequestSpanProcessor jest używane tylko w określonych scenariuszach, a te ustawienia nie powinny być uwidocznione w typowej funkcji ObservabilityConfiguration.

Szczegółowe informacje o agencie sztucznej inteligencji

Wbudowane dane binarne (zakodowane w formacie base64).

Opcje konfiguracji narzędzia Agent 365 Observability Builder

Szczegóły elementu wywołującego dotyczące tworzenia zakresu. Obsługuje osoby wywołujące ludzi, rozmówców agentów lub obie (A2A z człowiekiem w łańcuchu).

Uwaga dotycząca migracji: W wersji 1 nazwa CallerDetails odwołuje się do tożsamości osoby wywołującej (teraz UserDetails). W wersji 2 została ona przeprojektowana jako otoka, która grupuje zarówno informacje o człowieku, jak i rozmówcę agenta.

Zobacz UserDetails — tożsamość wywołująca człowieka (wcześniej CallerDetails) Zobacz sekcję CHANGELOG.md — zmiany powodujące niezgodność, aby uzyskać wskazówki dotyczące migracji

Reprezentuje kanał wywołania

Komunikat wejściowy wysyłany do modelu (konwencje semantyczne OTEL gen-ai).

Odwołanie do wstępnie przekazanego pliku.

Rozszerzalna część dla typów niestandardowych/przyszłych.

Rozszerzalne szczegóły wywołania narzędzia serwera z dyskryminującym typem.

Rozszerzalna odpowiedź wywołania narzędzia serwera z dyskryminującym typem.

Niestandardowy interfejs rejestratora dla możliwości obserwowania agenta 365 Implementowanie tego interfejsu w celu obsługi zapleczy rejestrowania

Szczegóły wywołania wnioskowania

Szczegóły rejestrowania odpowiedzi z wywołania wnioskowania

Szczegóły dotyczące wywoływania zakresu agenta.

Komunikat wyjściowy wygenerowany przez model (konwencje semantyczne OTEL gen-ai).

Reprezentuje odpowiedź zawierającą komunikaty wyjściowe z agenta. Używany z outputScope do śledzenia komunikatów wyjściowych. Akceptuje zwykłe ciągi, ustrukturyzowane obiekty OTEL OutputMessage lub nieprzetworzone dykt (traktowane jako wynik wywołania narzędzia na specyfikację OTEL).

Odwołanie do zakresu nadrzędnego dla jawnego łączenia elementu nadrzędnego-podrzędnego w granicach asynchronicznych. Używane, gdy propagacja kontekstu automatycznego kończy się niepowodzeniem (np. wywołania zwrotne protokołu WebSocket, programy obsługi zdarzeń zewnętrznych).

Rozumowanie modelu/łańcuch treści myślowych.

Reprezentuje żądanie z kontekstem telemetrii. Używane we wszystkich typach zakresu na potrzeby śledzenia kanałów i konwersacji.

Wywołanie narzędzia po stronie serwera.

Odpowiedź narzędzia po stronie serwera.

Reprezentuje punkt końcowy wywołania agenta

Szczegóły konfiguracji obejmują tworzenie zakresu. Grupuje opcje zakresu OpenTelemetry w jednym obiekcie, dzięki czemu sygnatura metody zakresu pozostaje stabilna w miarę dodawania nowych opcji.

Zawartość zwykłego tekstu.

Szczegóły wywołania narzędzia wykonanego przez agenta

Wywołanie narzędzia żądane przez model.

Wynik wywołania narzędzia.

Dokumentacja zewnętrznego identyfikatora URI.

Szczegółowe informacje o obiekcie wywołującym użytkownika ludzkiego.

Typ operatora dla nagłówków HTTP używanych w propagacji kontekstu śledzenia. Zgodność z mapami Node.js IncomingHttpHeaders i zwykłymi ciągami.

Zaakceptowane dane wejściowe dla elementu recordInputMessages. Obsługuje pojedynczy ciąg, tablicę ciągów (zgodność z poprzednimi wersjami) lub opakowy w wersji.

Związek wszystkich typów części komunikatów na konwencje semantyczne OTEL gen-ai.

Uwaga: Element GenericPart działa jako element catch-all w celu zapewnienia zgodności z niestandardowymi lub przyszłymi typami części. Ze względu na to, że jest to type (nie literał), wyczerpującestringswitch/ustawienie nie case spowoduje wygenerowania błędów czasu kompilacji w przypadku nieobsługiwanego przypadku.part.type

Opcje konfiguracji możliwości obserwacji — rozszerza opcje środowiska uruchomieniowego. Wszystkie przesłonięcia to funkcje wywoływane dla każdego dostępu do właściwości.

Dziedziczone z runtimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Uwaga: isDevelopmentEnvironment jest pochodnym elementem getter w klasie konfiguracji (w oparciu o klasterCategory), a nie opcją zastępowalną.

Zaakceptowane dane wejściowe dla elementu recordOutputMessages. Obsługuje pojedynczy ciąg, tablicę ciągów (zgodność z poprzednimi wersjami) lub opakowy w wersji.

Kontekst nadrzędny do tworzenia zakresu. Akceptuje albo:

• ParentSpanRef: jawna para traceId/spanId (podejście ręczne)
• ParentContext: kontekst OTel, zazwyczaj z extractContextFromHeaders lub propagation.extract()

Opcje konfiguracji narzędzia PerRequestSpanProcessor — rozszerza opcje środowiska uruchomieniowego. Wszystkie przesłonięcia to funkcje wywoływane dla każdego dostępu do właściwości.

Dziedziczone z runtimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Zaakceptowane dane wejściowe dla elementu OutputResponse.messages. Obsługuje zwykłe ciągi, ustrukturyzowane outputMessages lub nieprzetworzone dykt (traktowane jako wynik wywołania narzędzia dla specyfikacji OTEL i serializowane bezpośrednio za pośrednictwem formatu JSON.stringify).

Nazwy zdarzeń używane przez agenta365Exporter do rejestrowania i monitorowania. Są to typy zdarzeń o niskiej kardynalności, aby zapewnić wydajne monitorowanie i agregację.

Przyczyna, dla którego model przestał generować konwencje semantyczne OTEL gen-ai.

Reprezentuje różne operacje dla typów wnioskowania modelu

Reprezentuje różne role, które mogą wywoływać agenta

Rola uczestnika wiadomości na konwencje semantyczne OTEL gen-ai.

Modalność multimediów dla części obiektów blob, plików i identyfikatorów URI.

Tworzy nowy kontekst z jawnym odwołaniem zakresu nadrzędnego. Dzięki temu zakresy podrzędne mogą być poprawnie nadrzędne nawet wtedy, gdy kontekst asynchroniczny jest uszkodzony.

Wyodrębnia kontekst śledzenia z przychodzących nagłówków HTTP przy użyciu globalnie zarejestrowanego propagora W3C. Zwraca obiekt OTel ParentContext , który można przekazać do klas zakresu jako element ParentContext.

Przykład

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

Formatuj obiekt błędu rejestrowania za pomocą komunikatu i śledzenia stosu

Pobierz token eksportu na żądanie z danego kontekstu OTel (lub aktywnego).

Pobieranie bieżącego wystąpienia rejestratora

Wprowadza bieżący kontekst śledzenia (traceparent/tracestate nagłówki) do dostarczonego obiektu nagłówków przy użyciu globalnie zarejestrowanego propagora W3C.

Przykład

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

Sprawdź, czy eksport na żądanie jest włączony. Pierwszeństwo: wewnętrzne zastępowanie > zmiennej środowiskowej dostawcy > konfiguracji. Po włączeniu parametru PerRequestSpanProcessor jest używany zamiast klasy BatchSpanProcessor. Token jest przekazywany za pośrednictwem kontekstu OTel (asynchronicznego magazynu lokalnego) w czasie eksportowania.

Normalizuje InputMessagesParam wersję otoki do wersji InputMessages .

• string / string[] → przekonwertowane na ChatMessage[] i opakowane
• InputMessages → zwrócone as-is

Normalizuje OutputMessagesParam wersję otoki do wersji OutputMessages .

• string / string[] → przekonwertowane na OutputMessage[] i opakowane
• OutputMessages → zwrócone as-is

Resetuj do domyślnego rejestratora konsoli (głównie do testowania)

Uruchom funkcję w ramach kontekstu, która przenosi token eksportu dla poszczególnych żądań. Spowoduje to zachowanie tokenu tylko w kontekście OTel (ALS), nigdy w żadnym rejestrze.

Token można zaktualizować później, updateExportToken() zanim ślad zostanie opróżniony — przydatne, gdy wywołanie zwrotne jest długotrwałe, a oryginalny token może wygasnąć przed eksportem.

Wyodrębnia kontekst śledzenia z przychodzących nagłówków HTTP i uruchamia wywołanie zwrotne w tym kontekście. Wszystkie przedziały utworzone wewnątrz wywołania zwrotnego będą nadrzędne do wyodrębnionego śledzenia.

Przykład

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

Uruchamia funkcję wywołania zwrotnego w kontekście, który ma jawne odwołanie zakresu nadrzędnego. Jest to przydatne w przypadku tworzenia zakresów podrzędnych w asynchronicznych wywołaniach zwrotnych, w których propagacja kontekstu jest uszkodzona.

Gwarantuje, że wartość jest zawsze ciągiem analizowalnym w formacie JSON.

• Obiekty są serializowane za pośrednictwem pliku JSON.stringify.
• Ciągi, które są już prawidłowymi obiektami/tablicami JSON, są przekazywane.
• Wszystkie inne ciągi (w tym nagie elementy pierwotne JSON) są opakowane: { [key]: value }.

Serializuje wersję otoki komunikatów w formacie JSON.

Dane wyjściowe to pełny obiekt otoki: {"version":"0.1.0","messages":[...]}.

Funkcja try/catch zapewnia, że rejestrowanie danych telemetrycznych nie jest zgłaszane nawet wtedy, gdy części komunikatów zawierają wartości nieserializowalne w formacie JSON (np. BigInt, odwołania cykliczne).

Ustawianie niestandardowej implementacji rejestratora dla zestawu SDK do obserwacji

Przykład z winstonem:

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

Zaktualizuj token eksportu w aktywnym kontekście OTel. Wywołaj tę metodę, aby odświeżyć token przed zakończeniem zakresu głównego, gdy oryginalny token mógł wygasł podczas długotrwałego żądania.

Musi być wywoływany w tym samym kontekście asynchronicznym utworzonym przez runWithExportTokenprogram .

Udostępniony domyślny dostawca funkcji ObservabilityConfiguration.

Udostępniony domyślny dostawca perRequestSpanProcessorConfiguration.

Domyślne wystąpienie rejestratora pod kątem zgodności z poprzednimi wersjami. Delegaty do globalnego rejestratora, który można zamienić za pomocą setLogger().