@amitdeshmukh/ax-crew 5.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,45 @@
 # 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
+- Config is now object-only to be browser-safe. File-path based configs are no longer supported. Load JSON yourself and pass `{ crew: [...] }`.
+
+### Added
+- Runtime API key resolution via `providerKeyName`. Keys are read from `process.env[providerKeyName]` in Node or `globalThis[providerKeyName]` in the browser.
+- Updated examples to use `dotenv/config` to ensure keys are available at runtime.
+
+### Changed
+- Removed reliance on a hardcoded `PROVIDER_API_KEYS` map; providers read secrets using the user-supplied env var name.
+- `providerArgs` are forwarded unchanged to Ax; validation and semantics are handled by Ax provider implementations.
+- Docs updated: object-only config, env resolution behavior, providerArgs guidance.
+
+### Removed
+- Hardcoded provider lists/registries and the old `providers.ts` list file.
+- Temporary removal of router/balancer helpers and related examples to simplify this refactor.
+
+### Migration notes
+- If you previously passed a config file path, read the file yourself and pass the parsed object to `new AxCrew(config)`.
+- Set `providerKeyName` to the exact environment variable name holding the API key. Ensure env is loaded before constructing the crew (e.g., `import 'dotenv/config'`).
+
 ## [5.0.0] - 2025-10-16
 
 ### Added

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.
@@ -33,43 +35,17 @@ ANTHROPIC_API_KEY=...
 OPENAI_API_KEY=...
 AZURE_OPENAI_API_KEY=...
 ```
-In each agent config, set `providerKeyName` to the env var name.
+In each agent config, set `providerKeyName` to the env var name. AxCrew resolves the key at runtime by reading `process.env[providerKeyName]` in Node or `globalThis[providerKeyName]` in the browser. Ensure your env is loaded (for example, import `dotenv/config` in Node) before creating the crew.
 
 #### Provider-specific arguments (`providerArgs`)
-Some providers require extra top-level configuration beyond `ai.model` (e.g., Azure deployments or Gemini project/region). You can pass these via `providerArgs`; AxCrew forwards them to the underlying Ax factory with type alignment for popular providers.
-
-Supported mappings:
-- `azure-openai`: `resourceName`, `deploymentName`, `version` (if `resourceName` omitted and `apiURL` set, `apiURL` is used as full endpoint)
-- `anthropic`: `projectId`, `region`
-- `google-gemini`: `projectId`, `region`, `endpointId`
-- `openrouter`: `referer`, `title`
-- `ollama`: `url`
-
-Azure example with `providerArgs`:
-```json
-{
-  "name": "Writer",
-  "description": "Writes concise summaries",
-  "signature": "topic:string -> summary:string",
-  "provider": "azure-openai",
-  "providerKeyName": "AZURE_OPENAI_API_KEY",
-  "ai": { "model": "gpt-4o-mini", "temperature": 0 },
-  "apiURL": "https://your-resource.openai.azure.com",  "providerArgs": {
-    "resourceName": "your-resource",
-    "deploymentName": "gpt-4o-mini",
-    "version": "api-version=2024-02-15-preview"
-  }
-}
-```
+Some providers require extra top-level configuration beyond `ai.model` (for example, Azure deployment details or Vertex AI project/region). Pass these via `providerArgs`. AxCrew forwards `providerArgs` to Ax unchanged; validation and semantics are handled by Ax. Refer to Ax provider docs for supported fields.
 
 ### Quickstart
-This package includes TypeScript declarations and provides type safety.
 
 ```typescript
 import { AxCrew, AxCrewFunctions, FunctionRegistryType, StateInstance } from '@amitdeshmukh/ax-crew';
 import type { AxFunction } from '@ax-llm/ax';
 
