@cuylabs/agent-azure-monitor

Azure Monitor Application Insights observability adapter for @cuylabs/agent-core.

Use this package when you want the portable OpenTelemetry spans from agent-core and AI SDK v7 to land in Azure Monitor Application Insights. It does not replace the Azure SDK; it initializes @azure/monitor-opentelemetry with agent-oriented defaults and returns tracing metadata for agent-core.

This is separate from @cuylabs/agent-a365-observability:

• agent-azure-monitor sends traces to Azure Monitor/Application Insights.
• agent-a365-observability sends Agent 365 observability/compliance telemetry through the Microsoft Agent 365 exporter and baggage contract.

Install

pnpm add @cuylabs/agent-core @cuylabs/agent-azure-monitor @azure/monitor-opentelemetry @opentelemetry/resources

Recommended Startup

Import the register module before importing your app or agent code. This matches Azure Monitor's Node.js guidance: the distro should initialize before other libraries so automatic instrumentation can attach cleanly.

import "@cuylabs/agent-azure-monitor/register";
import { createAgent } from "@cuylabs/agent-core";
import { createAzureMonitorTracingConfig } from "@cuylabs/agent-azure-monitor";
import { openai } from "@ai-sdk/openai";

const agent = createAgent({
  name: "support-agent",
  model: openai("gpt-4o-mini"),
  tracing: createAzureMonitorTracingConfig({
    agentId: "support-agent-prod",
    agentDescription: "Answers support questions",
    agentVersion: "1.0.0",
  }),
});

Required environment:

APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=...;IngestionEndpoint=..."
OTEL_SERVICE_NAME="support-agent-service"
OTEL_SERVICE_NAMESPACE="cuylabs"
OTEL_SERVICE_INSTANCE_ID="local-dev"

Optional sampling environment:

AZURE_MONITOR_SAMPLING_RATIO=0.1
AZURE_MONITOR_TRACES_PER_SECOND=1.5

Azure Monitor also supports standard OpenTelemetry sampling environment variables such as OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG.

Programmatic Startup

Use this form when your host owns startup order and can call initialization before creating agents.

import { createAgent } from "@cuylabs/agent-core";
import {
  createAzureMonitorTracingConfig,
  initAzureMonitorObservability,
} from "@cuylabs/agent-azure-monitor";

const monitor = await initAzureMonitorObservability({
  connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
  resource: {
    serviceName: "support-agent-service",
    serviceNamespace: "cuylabs",
    serviceInstanceId: process.env.HOSTNAME,
  },
  tracesPerSecond: 1.5,
});

const agent = createAgent({
  name: "support-agent",
  model,
  tracing: createAzureMonitorTracingConfig({
    agentId: "support-agent-prod",
    agentDescription: "Answers support questions",
    agentVersion: "1.0.0",
  }),
});

try {
  for await (const event of agent.chat("session-1", "Hello")) {
    // stream events to the caller
  }
} finally {
  await agent.close();
  await monitor.shutdown();
}

What Gets Exported

agent-core emits:

• invoke_agent {agent} spans with gen_ai.operation.name=invoke_agent
• execute_tool {tool} spans with gen_ai.operation.name=execute_tool
• AI SDK v7 model spans from @ai-sdk/otel with GenAI model/provider/token attributes

This package starts the Azure Monitor OpenTelemetry distro so those spans flow to Application Insights. It does not replace Agent 365 observability; the two adapters can be composed when you need both App Insights APM and Agent 365 admin/security/compliance telemetry.