@cuylabs/agent-microsoft-opentelemetry

Microsoft OpenTelemetry distro adapter for @cuylabs/agent-core.

This package is the long-term Microsoft observability integration for agents-ts. It uses @microsoft/opentelemetry underneath instead of the older Agent 365 package family. The existing @cuylabs/agent-a365-observability package remains available for apps that are already on the legacy Microsoft Agent 365 SDK path.

Why This Package Exists

Microsoft now publishes a consolidated OpenTelemetry distro at @microsoft/opentelemetry. The distro owns the Microsoft OpenTelemetry provider setup, Agent 365 exporter, Agent 365 baggage processor, Azure Monitor exporter, OTLP support, and supported Microsoft framework auto-instrumentation.

@cuylabs/agent-core owns the agent runtime, but Agent 365 has product-specific scope types for invocation, inference, tools, and output. This package bridges those two models: it starts official Microsoft A365 scopes from agent-core lifecycle events, runs turns with Agent 365 baggage, provides S2S token resolution, and lets the Microsoft distro export the resulting spans.

Install

pnpm add @cuylabs/agent-microsoft-opentelemetry @microsoft/opentelemetry

Basic Agent 365 S2S Setup

import {
  createMicrosoftA365ObservedTurnSource,
  createMicrosoftA365S2STokenResolverFromEnv,
  createMicrosoftOpenTelemetryTracingConfig,
  initMicrosoftOpenTelemetry,
} from "@cuylabs/agent-microsoft-opentelemetry";

const observability = await initMicrosoftOpenTelemetry({
  resource: {
    serviceName: "cdo-ai-companion",
    serviceVersion: "1.0.0",
  },
  a365: {
    enabled: true,
    enableObservabilityExporter: true,
    useS2SEndpoint: true,
    tokenResolver: createMicrosoftA365S2STokenResolverFromEnv(),
  },
  azureMonitor: {
    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
  },
  instrumentationProfile: "agent-core",
  agent: {
    agentId: process.env.A365_OBSERVABILITY_AGENT_ID,
    agentDescription: process.env.A365_OBSERVABILITY_AGENT_DESCRIPTION,
    recordInputs: true,
    recordOutputs: true,
  },
});

Pass observability.tracing to createAgent({ tracing }). By default that tracing config installs the package's official A365 scope middleware:

• InvokeAgentScope starts when the agent turn starts.
• InferenceScope starts around each model step.
• ExecuteToolScope starts for each agent-core tool call event.
• OutputScope is emitted at turn completion.

Wrap channel turn sources with createMicrosoftA365ObservedTurnSource() so each turn runs with Agent 365 baggage, including tenant, agent, user, channel, conversation, and session attributes.

Environment Compatibility

The S2S helpers understand the Agent 365 CLI-generated settings:

| Variable | Purpose | | --------------------------------------------------------------------------- | --------------------------------------------------------------- | | A365_OBSERVABILITY_TENANT_ID or agent365Observability__tenantId | Tenant that owns the Agent 365 identity. | | A365_OBSERVABILITY_AGENT_ID or agent365Observability__agentId | Agent 365 agent identity service principal ID. | | A365_OBSERVABILITY_CLIENT_ID or agent365Observability__clientId | Blueprint application/client ID. | | A365_OBSERVABILITY_CLIENT_SECRET or agent365Observability__clientSecret | Blueprint client secret. Store this in Key Vault in production. | | ENABLE_A365_OBSERVABILITY_EXPORTER | Enables export to Agent 365. | | A365_OBSERVABILITY_USE_S2S_ENDPOINT | Uses the S2S Agent 365 ingestion path. | | A365_OBSERVABILITY_LOG_LEVEL | Microsoft distro Agent 365 log level. |

The package also accepts standard OpenTelemetry resource variables such as OTEL_SERVICE_NAME and OTEL_SERVICE_VERSION.

Microsoft distro-owned variables such as A365_OBSERVABILITY_SCOPES_OVERRIDE, A365_PER_REQUEST_MAX_TRACES, and standard OTEL_EXPORTER_OTLP_* variables are intentionally left as process environment pass-throughs. The adapter only normalizes values it needs for agents-ts startup and S2S token resolution.

Early Registration

The Microsoft distro recommends initialization as early as possible so automatic instrumentation can patch supported libraries before they are loaded. For ESM apps, use this package's loader entry point. It imports @microsoft/opentelemetry/loader first, then runs this package's environment-driven registration:

node --import @cuylabs/agent-microsoft-opentelemetry/loader dist/server.js

If the host already imports @microsoft/opentelemetry/loader separately, use the register entry point instead:

node --import @microsoft/opentelemetry/loader \
  --import @cuylabs/agent-microsoft-opentelemetry/register \
  dist/server.js

Set CUYLABS_MICROSOFT_OPENTELEMETRY_DISABLED=true to disable the adapter initialization without changing the command line.

Instrumentation Profile

The adapter is agent-core first. Its default profile is agent-core, which keeps Microsoft exporters and processors active while disabling Microsoft's optional OpenAI Agents SDK and LangChain auto-instrumentations. agent-core execution is represented through the adapter's official A365 scope middleware.

Use instrumentationProfile: "microsoft-genai" only when the same Node process also runs Microsoft's supported OpenAI Agents SDK or LangChain integrations. Use full-stack when Azure Monitor or OTLP should also receive infrastructure telemetry such as HTTP, Azure SDK, database, Redis, Bunyan, or Winston spans. Use microsoft-default only when you intentionally want the official distro's native instrumentation defaults without adapter opinions.

Microsoft Hosting Middleware

Apps built on Microsoft Agent Hosting compatible adapters can register the official A365 hosting middleware through this adapter:

import { configureMicrosoftA365Hosting } from "@cuylabs/agent-microsoft-opentelemetry";

await configureMicrosoftA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: true,
});

enableBaggage matches Microsoft's BaggageMiddleware. enableOutputLogging matches Microsoft's OutputLoggingMiddleware and can record outgoing message content on spans, so keep it explicit in production code. Non-Microsoft channel adapters should use createMicrosoftA365ObservedTurnSource() instead.

Package Boundary

This package does not replace agent-core execution. Instead:

• agent-core runs the turn, model loop, tools, approvals, and event stream.
• This package converts those lifecycle hooks into official A365 scopes.
• @microsoft/opentelemetry owns the provider, span processors, exporters, Azure Monitor, OTLP, and Agent 365 HTTP exporter.

The default tracing config disables agent-core's older generic OTel middleware and the local AI SDK GenAI integration so one agents-ts turn produces one official A365 scope tree. Applications can opt back into those lower-level spans with useA365Scopes: false, useDefaultOtelMiddleware: true, or useGenAIOpenTelemetry: true, but those settings should be deliberate because they can duplicate tool or model telemetry.

Source Layout

The source tree mirrors the adapter's ownership boundaries, not the full Microsoft distro implementation:

| Folder | Owns | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | src/a365 | Agent 365 request context, baggage attributes, official scope middleware, and turn-source wrappers. | | src/auth | S2S token exchange and Agent 365 CLI environment compatibility. | | src/runtime | Microsoft distro startup, loader integration, destination helpers, instrumentation profiles, and exporter options. | | src/tracing | agent-core tracing defaults for Microsoft-backed pipelines. | | src/common and src/internal | Shared public types and package-private utilities. |

For details, see docs/architecture.md. For a direct mapping to Microsoft's distro documentation, see docs/distro-alignment.md. For exporter destinations and auto-instrumentation guidance, see docs/destinations-and-instrumentation.md.