@microsoft/agents-a365-observability package

Options controlling the behavior of the Agent365 OpenTelemetry span exporter.

These values tune batching, timeouts, token acquisition and endpoint shape. All properties have sensible defaults so callers can usually construct without arguments and override selectively.

Provides OpenTelemetry tracing scope for security guardrail evaluation operations.

Describes a security guardian evaluation. Multiple guardian spans MAY exist under a single operation span if multiple guardians are chained.

Guardian spans SHOULD be children of the operation span they are protecting (e.g., inference or execute_tool spans).

Per request baggage builder for OpenTelemetry context propagation.

This class provides a fluent API for setting baggage values that will be propagated in the OpenTelemetry context.

Example

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

Context manager for baggage scope.

This class manages the lifecycle of baggage values, setting them on enter and restoring the previous context on exit.

Builder for configuring Agent 365 with OpenTelemetry tracing

Provides OpenTelemetry tracing scope for AI tool execution operations.

Provides OpenTelemetry tracing scope for generative AI inference operations.

Provides OpenTelemetry tracing scope for AI agent invocation operations.

Configuration for observability package. Inherits runtime settings and adds observability-specific settings.

Main entry point for Agent 365 providing OpenTelemetry tracing for AI agents and tools

OpenTelemetry constants for Agent 365

Base class for OpenTelemetry tracing scopes

Provides OpenTelemetry tracing scope for output message tracing with parent span linking.

Configuration for PerRequestSpanProcessor. Inherits runtime settings (clusterCategory, isNodeEnvDevelopment) and adds per-request processor guardrails.

This is separated from ObservabilityConfiguration because PerRequestSpanProcessor is used only in specific scenarios and these settings should not be exposed in the common ObservabilityConfiguration.

Details about an AI agent

Inline binary data (base64-encoded).

Configuration options for Agent 365 Observability Builder

Caller details for scope creation. Supports human callers, agent callers, or both (A2A with a human in the chain).

Migration note: In v1 the name CallerDetails referred to human caller identity (now UserDetails). In v2 it was repurposed as a wrapper that groups both human and agent caller information.

See UserDetails — human caller identity (previously CallerDetails) See CHANGELOG.md — breaking changes section for migration guidance

Represents channel for an invocation

An input message sent to a model (OTEL gen-ai semantic conventions).

Reference to a pre-uploaded file.

Extensible part for custom / future types.

Extensible server tool call details with a type discriminator.

Extensible server tool call response with a type discriminator.

Details of a guardrail evaluation for security operations tracing.

Represents a single security finding detected during guardian evaluation. Multiple findings may be emitted for a single guardrail span.

Custom logger interface for Agent 365 observability Implement this interface to support logging backends

Details for an inference call

Details for recording the response from an inference call

Details for invoking agent scope.

An output message produced by a model (OTEL gen-ai semantic conventions). finish_reason defaults to "stop" per OTel spec when not provided.

Represents a response containing output messages from an agent. Used with OutputScope for output message tracing. Accepts plain strings, structured OTEL OutputMessage objects, or a raw dict (treated as a tool call result per OTEL spec).

Reference to a parent span for explicit parent-child linking across async boundaries. Used when automatic context propagation fails (e.g., WebSocket callbacks, external event handlers).

Model reasoning / chain-of-thought content.

Represents a request with telemetry context. Used across all scope types for channel and conversation tracking.

Server-side tool invocation.

Server-side tool response.

Represents an endpoint for agent invocation

Span configuration details for scope creation. Groups OpenTelemetry span options into a single object so the scope method signature remains stable as new options are added.

Plain text content.

Details of a tool call made by an agent

A tool call requested by the model.

Result of a tool call.

External URI reference.

Details about the human user caller.

Carrier type for HTTP headers used in trace context propagation. Compatible with Node.js IncomingHttpHeaders and plain string maps.

Accepted input for recordInputMessages. Supports a single string, an array of strings (backward compat), or the structured wrapper.

Union of all message part types per OTEL gen-ai semantic conventions.

Note: GenericPart acts as a catch-all for forward compatibility with custom or future part types. Because its type is string (not a literal), exhaustive switch/case on part.type will not produce compile-time errors for unhandled cases.

Observability configuration options - extends runtime options. All overrides are functions called on each property access.