-// Type-safe configuration
 const config = {
   crew: [{
     name: "Planner",
@@ -156,25 +132,7 @@ Key TypeScript features:
 ## Usage
 
 ### Initializing a Crew
-A Crew is a team of agents that work together to achieve a common goal. You can configure your crew in two ways:
-
-1. Using a JSON configuration file that defines the agents in the crew, along with their individual configurations.
-2. Directly passing a JSON object with the crew configuration.
-
-#### Using a Configuration File
-See [agentConfig.json](agentConfig.json) for an example configuration file.
-
-```javascript
-// Import the AxCrew class
-import { AxCrew } from '@amitdeshmukh/ax-crew';
-
-// Create a new instance of AxCrew using a config file
-const configFilePath = './agentConfig.json';
-const crew = new AxCrew(configFilePath);
-```
-
-#### Using a Direct Configuration Object
-You can also pass the configuration directly as a JSON object:
+Pass a JSON object to the `AxCrew` constructor:
 
 ```javascript
 // Import the AxCrew class
@@ -205,15 +163,7 @@ const config = {
 const crew = new AxCrew(config);
 ```
 
-Both methods support the same configuration structure and options. Choose the one that best fits your use case:
-- Use a configuration file when you want to:
-  - Keep your configuration separate from your code
-  - Share configurations across different projects
-  - Version control your configurations
-- Use a direct configuration object when you want to:
-  - Generate configurations dynamically
-  - Modify configurations at runtime
-  - Keep everything in one file for simpler projects
+AxCrew no longer supports reading from a configuration file to remain browser-compatible.
 
 ### Agent Persona: definition and prompt
 
@@ -417,7 +367,7 @@ An example of how to complete a task using the agents is shown below. The `Plann
 import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
 
 // Create a new instance of AxCrew
-const crew = new AxCrew('./agentConfig.json', AxCrewFunctions);
+const crew = new AxCrew(config, AxCrewFunctions);
 crew.addAgentsToCrew(['Planner', 'Calculator', 'Manager']);
 
 // Get agent instances
@@ -449,7 +399,7 @@ The package supports streaming responses from agents, allowing you to receive an
 import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
 
 // Create and initialize crew as shown above
-const crew = new AxCrew('./agentConfig.json', AxCrewFunctions);
+const crew = new AxCrew(config, AxCrewFunctions);
 await crew.addAgentsToCrew(['Planner']);
 
 const planner = crew.agents.get("Planner");
@@ -666,7 +616,7 @@ MCP functions are automatically available to agents once the servers are configu
 import { AxCrew } from '@amitdeshmukh/ax-crew';
 
 // Create crew with MCP-enabled agents
-const crew = new AxCrew('./agentConfig.json');
+const crew = new AxCrew(config);
 await crew.addAgent('DataAnalyst'); // Agent with MCP servers configured
 
 const analyst = crew.agents.get('DataAnalyst');
@@ -767,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,16 +1,16 @@
 import { AxDefaultCostTracker } from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
-import type { AgentConfig, CrewConfigInput, 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;
 /**
- * Parses and returns the AxCrew config from either a JSON config file or a direct JSON object.
- * @param {CrewConfigInput} input - Either a path to the agent config json file or a JSON object with crew configuration.
+ * Returns the AxCrew config from a direct JSON object. Browser-safe.
+ * @param {CrewConfig} input - A JSON object with crew configuration.
  * @returns {Object} The parsed crew config.
  * @throws Will throw an error if reading/parsing fails.
  */
-declare const parseCrewConfig: (input: CrewConfigInput) => {
+declare const parseCrewConfig: (input: AxCrewConfig) => {
     crew: AgentConfig[];
 };
 /**
@@ -18,14 +18,14 @@ declare const parseCrewConfig: (input: CrewConfigInput) => {
  * and creates an instance of the Agent with the appropriate settings.
  *
  * @param {string} agentName - The identifier for the AI agent to be initialized.
- * @param {CrewConfigInput} crewConfig - Either a file path to the JSON configuration or a JSON object with crew configuration.
+ * @param {AxCrewConfig} crewConfig - A JSON object with crew configuration.
  * @param {FunctionRegistryType} functions - The functions available to the agent.
  * @param {Object} state - The state object for the agent.
  * @returns {Object} An object containing the Agents AI instance, its name, description, signature, functions and subAgentList.
  * @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: CrewConfigInput, 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

@@ -1,27 +1,7 @@
-import fs from 'fs';
-// Import Ax factory and MCP transports (as exported by current package)
+// Import Ax factory and MCP transports
 import { ai, AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport, AxDefaultCostTracker } from '@ax-llm/ax';
 // STDIO transport from tools package
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools';
-import { PROVIDER_API_KEYS } from '../config/index.js';
-// Canonical provider slugs supported by ai() factory
-const PROVIDER_CANONICAL = new Set([
-    'openai',
-    'anthropic',
-    'google-gemini',
-    'mistral',
-    'groq',
-    'cohere',
-    'together',
-    'deepseek',
-    'ollama',
-    'huggingface',
-    'openrouter',
-    'azure-openai',
-    'reka',
-    'x-grok'
-]);
-// Provider type lives in src/types.ts
 // Type guard to check if config is stdio transport
 export function isStdioTransport(config) {
     return 'command' in config;
@@ -44,48 +24,7 @@ export function isStreambleHTTPTransport(config) {
 function isConstructor(func) {
     return typeof func === 'function' && 'prototype' in func && 'toFunction' in func.prototype;
 }
-/**
- * Provides a user-friendly error message for JSON parsing errors
- */
-const getFormattedJSONError = (error, fileContents) => {
-    if (error instanceof SyntaxError) {
-        const match = error.message.match(/position (\d+)/);
-        const position = match ? parseInt(match[1]) : -1;
-        if (position !== -1) {
-            const lines = fileContents.split('\n');
-            let currentPos = 0;
-            let errorLine = 0;
-            let errorColumn = 0;
-            // Find the line and column of the error
-            for (let i = 0; i < lines.length; i++) {
-                if (currentPos + lines[i].length >= position) {
-                    errorLine = i + 1;
-                    errorColumn = position - currentPos + 1;
-                    break;
-                }
-                currentPos += lines[i].length + 1; // +1 for the newline character
-            }
-            const contextLines = lines.slice(Math.max(0, errorLine - 3), errorLine + 2)
-                .map((line, idx) => `${errorLine - 2 + idx}:  ${line}`).join('\n');
-            return `JSON Parse Error in your agent configuration:
-      
-Error near line ${errorLine}, column ${errorColumn}
-
-Context:
-${contextLines}
-
-Common issues to check:
-- Missing or extra commas between properties
-- Missing quotes around property names
-- Unmatched brackets or braces
-- Invalid JSON values
-- Trailing commas (not allowed in JSON)
-
-Original error: ${error.message}`;
-        }
-    }
-    return `Error parsing agent configuration: ${error.message}`;
-};
+// Removed file/JSON parse helpers to keep browser-safe
 const initializeMCPServers = async (agentConfigData) => {
     const mcpServers = agentConfigData.mcpServers;
     if (!mcpServers || Object.keys(mcpServers).length === 0) {
@@ -126,66 +65,46 @@ const initializeMCPServers = async (agentConfigData) => {
     }
 };
 /**
- * Parses and returns the AxCrew config from either a JSON config file or a direct JSON object.
- * @param {CrewConfigInput} input - Either a path to the agent config json file or a JSON object with crew configuration.
+ * Returns the AxCrew config from a direct JSON object. Browser-safe.
+ * @param {CrewConfig} input - A JSON object with crew configuration.
  * @returns {Object} The parsed crew config.
  * @throws Will throw an error if reading/parsing fails.
  */
 const parseCrewConfig = (input) => {
-    try {
-        if (typeof input === 'string') {
-            // Handle file path input
-            const fileContents = fs.readFileSync(input, 'utf8');
-            const parsedConfig = JSON.parse(fileContents);
-            return parsedConfig;
-        }
-        else {
-            // Handle direct JSON object input
-            return input;
-        }
-    }
-    catch (e) {
-        if (e instanceof Error) {
-            if (typeof input === 'string') {
-                const formattedError = getFormattedJSONError(e, fs.readFileSync(input, 'utf8'));
-                throw new Error(formattedError);
-            }
-            throw new Error(`Error parsing agent configuration: ${e.message}`);
-        }
-        throw e;
+    if (!input || typeof input !== 'object' || !Array.isArray(input.crew)) {
+        throw new Error('Invalid crew configuration: expected an object with a crew array');
     }
+    return input;
 };
 /**
  * Parses the agent's configuration, validates the presence of the necessary API key,
  * and creates an instance of the Agent with the appropriate settings.
  *
  * @param {string} agentName - The identifier for the AI agent to be initialized.
- * @param {CrewConfigInput} crewConfig - Either a file path to the JSON configuration or a JSON object with crew configuration.
+ * @param {AxCrewConfig} crewConfig - A JSON object with crew configuration.
  * @param {FunctionRegistryType} functions - The functions available to the agent.
  * @param {Object} state - The state object for the agent.
  * @returns {Object} An object containing the Agents AI instance, its name, description, signature, functions and subAgentList.
  * @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);
         if (!agentConfigData) {
             throw new Error(`AI agent with name ${agentName} is not configured`);
         }
-        // Enforce canonical provider slug
-        const lower = agentConfigData.provider.toLowerCase();
-        if (!PROVIDER_CANONICAL.has(lower)) {
-            throw new Error(`AI provider ${agentConfigData.provider} is not supported. Use one of: ${Array.from(PROVIDER_CANONICAL).join(', ')}`);
-        }
+        // Normalize provider slug to lowercase and validate via Ax factory
+        const lower = String(agentConfigData.provider).toLowerCase();
         const provider = lower;
-        // If an API Key property is present, get the API key for the AI agent from the environment variables
+        // Resolve API key from user-supplied environment variable name
         let apiKey = '';
         if (agentConfigData.providerKeyName) {
-            apiKey = PROVIDER_API_KEYS[agentConfigData.providerKeyName] || '';
+            const keyName = agentConfigData.providerKeyName;
+            apiKey = resolveApiKey(keyName) || '';
             if (!apiKey) {
-                throw new Error(`API key for provider ${agentConfigData.provider} is not set in environment variables`);
+                throw new Error(`API key '${keyName}' for provider ${agentConfigData.provider} is not set in environment`);
             }
         }
         else {
@@ -202,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) {
@@ -214,37 +136,20 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
                 throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
             }
         }
-        // Forward provider-specific arguments with type-safety for Azure OpenAI
+        // Forward provider-specific arguments as-is; let Ax validate/ignore as needed
         const providerArgs = agentConfigData.providerArgs;
-        if (provider === 'azure-openai') {
-            const az = providerArgs ?? {};
-            // If users supplied apiURL instead of resourceName, accept it (Ax supports full URL as resourceName)
-            if (!az.resourceName && agentConfigData.apiURL) {
-                az.resourceName = agentConfigData.apiURL;
-            }
-            Object.assign(aiArgs, az);
-        }
-        else if (provider === 'anthropic') {
-            const an = providerArgs ?? {};
-            Object.assign(aiArgs, an);
-        }
-        else if (provider === 'google-gemini') {
-            const g = providerArgs ?? {};
-            Object.assign(aiArgs, g);
-        }
-        else if (provider === 'openrouter') {
-            const o = providerArgs ?? {};
-            Object.assign(aiArgs, o);
+        if (providerArgs && typeof providerArgs === 'object') {
+            Object.assign(aiArgs, providerArgs);
         }
-        else if (provider === 'ollama') {
-            const ol = providerArgs ?? {};
-            Object.assign(aiArgs, ol);
+        // Validate provider by attempting instantiation; Ax will throw on unknown providers
+        let aiInstance;
+        try {
+            aiInstance = ai(aiArgs);
         }
-        else if (providerArgs && typeof providerArgs === 'object') {
-            // Generic pass-through for other providers if needed in the future
-            Object.assign(aiArgs, providerArgs);
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Unsupported provider '${provider}': ${msg}`);
         }
-        const aiInstance = ai(aiArgs);
         // If an mcpServers config is provided in the agent config, convert to functions
         const mcpFunctions = await initializeMCPServers(agentConfigData);
         // Prepare functions for the AI agent
@@ -284,3 +189,20 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
     }
 };
 export { parseAgentConfig, parseCrewConfig };
