@cuylabs/agent-foundry-agentserver-core 4.1.0 → 4.2.0

package/README.md

@@ -8,3 +8,26 @@ sanitization, request correlation IDs, server-version header formatting, and
 standard error envelopes. Protocol packages such as
 `@cuylabs/agent-foundry-agentserver-invocations` build their HTTP surface on top
 of these helpers.
+
+## Observability
+
+Core always creates OpenTelemetry-compatible request spans and installs the
+Node async context manager so protocol handlers can read active baggage. It
+sets the Foundry baggage keys used by the Python host:
+
+```text
+azure.ai.agentserver.invocation_id
+azure.ai.agentserver.session_id
+```
+
+Exporter setup is optional and is driven by the same environment variables used
+by hosted agents:
+
+| Variable | Behavior |
+| --- | --- |
+| `APPLICATIONINSIGHTS_CONNECTION_STRING` | Enables Azure Monitor export through the package's optional `@azure/monitor-opentelemetry` dependency |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Enables OTLP HTTP trace export through the package's optional OpenTelemetry exporter dependencies |
+
+Protocol packages call `configureAgentServerObservability()` by default. Apps
+that already own OpenTelemetry setup can disable package-managed exporter setup
+at the protocol layer and keep the span/baggage helpers.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Span, Context } from '@opentelemetry/api';
+
 interface AgentServerConfig {
     agentName: string;
     agentVersion: string;
@@ -10,15 +12,23 @@ interface AgentServerConfig {
     applicationInsightsConnectionString: string;
     otlpEndpoint: string;
     sseKeepAliveIntervalSeconds: number;
+    gracefulShutdownTimeoutSeconds: number;
+    logLevel: AgentServerLogLevel;
 }
 interface AgentServerConfigOptions {
     env?: NodeJS.ProcessEnv;
     port?: number;
     sseKeepAliveIntervalSeconds?: number;
+    gracefulShutdownTimeoutSeconds?: number;
+    logLevel?: string;
 }
+declare const LOG_LEVELS: readonly ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"];
+type AgentServerLogLevel = (typeof LOG_LEVELS)[number];
 declare function resolveAgentServerConfig(options?: AgentServerConfigOptions): AgentServerConfig;
 declare function resolvePort(explicitPort?: number, env?: NodeJS.ProcessEnv): number;
 declare function resolveSseKeepAliveInterval(explicitInterval?: number, env?: NodeJS.ProcessEnv): number;
+declare function resolveGracefulShutdownTimeout(explicitTimeout?: number): number;
+declare function resolveLogLevel(explicitLevel?: string): AgentServerLogLevel;
 
 interface AgentServerErrorBody {
     error: {
@@ -60,6 +70,22 @@ declare function resolveInvocationIdentity(input: InvocationIdentityInput): Invo
 declare function resolveRequestId(header: HeaderGetter): string;
 declare function sanitizeProtocolId(value: string | undefined, fallback: string): string;
 
+interface AgentServerObservabilityLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+interface AgentServerObservabilityHandle {
+    configured: boolean;
+    exporters: string[];
+    shutdown(): Promise<void>;
+}
+interface ConfigureAgentServerObservabilityOptions {
+    config: AgentServerConfig;
+    logger?: AgentServerObservabilityLogger;
+}
+declare function configureAgentServerObservability(options: ConfigureAgentServerObservabilityOptions): Promise<AgentServerObservabilityHandle>;
+
 interface ServerVersionSegment {
     name: string;
     version: string;
@@ -69,4 +95,55 @@ declare function buildPlatformServerHeader(segments: readonly ServerVersionSegme
 
 declare const AGENTSERVER_CORE_PACKAGE_VERSION: string;
 
-export { AGENTSERVER_CORE_PACKAGE_VERSION, type AgentServerConfig, type AgentServerConfigOptions, type AgentServerErrorBody, CHAT_ISOLATION_HEADER, type HeaderGetter, INVOCATION_ID_HEADER, INVOCATION_ID_HEADERS, type InvocationIdentity, type InvocationIdentityInput, type QueryGetter, REQUEST_ID_HEADER, SESSION_ID_HEADER, SESSION_ID_HEADERS, USER_ISOLATION_HEADER, buildPlatformServerHeader, buildServerVersionSegment, createErrorBody, resolveAgentServerConfig, resolveInvocationIdentity, resolvePort, resolveRequestId, resolveSseKeepAliveInterval, sanitizeProtocolId };
+declare const AGENTSERVER_INVOCATION_ID_BAGGAGE = "azure.ai.agentserver.invocation_id";
+declare const AGENTSERVER_SESSION_ID_BAGGAGE = "azure.ai.agentserver.session_id";
+declare const AGENTSERVER_CONVERSATION_ID_BAGGAGE = "azure.ai.agentserver.conversation_id";
+declare const ATTR_SERVICE_NAME = "service.name";
+declare const ATTR_GEN_AI_SYSTEM = "gen_ai.system";
+declare const ATTR_GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+declare const ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
+declare const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
+declare const ATTR_GEN_AI_AGENT_VERSION = "gen_ai.agent.version";
+declare const ATTR_GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+declare const ATTR_GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+declare const ATTR_GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id";
+declare const ATTR_FOUNDRY_PROJECT_ID = "microsoft.foundry.project.id";
+declare const ATTR_SESSION_ID = "microsoft.session.id";
+declare const ATTR_INVOCATION_ID = "azure.ai.agentserver.invocations.id";
+declare const ATTR_INVOCATIONS_ERROR_CODE = "azure.ai.agentserver.invocations.error.code";
+declare const ATTR_INVOCATIONS_ERROR_MESSAGE = "azure.ai.agentserver.invocations.error.message";
+interface AgentServerRequestSpanOptions {
+    config: Pick<AgentServerConfig, "agentId" | "agentName" | "agentVersion" | "projectArmId">;
+    headers: HeaderGetter;
+    requestId: string;
+    operation: string;
+    operationName?: string;
+    instrumentationScope?: string;
+    invocationId?: string;
+    sessionId?: string;
+    correlationRequestId?: string;
+}
+interface AgentServerRequestSpan {
+    readonly span: Span;
+    readonly context: Context;
+    run<T>(fn: () => T): T;
+    end(error?: unknown): void;
+    recordError(error: unknown, code?: string): void;
+}
+interface AgentServerSpanProcessor {
+    onStart(span: Span, parentContext?: Context): void;
+    onEnd(span: unknown): void;
+    shutdown(): Promise<void> | void;
+    forceFlush(timeoutMillis?: number): Promise<boolean> | boolean;
+}
+declare function startAgentServerRequestSpan(options: AgentServerRequestSpanOptions): AgentServerRequestSpan;
+declare function withAgentServerBaggage(sourceContext: Context, values: {
+    invocationId?: string;
+    sessionId?: string;
+    requestId?: string;
+}): Context;
+declare function recordAgentServerSpanError(span: Span, error: unknown, code?: string): void;
+declare function createFoundryEnrichmentSpanProcessor(config: Pick<AgentServerConfig, "agentId" | "agentName" | "agentVersion" | "projectArmId">): AgentServerSpanProcessor;
+declare function flushSpans(timeoutMillis?: number): void;
+
+export { AGENTSERVER_CONVERSATION_ID_BAGGAGE, AGENTSERVER_CORE_PACKAGE_VERSION, AGENTSERVER_INVOCATION_ID_BAGGAGE, AGENTSERVER_SESSION_ID_BAGGAGE, ATTR_FOUNDRY_PROJECT_ID, ATTR_GEN_AI_AGENT_ID, ATTR_GEN_AI_AGENT_NAME, ATTR_GEN_AI_AGENT_VERSION, ATTR_GEN_AI_CONVERSATION_ID, ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_PROVIDER_NAME, ATTR_GEN_AI_RESPONSE_ID, ATTR_GEN_AI_SYSTEM, ATTR_INVOCATIONS_ERROR_CODE, ATTR_INVOCATIONS_ERROR_MESSAGE, ATTR_INVOCATION_ID, ATTR_SERVICE_NAME, ATTR_SESSION_ID, type AgentServerConfig, type AgentServerConfigOptions, type AgentServerErrorBody, type AgentServerLogLevel, type AgentServerObservabilityHandle, type AgentServerObservabilityLogger, type AgentServerRequestSpan, type AgentServerRequestSpanOptions, type AgentServerSpanProcessor, CHAT_ISOLATION_HEADER, type ConfigureAgentServerObservabilityOptions, type HeaderGetter, INVOCATION_ID_HEADER, INVOCATION_ID_HEADERS, type InvocationIdentity, type InvocationIdentityInput, type QueryGetter, REQUEST_ID_HEADER, SESSION_ID_HEADER, SESSION_ID_HEADERS, USER_ISOLATION_HEADER, buildPlatformServerHeader, buildServerVersionSegment, configureAgentServerObservability, createErrorBody, createFoundryEnrichmentSpanProcessor, flushSpans, recordAgentServerSpanError, resolveAgentServerConfig, resolveGracefulShutdownTimeout, resolveInvocationIdentity, resolveLogLevel, resolvePort, resolveRequestId, resolveSseKeepAliveInterval, sanitizeProtocolId, startAgentServerRequestSpan, withAgentServerBaggage };

package/dist/index.js

@@ -1,6 +1,8 @@
 // src/config.ts
 var DEFAULT_PORT = 8088;
 var DEFAULT_SSE_KEEP_ALIVE_INTERVAL = 0;
+var DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT = 30;
+var LOG_LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"];
 function resolveAgentServerConfig(options = {}) {
   const env = options.env ?? process.env;
   const agentName = env.FOUNDRY_AGENT_NAME ?? "";
@@ -20,7 +22,11 @@ function resolveAgentServerConfig(options = {}) {
     sseKeepAliveIntervalSeconds: resolveSseKeepAliveInterval(
       options.sseKeepAliveIntervalSeconds,
       env
-    )
+    ),
+    gracefulShutdownTimeoutSeconds: resolveGracefulShutdownTimeout(
+      options.gracefulShutdownTimeoutSeconds
+    ),
+    logLevel: resolveLogLevel(options.logLevel)
   };
 }
 function resolvePort(explicitPort, env = process.env) {
@@ -56,6 +62,24 @@ function resolveSseKeepAliveInterval(explicitInterval, env = process.env) {
   }
   return DEFAULT_SSE_KEEP_ALIVE_INTERVAL;
 }
+function resolveGracefulShutdownTimeout(explicitTimeout) {
+  if (explicitTimeout !== void 0) {
+    return Math.max(
+      0,
+      validateInteger(explicitTimeout, "gracefulShutdownTimeoutSeconds")
+    );
+  }
+  return DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT;
+}
+function resolveLogLevel(explicitLevel) {
+  const normalized = (explicitLevel ?? "INFO").trim().toUpperCase();
+  if (!LOG_LEVELS.includes(normalized)) {
+    throw new Error(
+      `Invalid value for logLevel: ${explicitLevel} (expected ${LOG_LEVELS.join(", ")})`
+    );
+  }
+  return normalized;
+}
 function validatePort(value, source) {
   if (!Number.isInteger(value) || value < 1 || value > 65535) {
     throw new Error(`Invalid value for ${source}: ${value} (expected 1-65535)`);
@@ -70,6 +94,14 @@ function validateNonNegativeInteger(value, source) {
   }
   return value;
 }
+function validateInteger(value, source) {
+  if (!Number.isInteger(value)) {
+    throw new Error(
+      `Invalid value for ${source}: ${value} (expected an integer)`
+    );
+  }
+  return value;
+}
 
 // src/errors.ts
 function createErrorBody(code, message, options = {}) {
@@ -160,6 +192,414 @@ function traceIdFromTraceparent(traceparent) {
   return void 0;
 }
 
+// src/tracing.ts
+import {
+  SpanKind,
+  SpanStatusCode,
+  context,
+  propagation,
+  trace
+} from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+var AGENTSERVER_INVOCATION_ID_BAGGAGE = "azure.ai.agentserver.invocation_id";
+var AGENTSERVER_SESSION_ID_BAGGAGE = "azure.ai.agentserver.session_id";
+var AGENTSERVER_CONVERSATION_ID_BAGGAGE = "azure.ai.agentserver.conversation_id";
+var ATTR_SERVICE_NAME = "service.name";
+var ATTR_GEN_AI_SYSTEM = "gen_ai.system";
+var ATTR_GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+var ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
+var ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
+var ATTR_GEN_AI_AGENT_VERSION = "gen_ai.agent.version";
+var ATTR_GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+var ATTR_GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+var ATTR_GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id";
+var ATTR_FOUNDRY_PROJECT_ID = "microsoft.foundry.project.id";
+var ATTR_SESSION_ID = "microsoft.session.id";
+var ATTR_INVOCATION_ID = "azure.ai.agentserver.invocations.id";
+var ATTR_INVOCATIONS_ERROR_CODE = "azure.ai.agentserver.invocations.error.code";
+var ATTR_INVOCATIONS_ERROR_MESSAGE = "azure.ai.agentserver.invocations.error.message";
+var SERVICE_NAME_VALUE = "azure.ai.agentserver";
+var GEN_AI_SYSTEM_VALUE = "azure.ai.agentserver";
+var GEN_AI_PROVIDER_NAME_VALUE = "AzureAI Hosted Agents";
+var contextManagerRegistered = false;
+var headerGetter = {
+  keys: () => ["traceparent", "tracestate", "baggage", "x-request-id"],
+  get: (carrier, key) => carrier(key)
+};
+function startAgentServerRequestSpan(options) {
+  ensureAgentServerContextManager();
+  const config = options.config;
+  const instrumentationScope = options.instrumentationScope ?? "Azure.AI.AgentServer";
+  const operationName = options.operationName ?? options.operation;
+  const spanName = config.agentId ? `${options.operation} ${config.agentId}` : options.operation;
+  const extractedContext = propagation.extract(
+    context.active(),
+    options.headers,
+    headerGetter
+  );
+  const attributes = {
+    [ATTR_SERVICE_NAME]: config.agentName || SERVICE_NAME_VALUE,
+    [ATTR_GEN_AI_SYSTEM]: GEN_AI_SYSTEM_VALUE,
+    [ATTR_GEN_AI_PROVIDER_NAME]: GEN_AI_PROVIDER_NAME_VALUE,
+    [ATTR_GEN_AI_RESPONSE_ID]: options.requestId,
+    [ATTR_GEN_AI_AGENT_ID]: config.agentId,
+    [ATTR_GEN_AI_OPERATION_NAME]: operationName
+  };
+  setAttribute(attributes, ATTR_GEN_AI_AGENT_NAME, config.agentName);
+  setAttribute(attributes, ATTR_GEN_AI_AGENT_VERSION, config.agentVersion);
+  setAttribute(attributes, ATTR_FOUNDRY_PROJECT_ID, config.projectArmId);
+  setAttribute(attributes, ATTR_SESSION_ID, options.sessionId);
+  setAttribute(attributes, ATTR_INVOCATION_ID, options.invocationId);
+  const requestId = options.headers("x-request-id") ?? options.correlationRequestId;
+  setAttribute(attributes, "x_request_id", requestId);
+  const span = trace.getTracer(instrumentationScope).startSpan(
+    spanName,
+    {
+      kind: SpanKind.SERVER,
+      attributes
+    },
+    extractedContext
+  );
+  const spanContext = withAgentServerBaggage(
+    trace.setSpan(extractedContext, span),
+    {
+      invocationId: options.invocationId,
+      sessionId: options.sessionId,
+      requestId
+    }
+  );
+  let ended = false;
+  function recordError(error, code = "internal_error") {
+    recordAgentServerSpanError(span, error, code);
+  }
+  return {
+    span,
+    context: spanContext,
+    run: (fn) => context.with(spanContext, fn),
+    recordError,
+    end(error) {
+      if (ended) {
+        return;
+      }
+      ended = true;
+      if (error !== void 0) {
+        recordError(error);
+      }
+      span.end();
+      flushSpans();
+    }
+  };
+}
+function ensureAgentServerContextManager() {
+  if (contextManagerRegistered) {
+    return;
+  }
+  contextManagerRegistered = true;
+  const manager = new AsyncLocalStorageContextManager().enable();
+  const registered = context.setGlobalContextManager(manager);
+  if (!registered) {
+    manager.disable();
+  }
+}
+function withAgentServerBaggage(sourceContext, values) {
+  let baggage = propagation.getBaggage(sourceContext) ?? propagation.createBaggage();
+  if (values.invocationId) {
+    baggage = baggage.setEntry(AGENTSERVER_INVOCATION_ID_BAGGAGE, {
+      value: values.invocationId
+    });
+  }
+  if (values.sessionId) {
+    baggage = baggage.setEntry(AGENTSERVER_SESSION_ID_BAGGAGE, {
+      value: values.sessionId
+    });
+  }
+  if (values.requestId) {
+    baggage = baggage.setEntry("x_request_id", {
+      value: values.requestId
+    });
+  }
+  return propagation.setBaggage(sourceContext, baggage);
+}
+function recordAgentServerSpanError(span, error, code = "internal_error") {
+  const message = errorMessage(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message
+  });
+  span.setAttribute("error.type", errorType(error));
+  span.setAttribute(ATTR_INVOCATIONS_ERROR_CODE, code);
+  span.setAttribute(ATTR_INVOCATIONS_ERROR_MESSAGE, message);
+  if (error instanceof Error) {
+    span.recordException(error);
+  } else {
+    span.recordException(message);
+  }
+}
+function createFoundryEnrichmentSpanProcessor(config) {
+  return {
+    onStart(span, parentContext) {
+      setSpanAttribute(span, ATTR_FOUNDRY_PROJECT_ID, config.projectArmId);
+      setSpanAttribute(span, ATTR_GEN_AI_AGENT_NAME, config.agentName);
+      setSpanAttribute(span, ATTR_GEN_AI_AGENT_VERSION, config.agentVersion);
+      setSpanAttribute(span, ATTR_GEN_AI_AGENT_ID, config.agentId);
+      const activeBaggage = propagation.getBaggage(
+        parentContext ?? context.active()
+      );
+      setSpanAttribute(
+        span,
+        ATTR_SESSION_ID,
+        activeBaggage?.getEntry(AGENTSERVER_SESSION_ID_BAGGAGE)?.value
+      );
+      setSpanAttribute(
+        span,
+        ATTR_INVOCATION_ID,
+        activeBaggage?.getEntry(AGENTSERVER_INVOCATION_ID_BAGGAGE)?.value
+      );
+      setSpanAttribute(
+        span,
+        ATTR_GEN_AI_CONVERSATION_ID,
+        activeBaggage?.getEntry(AGENTSERVER_CONVERSATION_ID_BAGGAGE)?.value
+      );
+    },
+    onEnd() {
+    },
+    shutdown() {
+    },
+    forceFlush() {
+      return true;
+    }
+  };
+}
+function flushSpans(timeoutMillis = 5e3) {
+  const provider = trace.getTracerProvider();
+  try {
+    void provider.forceFlush?.(timeoutMillis);
+  } catch {
+  }
+}
+function setAttribute(target, key, value) {
+  const normalized = value?.trim();
+  if (normalized) {
+    target[key] = normalized;
+  }
+}
+function setSpanAttribute(span, key, value) {
+  const normalized = value?.trim();
+  if (normalized) {
+    span.setAttribute(key, normalized);
+  }
+}
+function errorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function errorType(error) {
+  if (error instanceof Error) {
+    return error.name || error.constructor.name || "Error";
+  }
+  return typeof error;
+}
+
+// src/observability.ts
+var configuredKey;
+var configuredPromise;
+function configureAgentServerObservability(options) {
+  const key = observabilityKey(options.config);
+  if (!configuredPromise || configuredKey !== key) {
+    configuredKey = key;
+    configuredPromise = configureAgentServerObservabilityOnce(options);
+  }
+  return configuredPromise;
+}
+async function configureAgentServerObservabilityOnce(options) {
+  const logger = options.logger ?? silentLogger;
+  const config = options.config;
+  const exporters = [];
+  const shutdownCallbacks = [];
+  const enrichmentProcessor = createFoundryEnrichmentSpanProcessor(config);
+  const otlpSpanProcessor = await createOtlpSpanProcessor(config, logger);
+  const spanProcessors = [enrichmentProcessor];
+  if (otlpSpanProcessor) {
+    spanProcessors.push(otlpSpanProcessor);
+  }
+  if (config.applicationInsightsConnectionString.trim()) {
+    try {
+      const azureMonitor = await importOptional(
+        "@azure/monitor-opentelemetry"
+      );
+      const azureMonitorOptions = {
+        resource: await createResource(config, logger),
+        azureMonitorExporterOptions: {
+          connectionString: config.applicationInsightsConnectionString.trim()
+        }
+      };
+      if (spanProcessors.length > 0) {
+        azureMonitorOptions.spanProcessors = spanProcessors;
+      }
+      if (otlpSpanProcessor) {
+        exporters.push("otlp");
+      }
+      azureMonitor.useAzureMonitor(azureMonitorOptions);
+      exporters.push("azure-monitor");
+      shutdownCallbacks.push(() => azureMonitor.shutdownAzureMonitor());
+      logger.info("Foundry Agent Server observability configured", {
+        exporters
+      });
+      return makeHandle(exporters, shutdownCallbacks);
+    } catch (error) {
+      logger.warn("Failed to initialize Azure Monitor observability", {
+        error: formatError(error)
+      });
+    }
+  }
+  if (otlpSpanProcessor) {
+    try {
+      const setup2 = await ensureTraceProvider(config, logger, spanProcessors);
+      if (setup2.configured) {
+        exporters.push("otlp");
+      }
+      if (setup2.shutdown) {
+        shutdownCallbacks.push(setup2.shutdown);
+      }
+      logger.info("Foundry Agent Server OTLP observability configured", {
+        exporters
+      });
+      return makeHandle(exporters, shutdownCallbacks, setup2.configured);
+    } catch (error) {
+      logger.warn("Failed to initialize OTLP observability", {
+        error: formatError(error)
+      });
+    }
+  }
+  const setup = await ensureTraceProvider(config, logger, [
+    enrichmentProcessor
+  ]);
+  if (setup.shutdown) {
+    shutdownCallbacks.push(setup.shutdown);
+  }
+  return makeHandle(exporters, shutdownCallbacks, setup.configured);
+}
+async function createOtlpSpanProcessor(config, logger) {
+  const endpoint = config.otlpEndpoint.trim();
+  if (!endpoint) {
+    return void 0;
+  }
+  try {
+    const [{ OTLPTraceExporter }, { BatchSpanProcessor }] = await Promise.all([
+      importOptional(
+        "@opentelemetry/exporter-trace-otlp-http"
+      ),
+      importOptional(
+        "@opentelemetry/sdk-trace-base"
+      )
+    ]);
+    return new BatchSpanProcessor(new OTLPTraceExporter({ url: endpoint }));
+  } catch (error) {
+    logger.warn("Failed to initialize OTLP span processor", {
+      error: formatError(error)
+    });
+    return void 0;
+  }
+}
+async function createResource(config, logger) {
+  const attributes = {
+    "service.name": config.agentName || "azure.ai.agentserver"
+  };
+  if (config.agentVersion) {
+    attributes["service.version"] = config.agentVersion;
+  }
+  if (config.projectArmId) {
+    attributes["microsoft.foundry.project.id"] = config.projectArmId;
+  }
+  try {
+    const resources = await importOptional(
+      "@opentelemetry/resources"
+    );
+    return resources.resourceFromAttributes(attributes);
+  } catch (error) {
+    logger.debug?.("OpenTelemetry resource package unavailable", {
+      error: formatError(error)
+    });
+    return void 0;
+  }
+}
+function makeHandle(exporters, shutdownCallbacks, providerConfigured = exporters.length > 0) {
+  return {
+    configured: providerConfigured,
+    exporters: [...exporters],
+    async shutdown() {
+      await Promise.allSettled(shutdownCallbacks.map((shutdown) => shutdown()));
+    }
+  };
+}
+async function ensureTraceProvider(config, logger, spanProcessors) {
+  try {
+    const api = await importOptional("@opentelemetry/api");
+    const currentProvider = api.trace.getTracerProvider();
+    if (currentProvider.addSpanProcessor) {
+      for (const processor of spanProcessors) {
+        currentProvider.addSpanProcessor(processor);
+      }
+      return { configured: true };
+    }
+  } catch (error) {
+    logger.debug?.("OpenTelemetry API provider inspection failed", {
+      error: formatError(error)
+    });
+  }
+  try {
+    const traceNode = await importOptional(
+      "@opentelemetry/sdk-trace-node"
+    );
+    const provider = new traceNode.NodeTracerProvider({
+      resource: await createResource(config, logger),
+      spanProcessors
+    });
+    provider.register();
+    return {
+      configured: true,
+      shutdown: () => provider.shutdown()
+    };
+  } catch (error) {
+    logger.warn("Failed to initialize local OpenTelemetry tracer provider", {
+      error: formatError(error)
+    });
+    return { configured: false };
+  }
+}
+async function importOptional(specifier) {
+  const dynamicImport = new Function(
+    "specifier",
+    "return import(specifier)"
+  );
+  return await dynamicImport(specifier);
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  return String(error);
+}
+var silentLogger = {
+  info: () => {
+  },
+  warn: () => {
+  }
+};
+function observabilityKey(config) {
+  const appInsights = config.applicationInsightsConnectionString.trim();
+  const otlp = config.otlpEndpoint.trim();
+  return [
+    appInsights,
+    otlp,
+    config.agentName,
+    config.agentVersion,
+    config.projectArmId
+  ].join("|");
+}
+
 // src/server-version.ts
 function buildServerVersionSegment(name, version) {
   if (!name.trim()) {
@@ -184,7 +624,24 @@ function readPackageVersion() {
 }
 var AGENTSERVER_CORE_PACKAGE_VERSION = readPackageVersion();
 export {
+  AGENTSERVER_CONVERSATION_ID_BAGGAGE,
   AGENTSERVER_CORE_PACKAGE_VERSION,
+  AGENTSERVER_INVOCATION_ID_BAGGAGE,
+  AGENTSERVER_SESSION_ID_BAGGAGE,
+  ATTR_FOUNDRY_PROJECT_ID,
+  ATTR_GEN_AI_AGENT_ID,
+  ATTR_GEN_AI_AGENT_NAME,
+  ATTR_GEN_AI_AGENT_VERSION,
+  ATTR_GEN_AI_CONVERSATION_ID,
+  ATTR_GEN_AI_OPERATION_NAME,
+  ATTR_GEN_AI_PROVIDER_NAME,
+  ATTR_GEN_AI_RESPONSE_ID,
+  ATTR_GEN_AI_SYSTEM,
+  ATTR_INVOCATIONS_ERROR_CODE,
+  ATTR_INVOCATIONS_ERROR_MESSAGE,
+  ATTR_INVOCATION_ID,
+  ATTR_SERVICE_NAME,
+  ATTR_SESSION_ID,
   CHAT_ISOLATION_HEADER,
   INVOCATION_ID_HEADER,
   INVOCATION_ID_HEADERS,
@@ -194,11 +651,19 @@ export {
   USER_ISOLATION_HEADER,
   buildPlatformServerHeader,
   buildServerVersionSegment,
+  configureAgentServerObservability,
   createErrorBody,
+  createFoundryEnrichmentSpanProcessor,
+  flushSpans,
+  recordAgentServerSpanError,
   resolveAgentServerConfig,
+  resolveGracefulShutdownTimeout,
   resolveInvocationIdentity,
+  resolveLogLevel,
   resolvePort,
   resolveRequestId,
   resolveSseKeepAliveInterval,
-  sanitizeProtocolId
+  sanitizeProtocolId,
+  startAgentServerRequestSpan,
+  withAgentServerBaggage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-foundry-agentserver-core",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Shared TypeScript host utilities for Foundry Agent Server protocol packages",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,17 @@
     "dist",
     "README.md"
   ],
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.6.0"
+  },
+  "optionalDependencies": {
+    "@azure/monitor-opentelemetry": "^1.16.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",