@amitdeshmukh/ax-crew 6.0.0 → 7.0.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [7.0.0] - 2025-12-27
+
+### Breaking
+- Change to `AxCrewConfig` interface
+
+### Added
+- Optional OpenTelemetry telemetry support for distributed tracing and metrics collection
+- New `AxCrewOptions` interface with `telemetry` field accepting `tracer` and `meter` instances
+- Automatic instrumentation of agent execution, function calls, and token metrics when telemetry is enabled
+- Support for multiple OpenTelemetry exporters (console, Jaeger, Prometheus, etc.)
+- Complete telemetry example in `examples/telemetry-demo.ts` demonstrating setup with console and Jaeger exporters
+- Comprehensive telemetry documentation in README with setup instructions, best practices, and examples
+- Test coverage for telemetry functionality in `tests/telemetry.test.ts`
+
+### Changed
+- AxCrew constructor now accepts optional fourth parameter `options` of type `AxCrewOptions` for telemetry configuration
+- Enhanced agent initialization to pass telemetry context to underlying agents
+
 ## [6.0.0] - 2025-10-22
 
 ### Breaking

package/README.md

@@ -1,5 +1,7 @@
 ![image](axcrew.png)
 
+[![npm version](https://img.shields.io/npm/v/@amitdeshmukh/ax-crew.svg)](https://www.npmjs.com/package/@amitdeshmukh/ax-crew) [![npm downloads](https://img.shields.io/npm/dm/@amitdeshmukh/ax-crew.svg)](https://www.npmjs.com/package/@amitdeshmukh/ax-crew)
+
 ### AxCrew — build a crew of AI agents with shared state (powered by AxLLM)
 
 AxCrew lets you define a team of AI agents in config and run them together with shared state, tools, streaming, MCP, and built‑in metrics/cost tracking. Bring your own functions or use the provided registry.
@@ -715,6 +717,140 @@ Notes:
 - Legacy cost APIs (`getLastUsageCost`, `getAccumulatedCosts`, `getAggregatedCosts`) are superseded by metrics methods.
 - Estimated cost values are numbers rounded to 5 decimal places.
 
+### Telemetry Support (OpenTelemetry)
+
+AxCrew provides optional OpenTelemetry integration for comprehensive observability. You can pass custom tracer and meter instances to monitor agent operations, track performance, and analyze behavior across your crew.
+
+#### Features
+
+- **Distributed Tracing**: Track agent execution flows, function calls, and dependencies
+- **Metrics Collection**: Monitor token usage, costs, latency, and error rates
+- **Multiple Exporters**: Support for console, Jaeger, Prometheus, and other OpenTelemetry backends
+
+#### Setup
+
+Install OpenTelemetry dependencies:
+
+```bash
+npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics
+```
+
+Optional: Install exporters for enhanced visualization:
+
+```bash
+# For Jaeger tracing UI
+npm install @opentelemetry/exporter-jaeger
+
+# For Prometheus metrics
+npm install @opentelemetry/exporter-prometheus
+```
+
+#### Basic Configuration
+
+```typescript
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import { trace, metrics } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { MeterProvider } from '@opentelemetry/sdk-metrics';
+import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+// Initialize OpenTelemetry
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())]
+});
+tracerProvider.register();
+
+const meterProvider = new MeterProvider();
+metrics.setGlobalMeterProvider(meterProvider);
+
+// Get tracer and meter instances
+const tracer = trace.getTracer('my-app');
+const meter = metrics.getMeter('my-app');
+
+// Pass to AxCrew
+const crew = new AxCrew(
+  config,
+  AxCrewFunctions,
+  undefined,
+  {
+    telemetry: {
+      tracer,
+      meter
+    }
+  }
+);
+```
+
+#### What Gets Traced
+
+When telemetry is enabled, AxCrew automatically instruments:
+
+- **Agent Execution**: Each agent's `forward()` call creates a span with timing and metadata
+- **Function Calls**: Tool/function invocations are traced with parameters and results
+- **Provider Information**: Model name, provider, and configuration details
+- **Token Metrics**: Input/output tokens and estimated costs
+- **Errors**: Exceptions and failures are captured with full context
+
+#### Advanced Configuration with Jaeger
+
+For enhanced visualization, you can export traces to Jaeger:
+
+```typescript
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors: [
+    new SimpleSpanProcessor(new ConsoleSpanExporter()),
+    new SimpleSpanProcessor(new JaegerExporter({
+      endpoint: 'http://localhost:14268/api/traces'
+    }))
+  ]
+});
+tracerProvider.register();
+
+// ... rest of setup
+```
+
+Start Jaeger with Docker:
+
+```bash
+docker run -d --name jaeger \
+  -p 16686:16686 \
+  -p 14268:14268 \
+  jaegertracing/all-in-one:latest
+```
+
+View traces at: http://localhost:16686
+
+#### Complete Example
+
+See [examples/telemetry-demo.ts](examples/telemetry-demo.ts) for a full working example that demonstrates:
+
+- Setting up OpenTelemetry with console and Jaeger exporters
+- Configuring multiple agents with different providers
+- Running a multi-step workflow with telemetry tracking
+- Viewing traces and metrics in the console and Jaeger UI
+
+Run the example:
+
+```bash
+# With console output only
+npm run dev examples/telemetry-demo.ts
+
+# With Jaeger (start Jaeger first)
+docker run -d --name jaeger -p 16686:16686 -p 14268:14268 jaegertracing/all-in-one:latest
+npm run dev examples/telemetry-demo.ts
+# Open http://localhost:16686 to view traces
+```
+
+#### Best Practices
+
+1. **Production Setup**: Use appropriate exporters for your infrastructure (Jaeger, Zipkin, Cloud providers)
+2. **Sampling**: Configure sampling strategies to control trace volume in production
+3. **Context Propagation**: OpenTelemetry automatically propagates trace context across agent calls
+4. **Custom Attributes**: Extend traces with custom attributes specific to your use case
+5. **Performance**: Telemetry adds minimal overhead when properly configured
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version updates.

package/dist/agents/agentConfig.d.ts

@@ -1,6 +1,6 @@
 import { AxDefaultCostTracker } from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
-import type { AgentConfig, AxCrewConfig, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreamableHTTPTransportConfig } from '../types.js';
+import type { AgentConfig, AxCrewConfig, AxCrewOptions, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreamableHTTPTransportConfig } from '../types.js';
 export declare function isStdioTransport(config: MCPTransportConfig): config is MCPStdioTransportConfig;
 export declare function isHTTPSSETransport(config: MCPTransportConfig): config is MCPHTTPSSETransportConfig;
 export declare function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreamableHTTPTransportConfig;
@@ -25,7 +25,7 @@ declare const parseCrewConfig: (input: AxCrewConfig) => {
  * @throws {Error} Throws an error if the agent configuration is missing, the provider is unsupported,
  * the API key is not found, or the provider key name is not specified in the configuration.
  */
-declare const parseAgentConfig: (agentName: string, crewConfig: AxCrewConfig, functions: FunctionRegistryType, state: Record<string, any>) => Promise<{
+declare const parseAgentConfig: (agentName: string, crewConfig: AxCrewConfig, functions: FunctionRegistryType, state: Record<string, any>, options?: AxCrewOptions) => Promise<{
     ai: import("@ax-llm/ax").AxAI<string>;
     name: string;
     description: string;

package/dist/agents/agentConfig.js

@@ -88,7 +88,7 @@ const parseCrewConfig = (input) => {
  * @throws {Error} Throws an error if the agent configuration is missing, the provider is unsupported,
  * the API key is not found, or the provider key name is not specified in the configuration.
  */
-const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
+const parseAgentConfig = async (agentName, crewConfig, functions, state, options) => {
     try {
         // Retrieve the parameters for the specified AI agent from config
         const agentConfigData = parseCrewConfig(crewConfig).crew.find(agent => agent.name === agentName);
@@ -121,7 +121,10 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
                 debug: agentConfigData.debug || false,
                 ...agentConfigData.options,
                 // Attach default cost tracker so usage/costs are recorded by provider layer
-                trackers: [costTracker]
+                trackers: [costTracker],
+                // Inject telemetry if provided
+                tracer: options?.telemetry?.tracer,
+                meter: options?.telemetry?.meter
             }
         };
         if (agentConfigData.apiURL) {

package/dist/agents/index.d.ts

@@ -1,6 +1,6 @@
 import { AxAgent, AxAI } from "@ax-llm/ax";
 import type { AxSignature, AxAgentic, AxFunction, AxProgramForwardOptions, AxProgramStreamingForwardOptions, AxGenStreamingOut } from "@ax-llm/ax";
-import type { StateInstance, FunctionRegistryType, UsageCost, AxCrewConfig, MCPTransportConfig } from "../types.js";
+import type { StateInstance, FunctionRegistryType, UsageCost, AxCrewConfig, AxCrewOptions, MCPTransportConfig } from "../types.js";
 declare class StatefulAxAgent extends AxAgent<any, any> {
     state: StateInstance;
     axai: any;
@@ -59,6 +59,7 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
  */
 declare class AxCrew {
     private crewConfig;
+    private options?;
     functionsRegistry: FunctionRegistryType;
     crewId: string;
     agents: Map<string, StatefulAxAgent> | null;
@@ -67,9 +68,10 @@ declare class AxCrew {
      * Creates an instance of AxCrew.
      * @param {AxCrewConfig} crewConfig - JSON object with crew configuration.
      * @param {FunctionRegistryType} [functionsRegistry={}] - The registry of functions to use in the crew.
+     * @param {AxCrewOptions} [options] - Optional settings for the crew (e.g., telemetry).
      * @param {string} [crewId=uuidv4()] - The unique identifier for the crew.
      */
-    constructor(crewConfig: AxCrewConfig, functionsRegistry?: FunctionRegistryType, crewId?: string);
+    constructor(crewConfig: AxCrewConfig, functionsRegistry?: FunctionRegistryType, options?: AxCrewOptions, crewId?: string);
     /**
      * Factory function for creating an agent.
      * @param {string} agentName - The name of the agent to create.

package/dist/agents/index.js

@@ -196,6 +196,7 @@ class StatefulAxAgent extends AxAgent {
  */
 class AxCrew {
     crewConfig;
+    options;
     functionsRegistry = {};
     crewId;
     agents;
@@ -204,9 +205,10 @@ class AxCrew {
      * Creates an instance of AxCrew.
      * @param {AxCrewConfig} crewConfig - JSON object with crew configuration.
      * @param {FunctionRegistryType} [functionsRegistry={}] - The registry of functions to use in the crew.
+     * @param {AxCrewOptions} [options] - Optional settings for the crew (e.g., telemetry).
      * @param {string} [crewId=uuidv4()] - The unique identifier for the crew.
      */
-    constructor(crewConfig, functionsRegistry = {}, crewId = uuidv4()) {
+    constructor(crewConfig, functionsRegistry = {}, options, crewId = uuidv4()) {
         // Basic validation of crew configuration
         if (!crewConfig || typeof crewConfig !== 'object' || !('crew' in crewConfig)) {
             throw new Error('Invalid crew configuration');
@@ -220,6 +222,7 @@ class AxCrew {
         this.crewConfig = crewConfig;
         this.functionsRegistry = functionsRegistry;
         this.crewId = crewId;
+        this.options = options;
         this.agents = new Map();
         this.state = createState(crewId);
         // Make crewId discoverable to metrics
@@ -233,7 +236,7 @@ class AxCrew {
      */
     createAgent = async (agentName) => {
         try {
-            const agentConfig = await parseAgentConfig(agentName, this.crewConfig, this.functionsRegistry, this.state);
+            const agentConfig = await parseAgentConfig(agentName, this.crewConfig, this.functionsRegistry, this.state, this.options);
             // Destructure with type assertion
             const { ai, name, description, signature, functions, subAgentNames, examples, tracker } = agentConfig;
             // Get subagents for the AI agent

package/dist/types.d.ts

@@ -216,4 +216,17 @@ interface AgentConfig {
 interface AxCrewConfig {
     crew: AgentConfig[];
 }
-export { type AgentConfig, type AxCrewConfig, type AggregatedMetrics, type StateInstance, type FunctionRegistryType, type MCPStdioTransportConfig, type MCPHTTPSSETransportConfig, type MCPStreamableHTTPTransportConfig, type MCPTransportConfig, type ModelUsage, type ModelInfo, type UsageCost, type AggregatedCosts };
+/**
+ * Options for the AxCrew instance, specifically allowing optional OpenTelemetry injection.
+ *
+ * @property {Object} [telemetry] - Telemetry configuration.
+ * @property {any} [telemetry.tracer] - OpenTelemetry Tracer instance.
+ * @property {any} [telemetry.meter] - OpenTelemetry Meter instance.
+ */
+interface AxCrewOptions {
+    telemetry?: {
+        tracer?: any;
+        meter?: any;
+    };
+}
+export { type AgentConfig, type AxCrewConfig, type AxCrewOptions, type AggregatedMetrics, type StateInstance, type FunctionRegistryType, type MCPStdioTransportConfig, type MCPHTTPSSETransportConfig, type MCPStreamableHTTPTransportConfig, type MCPTransportConfig, type ModelUsage, type ModelInfo, type UsageCost, type AggregatedCosts };

package/examples/telemetry-demo.ts

@@ -0,0 +1,166 @@
+
+import { AxCrew } from "../dist/index.js";
+import { AxCrewFunctions } from "../dist/functions/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
+import type { Provider } from "../dist/types.js";
+import "dotenv/config";
+
+// Import OpenTelemetry packages
+// Note: In a real project, you would need to install these dependencies:
+// npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics
+// Optional: npm install @opentelemetry/exporter-jaeger (for Jaeger UI visualization)
+import { metrics, trace } from "@opentelemetry/api";
+import {
+  ConsoleSpanExporter,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import {
+  ConsoleMetricExporter,
+  MeterProvider,
+  PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+
+// Optional Jaeger import - will be used if available
+let JaegerExporter;
+try {
+  JaegerExporter = (await import('@opentelemetry/exporter-jaeger')).JaegerExporter;
+} catch (error) {
+  console.log('Jaeger exporter not available. Install with: npm install @opentelemetry/exporter-jaeger');
+  console.log('Traces will only be sent to console.');
+}
+
+// --- 1. Setup OpenTelemetry (Console + Optional Jaeger) ---
+
+// Set up tracing to console and optionally Jaeger
+const spanProcessors = [new SimpleSpanProcessor(new ConsoleSpanExporter())];
+
+// Add Jaeger if available
+if (JaegerExporter) {
+  try {
+    spanProcessors.push(new SimpleSpanProcessor(new JaegerExporter({
+      endpoint: 'http://localhost:14268/api/traces',
+    })));
+    console.log('Jaeger tracing enabled. View traces at: http://localhost:16686');
+  } catch (error) {
+    console.log('Failed to initialize Jaeger exporter:', error.message);
+    console.log('Continuing with console tracing only.');
+  }
+}
+
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors
+});
+tracerProvider.register(); // This registers it as the global tracer provider
+
+// Set up basic metrics to print to console
+const meterProvider = new MeterProvider({
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new ConsoleMetricExporter(),
+      exportIntervalMillis: 5000, // Export every 5 seconds
+    }),
+  ],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+
+// Get your tracer and meter instances
+const tracer = trace.getTracer("ax-crew-example");
+const meter = metrics.getMeter("ax-crew-example");
+
+// --- 2. Define Crew Configuration ---
+
+const crewConfig: AxCrewConfig = {
+  crew: [
+    {
+      name: "Researcher",
+      description: "Researches a topic using tools and provides a summary.",
+      signature: "topic:string -> facts:string[]",
+      // Agent 1 uses OpenAI
+      provider: "openai" as Provider,
+      providerKeyName: "OPENAI_API_KEY",
+      ai: {
+        model: "gpt-4o-mini",
+        temperature: 0.7,
+      },
+      // Give this agent access to a tool (function)
+      functions: ["CurrentDateTime"]
+    },
+    {
+      name: "Writer",
+      description: "Writes a blog post based on provided facts.",
+      signature: "facts:string[] -> blogPost:string",
+      // Agent 2 uses a different provider (e.g., Google Gemini)
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: {
+        model: "gemini-flash-latest",
+        temperature: 0.7,
+      },
+      // No tools for this agent, just pure generation
+    }
+  ]
+};
+
+// --- 3. Run the Crew ---
+
+async function main() {
+  console.log("Starting AxCrew with Telemetry...");
+
+  // Initialize AxCrew with the telemetry options
+  const crew = new AxCrew(
+    crewConfig,
+    AxCrewFunctions,
+    undefined, // Use default crewId
+    {
+      telemetry: {
+        tracer,
+        meter
+      }
+    }
+  );
+
+  try {
+    // Initialize agents
+    await crew.addAgent("Researcher");
+    await crew.addAgent("Writer");
+
+    const researcher = crew.agents!.get("Researcher")!;
+    const writer = crew.agents!.get("Writer")!;
+
+    // Step 1: Research
+    console.log("\n--- Step 1: Researching ---");
+    // This call will be traced, including the 'CurrentDateTime' tool usage
+    const researchResult = await researcher.forward({
+      topic: "The future of AI agents in 2025"
+    });
+    console.log("Research output:", researchResult.facts);
+
+    // Step 2: Writing
+    console.log("\n--- Step 2: Writing ---");
+    // This call will be traced under a different provider
+    const writerResult = await writer.forward({
+      facts: researchResult.facts
+    });
+    console.log("Blog Post:\n", writerResult.blogPost);
+
+    console.log("\n--- Done ---");
+    console.log("Check your console output above for OpenTelemetry traces and metrics.");
+    if (JaegerExporter) {
+      console.log("Check Jaeger UI at http://localhost:16686 for enhanced trace visualization.");
+    } else {
+      console.log("For enhanced visualization, install Jaeger: npm install @opentelemetry/exporter-jaeger");
+      console.log("Then run: docker run -d --name jaeger -p 16686:16686 -p 14268:14268 jaegertracing/all-in-one:latest");
+    }
+
+    // Wait a moment for metrics to export before exiting
+    await new Promise(resolve => setTimeout(resolve, 6000));
+
+  } catch (error) {
+    console.error("Error running crew:", error);
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "Build and launch a crew of AI agents with shared state. Built with axllm.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,8 @@
   },
   "peerDependencies": {
     "@ax-llm/ax": "^14.0.36",
-    "@ax-llm/ax-tools": "^14.0.36"
+    "@ax-llm/ax-tools": "^14.0.36",
+    "@opentelemetry/api": "^1.9.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/src/agents/agentConfig.ts

@@ -7,6 +7,7 @@ import { AxMCPStdioTransport } from '@ax-llm/ax-tools'
 import type { 
   AgentConfig,
   AxCrewConfig,
+  AxCrewOptions,
   FunctionRegistryType, 
   MCPTransportConfig, 
   MCPStdioTransportConfig, 
@@ -112,7 +113,8 @@ const parseAgentConfig = async (
   agentName: string, 
   crewConfig: AxCrewConfig,
   functions: FunctionRegistryType,
-  state: Record<string, any>
+  state: Record<string, any>,
+  options?: AxCrewOptions
 ) => {
   try {
     // Retrieve the parameters for the specified AI agent from config
@@ -149,7 +151,10 @@ const parseAgentConfig = async (
         debug: agentConfigData.debug || false,
         ...agentConfigData.options,
         // Attach default cost tracker so usage/costs are recorded by provider layer
-        trackers: [costTracker]
+        trackers: [costTracker],
+        // Inject telemetry if provided
+        tracer: options?.telemetry?.tracer,
+        meter: options?.telemetry?.meter
       }
     };
     if (agentConfigData.apiURL) {

package/src/agents/index.ts

@@ -15,6 +15,7 @@ import type {
    FunctionRegistryType, 
    UsageCost, 
    AxCrewConfig,
+   AxCrewOptions,
    MCPTransportConfig,
 } from "../types.js";
 
@@ -280,6 +281,7 @@ class StatefulAxAgent extends AxAgent<any, any> {
  */
 class AxCrew {
   private crewConfig: AxCrewConfig;
+  private options?: AxCrewOptions;
   functionsRegistry: FunctionRegistryType = {};
   crewId: string;
   agents: Map<string, StatefulAxAgent> | null;
@@ -289,12 +291,14 @@ class AxCrew {
    * Creates an instance of AxCrew.
    * @param {AxCrewConfig} crewConfig - JSON object with crew configuration.
    * @param {FunctionRegistryType} [functionsRegistry={}] - The registry of functions to use in the crew.
+   * @param {AxCrewOptions} [options] - Optional settings for the crew (e.g., telemetry).
    * @param {string} [crewId=uuidv4()] - The unique identifier for the crew.
    */
   constructor(
     crewConfig: AxCrewConfig,
     functionsRegistry: FunctionRegistryType = {},
-    crewId: string = uuidv4()
+    options?: AxCrewOptions,
+    crewId: string = uuidv4(),
   ) {
     // Basic validation of crew configuration
     if (!crewConfig || typeof crewConfig !== 'object' || !('crew' in crewConfig)) {
@@ -311,6 +315,7 @@ class AxCrew {
     this.crewConfig = crewConfig;
     this.functionsRegistry = functionsRegistry;
     this.crewId = crewId;
+    this.options = options;
     this.agents = new Map<string, StatefulAxAgent>();
     this.state = createState(crewId);
     // Make crewId discoverable to metrics
@@ -329,7 +334,8 @@ class AxCrew {
         agentName,
         this.crewConfig,
         this.functionsRegistry,
-        this.state
+        this.state,
+        this.options
       );
 
       // Destructure with type assertion

package/src/types.ts

@@ -236,9 +236,24 @@ interface AxCrewConfig {
   crew: AgentConfig[]
 }
 
+/**
+ * Options for the AxCrew instance, specifically allowing optional OpenTelemetry injection.
+ *
+ * @property {Object} [telemetry] - Telemetry configuration.
+ * @property {any} [telemetry.tracer] - OpenTelemetry Tracer instance.
+ * @property {any} [telemetry.meter] - OpenTelemetry Meter instance.
+ */
+interface AxCrewOptions {
+  telemetry?: {
+    tracer?: any;
+    meter?: any;
+  }
+}
+
 export {
   type AgentConfig,
   type AxCrewConfig,
+  type AxCrewOptions,
   type AggregatedMetrics,
   type StateInstance,
   type FunctionRegistryType,

package/tests/telemetry.test.ts

@@ -0,0 +1,81 @@
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AxCrew } from '../src/index.js';
+import type { AxCrewConfig } from '../src/types.js';
+import * as axModule from '@ax-llm/ax';
+
+// Mock the entire @ax-llm/ax module
+vi.mock('@ax-llm/ax', async (importOriginal) => {
+  const actual = await importOriginal() as typeof axModule;
+  return {
+    ...actual,
+    // Spy on the ai factory function
+    ai: vi.fn().mockImplementation((args) => {
+      // Return a dummy object that mimics enough of AxAI to satisfy AxCrew
+      return {
+        getName: () => args.name,
+        chat: vi.fn(),
+        defaults: { model: args.config?.model },
+        options: args.options // Store options so we can potentially inspect if needed, though we rely on the spy
+      };
+    }),
+    // We need to keep other exports working if they are used
+    AxAgent: actual.AxAgent,
+    AxAI: actual.AxAI,
+    AxDefaultCostTracker: actual.AxDefaultCostTracker
+  };
+});
+
+describe('AxCrew Telemetry', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should pass telemetry options to the underlying AxAI factory', async () => {
+    const mockTracer = { isMockTracer: true };
+    const mockMeter = { isMockMeter: true };
+
+    const crewConfig: AxCrewConfig = {
+      crew: [
+        {
+          name: "telemetry-agent",
+          description: "An agent for testing telemetry propagation",
+          signature: "in:string -> out:string",
+          provider: "openai",
+          providerKeyName: "OPENAI_API_KEY",
+          ai: { model: "gpt-4o-mini" }
+        }
+      ]
+    };
+
+    // Set dummy key
+    process.env.OPENAI_API_KEY = 'dummy-key';
+
+    const options = {
+        telemetry: {
+            tracer: mockTracer,
+            meter: mockMeter
+        }
+    };
+
+    // Initialize Crew with telemetry options (3rd argument now)
+    const crew = new AxCrew(crewConfig, {}, options as any);
+
+    // Create the agent
+    await crew.addAgent("telemetry-agent");
+
+    // Check if the 'ai' mock was called with the expected arguments
+    expect(axModule.ai).toHaveBeenCalled();
+
+    // Get the arguments of the first call to ai()
+    const callArgs = vi.mocked(axModule.ai).mock.calls[0][0];
+
+    // Verify the structure
+    expect(callArgs).toBeDefined();
+    expect(callArgs.options).toBeDefined();
+
+    // Assert tracer and meter were passed correctly
+    expect(callArgs.options.tracer).toBe(mockTracer);
+    expect(callArgs.options.meter).toBe(mockMeter);
+  });
+});