Inherited from RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Note: isDevelopmentEnvironment is a derived getter on the configuration class (based on clusterCategory), not an overridable option.

Accepted input for recordOutputMessages. Supports a single string, an array of strings (backward compat), or the structured wrapper.

A parent context for span creation. Accepts either:

• ParentSpanRef: explicit traceId/spanId pair (manual approach)
• ParentContext: an OTel Context, typically from extractContextFromHeaders or propagation.extract()

Configuration options for PerRequestSpanProcessor - extends runtime options. All overrides are functions called on each property access.

Inherited from RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Accepted input for OutputResponse.messages. Supports plain strings, structured OutputMessages, or a raw dict (treated as a tool call result per OTEL spec and serialized directly via JSON.stringify).

A function that resolves an app-only OBS token for the given agent and tenant. Delegated (scp) tokens are not accepted by the S2S service. Implementations may perform synchronous lookup (e.g., in-memory cache) or asynchronous network calls. Used in both batch and per-request modes, independently of workload token context. Return null if a token cannot be provided; export fails without sending an HTTP request.

Event names used by Agent365Exporter for logging and monitoring. These are low-cardinality event types to ensure efficient monitoring and aggregation.

Reason a model stopped generating per OTEL gen-ai semantic conventions.

The decision made by a security guardian during guardrail evaluation.

Represents different operation for types for model inference

Represents different roles that can invoke an agent

Role of a message participant per OTEL gen-ai semantic conventions.

Media modality for blob, file, and URI parts.

Creates a new Context with an explicit parent span reference. This allows child spans to be correctly parented even when async context is broken.

Extracts trace context from incoming HTTP headers using the globally registered W3C propagator. Returns an OTel ParentContext that can be passed to scope classes as a ParentContext.

Example

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

Format error object for logging with message and stack trace

Retrieve the per-request export token from a given OTel Context (or the active one).

Get the current logger instance

Injects the current trace context (traceparent/tracestate headers) into the provided headers object using the globally registered W3C propagator.

Example

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

Check if per-request export is enabled. Precedence: internal overrides > configuration provider > environment variable. When enabled, the PerRequestSpanProcessor is used instead of BatchSpanProcessor. Credential selection is unchanged: Agent365Exporter uses its app-only token resolver.

Normalizes an InputMessagesParam to an InputMessages instance.

• string / string[] → converted to ChatMessage[] and wrapped
• InputMessages → returned as-is

Normalizes an OutputMessagesParam to an OutputMessages instance.

• string / string[] → converted to OutputMessage[] and wrapped
• OutputMessages → returned as-is

Reset to the default console logger (mainly for testing)

Run a function within a Context that carries the per-request export token. This keeps the token only in OTel Context (ALS), never in any registry. These helpers remain available for custom export integrations. Agent365Exporter does not consume this token; configure its app-only tokenResolver in every mode.

The token can be updated later via updateExportToken() before the trace is flushed — useful when the callback is long-running and the original token may expire before export.

Extracts trace context from incoming HTTP headers and runs the callback within that context. Any spans created inside the callback will be parented to the extracted trace.

Example

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

Runs a callback function within a context that has an explicit parent span reference. This is useful for creating child spans in async callbacks where context propagation is broken.

Ensures the value is always a JSON-parseable string.

• Objects are serialized via JSON.stringify.
• Strings that are already valid JSON objects/arrays are passed through.
• All other strings (including bare JSON primitives) are wrapped: { [key]: value }.

Serializes a message wrapper to JSON.

The output is a plain JSON array per OTel gen-ai semantic conventions: [{...}, ...].

The try/catch ensures telemetry recording is non-throwing even when message parts contain non-JSON-serializable values (e.g. BigInt, circular refs).

Set a custom logger implementation for the observability SDK

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

Update the export token in the active OTel Context. Call this to refresh the token before ending the root span when the original token may have expired during a long-running request.

Must be called within the same async context created by runWithExportToken.

Default finish reason applied when none is provided (per OTel spec).

Well-known severity levels for security risks detected by guardrails.

Well-known values for the type of content or action a guardrail is applied to. Custom strings are also accepted.

Shared default provider for ObservabilityConfiguration.

Shared default provider for PerRequestSpanProcessorConfiguration.

Default logger instance for backward compatibility. Delegates to the global logger which can be replaced via setLogger().