@microsoft/agents-a365-observability

OpenTelemetry-based observability and tracing for Microsoft Agents A365 applications. This package provides comprehensive monitoring capabilities for agent invocations, tool executions, and AI model inference calls with seamless Azure Monitor integration.

Installation

npm install @microsoft/agents-a365-observability

Usage

For detailed usage examples and implementation guidance, see the Microsoft Agent 365 Observability Documentation.

OBS endpoint

All exports use /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1, including batch and per-request exports from AI Teammate and OBO workloads. The exporter never falls back to /observability. The useS2SEndpoint option is deprecated and ignored, including when set to false; domain overrides change the host, not this route.

Endpoint selection does not acquire or convert tokens. Supply an app-only OBS resolver for the exporting tenant and agent identity. Eligible Agent 365-registered instances can use roleless app tokens when service policy permits; an Agent365.Observability.OtelWrite grant is not a universal prerequisite. The S2S service rejects delegated (scp) tokens, including AI Teammate user tokens. Keep workload authentication (such as OBO for MCP or Microsoft Graph) separate from OBS authentication. An authorization failure is not a reason to retry telemetry on the OBO route.

When using the hosting token cache, call RefreshObservabilityToken(agentId, tenantId, appOnlyTokenResolver). It throws when the resolver fails or returns no token, so call it from your exporter tokenResolver or wrap it in try/catch on the request path. The TurnContext/Authorization overload was removed in 2.0.0; JavaScript callers that still pass it get a one-time error log and no token. S2S ingestion may remove unverified user attribution; routing a workload through S2S does not establish that its caller identity is trusted.

Migrating per-request authentication

Batch and per-request exports both call the configured tokenResolver with the exporting agent and tenant IDs. Configure it with withTokenResolver(...) or exporterOptions.tokenResolver; both also work through ObservabilityManager.start(options), and withTokenResolver/tokenResolver takes precedence. The callback must acquire or refresh an app-only OBS token independently of workload authentication.

import { ObservabilityManager, type TokenResolver } from '@microsoft/agents-a365-observability';

function startObservability(resolveAppOnlyObsToken: TokenResolver): void {
  ObservabilityManager.configure(builder => {
    builder.withService('my-agent').withTokenResolver(resolveAppOnlyObsToken);
  }).start();
}

Enabling ENABLE_A365_OBSERVABILITY_PER_REQUEST_EXPORT changes span buffering, not credential selection. runWithExportToken, updateExportToken, and getExportToken remain available for custom export integrations, but Agent365Exporter never uses their context token, even when it looks app-only. Existing callers must provide the OBS resolver instead of relying on a workload token in context.

Resolvers must cache. The exporter invokes the resolver on every export batch, and once per identity group when spans partition across tenants or agents. In per-request mode that is roughly one call per request. Resolvers should cache the acquired app-only token and refresh only as it approaches expiry. AgenticTokenCache in @microsoft/agents-a365-observability-hosting implements this pattern; the sample observability-token-service.ts files show a minimal single-identity variant.

An enabled Agent 365 exporter without a resolver fails configuration. A resolver failure or empty token fails export without an HTTP request or delegated fallback. Console-only configuration does not require an OBS resolver.

Support

For issues, questions, or feedback:

• File issues in the GitHub Issues section
• See the main documentation for more information

Trademarks

Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

License

Copyright (c) Microsoft Corporation. All rights reserved.

Licensed under the MIT License - see the LICENSE file for details