+function resolveApiKey(varName) {
+    try {
+        // Prefer Node env when available
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        if (typeof process !== 'undefined' && process?.env) {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            return process.env[varName];
+        }
+        // Fallback: allow global exposure in browser builds (e.g., injected at runtime)
+        return globalThis?.[varName];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/agents/compose.d.ts

@@ -0,0 +1,15 @@
+import type { AxAI } from '@ax-llm/ax';
+import type { AxCrewConfig } from '../types.js';
+type BuildProviderArgs = {
+    provider: string;
+    apiKey: string;
+    config: any;
+    apiURL?: string;
+    providerArgs?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+};
+export declare function instantiateProvider({ provider, apiKey, config, apiURL, providerArgs, options, }: BuildProviderArgs): AxAI<any>;
+export declare function buildProvidersFromConfig(cfg: AxCrewConfig): AxAI<any>[];
+export declare function discoverProvidersFromConfig(cfg: AxCrewConfig): string[];
+export declare function listSelectableProviders(cfg: AxCrewConfig): string[];
+export {};

package/dist/agents/compose.js

@@ -0,0 +1,58 @@
+import { ai } from '@ax-llm/ax';
+export function instantiateProvider({ provider, apiKey, config, apiURL, providerArgs, options, }) {
+    const args = { name: provider, apiKey, config, options };
+    if (apiURL)
+        args.apiURL = apiURL;
+    if (providerArgs && typeof providerArgs === 'object')
+        Object.assign(args, providerArgs);
+    return ai(args);
+}
+export function buildProvidersFromConfig(cfg) {
+    const services = [];
+    for (const agent of cfg.crew) {
+        const apiKeyName = agent.providerKeyName;
+        if (!apiKeyName)
+            throw new Error(`Provider key name is missing for agent ${agent.name}`);
+        const apiKey = resolveApiKey(apiKeyName) || '';
+        if (!apiKey)
+            throw new Error(`API key '${apiKeyName}' not set for agent ${agent.name}`);
+        const service = instantiateProvider({
+            provider: String(agent.provider).toLowerCase(),
+            apiKey,
+            config: agent.ai,
+            apiURL: agent.apiURL,
+            providerArgs: agent.providerArgs,
+            options: agent.options,
+        });
+        services.push(service);
+    }
+    return services;
+}
+// Provider discovery helpers consolidated here (previously in src/providers.ts)
+export function discoverProvidersFromConfig(cfg) {
+    const providers = new Set();
+    for (const agent of cfg.crew) {
+        providers.add(String(agent.provider).toLowerCase());
+    }
+    return Array.from(providers);
+}
+export function listSelectableProviders(cfg) {
+    return discoverProvidersFromConfig(cfg);
+}
+function resolveApiKey(varName) {
+    try {
+        // Prefer Node env when available
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        if (typeof process !== 'undefined' && process?.env) {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            return process.env[varName];
+        }
+        // Fallback: allow global exposure in browser builds (e.g., injected at runtime)
+        return globalThis?.[varName];
+    }
+    catch {
+        return undefined;
+    }
+}