@amitdeshmukh/ax-crew 5.0.0 → 6.0.0

package/dist/index.js

@@ -1,5 +1,30 @@
 import { AxCrew } from './agents/index.js';
 import { AxCrewFunctions } from './functions/index.js';
+/**
+ * Metrics types and helpers for request counts, token usage, and estimated cost.
+ *
+ * Re-exports the metrics module for convenience:
+ *  - Types: TokenUsage, MetricsSnapshot, etc.
+ *  - Namespace: MetricsRegistry (record/snapshot/reset helpers)
+ */
 export * from './metrics/index.js';
+/**
+ * MetricsRegistry provides functions to record requests, tokens, and cost,
+ * and to snapshot/reset metrics at agent or crew granularity.
+ */
 export { MetricsRegistry } from './metrics/index.js';
-export { AxCrew, AxCrewFunctions, };
+/**
+ * Create and manage a crew of Ax agents that share state and metrics.
+ * See the `AxCrew` class for full documentation.
+ */
+const _AxCrew = AxCrew;
+/**
+ * Built-in function registry with common tools that can be referenced by name
+ * from agent configs, or extended with your own functions.
+ */
+const _AxCrewFunctions = AxCrewFunctions;
+export { 
+/** See class JSDoc on the `AxCrew` implementation. */
+_AxCrew as AxCrew, 
+/** Built-in function registry; see file docs in `src/functions/index.ts`. */
+_AxCrewFunctions as AxCrewFunctions, };

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import type { AxFunction, AxSignature, AxModelConfig, AxMCPStreamableHTTPTransportOptions, AxProgramForwardOptions } from '@ax-llm/ax';
-export type Provider = 'openai' | 'anthropic' | 'google-gemini' | 'mistral' | 'groq' | 'cohere' | 'together' | 'deepseek' | 'ollama' | 'huggingface' | 'openrouter' | 'azure-openai' | 'reka' | 'x-grok';
+import type { AxFunction, AxSignature, AxModelConfig, AxMCPStreamableHTTPTransportOptions, AxProgramForwardOptions, AxAIArgs } from '@ax-llm/ax';
+export type Provider = AxAIArgs<any>['name'];
 /**
  * A state instance that is shared between agents.
  * This can be used to store data that becomes available to all agents and functions in an out-of-band manner.
@@ -177,9 +177,43 @@ interface AgentConfig {
     mcpServers?: Record<string, MCPTransportConfig>;
 }
 /**
- * The input type for the agent config. This can be a path to a JSON file or a JSON object.
+ * The configuration object for an AxCrew instance.
+ *
+ * @property {AgentConfig[]} crew - The agents that make up the crew.
+ * @example
+ * const config: AxCrewConfig = {
+ *   crew: [
+ *     {
+ *       name: "Agent1",
+ *       description: "Agent 1 description",
+ *       signature: "signature",
+ *       provider: "provider",
+ *       providerKeyName: "providerKeyName",
+ *       ai: {
+ *         model: "model",
+ *         temperature: 0,
+ *       },
+ *       options: {
+ *         debug: true,
+ *       },
+ *       functions: ["function1", "function2"],
+ *       agents: ["agent2"],
+ *     },
+ *     {
+ *       name: "Agent2",
+ *       description: "Agent 2 description",
+ *       signature: "signature",
+ *       provider: "provider",
+ *       providerKeyName: "providerKeyName",
+ *       ai: {
+ *         model: "model",
+ *         temperature: 0,
+ *       }
+ *   ]
+ * }
+ * const crew = new AxCrew(config);
  */
-type CrewConfigInput = string | {
+interface AxCrewConfig {
     crew: AgentConfig[];
-};
-export { type AgentConfig, type CrewConfigInput, type AggregatedMetrics, type StateInstance, type FunctionRegistryType, type MCPStdioTransportConfig, type MCPHTTPSSETransportConfig, type MCPStreamableHTTPTransportConfig, type MCPTransportConfig, type ModelUsage, type ModelInfo, type UsageCost, type AggregatedCosts };
+}
+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 };

package/examples/basic-researcher-writer.ts

@@ -2,6 +2,8 @@ import { AxCrew } from "../dist/index.js";
 import { AxCrewFunctions } from "../dist/functions/index.js";
 import type { AxCrewConfig } from "../dist/index.js";
 import type { Provider } from "../dist/types.js";
+import dotenv from "dotenv";
+dotenv.config();
 
 // Example agent configuration
 const agentConfig: AxCrewConfig = {
@@ -26,10 +28,10 @@ const agentConfig: AxCrewConfig = {
       name: "writer",
       description: "A writing agent that creates content",
       signature: "topic:string -> article:string",
-      provider: "anthropic" as Provider,
-      providerKeyName: "ANTHROPIC_API_KEY",
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "claude-3-haiku-20240307",
+        model: "gemini-2.5-flash-lite",
         maxTokens: 4000,
         stream: true
       },

package/examples/mcp-agent.ts

@@ -1,4 +1,5 @@
-import { AxCrew, AxCrewConfig } from "../dist/index.js";
+import { AxCrew } from "../dist/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
 
 import dotenv from "dotenv";
 dotenv.config();
@@ -7,31 +8,23 @@ dotenv.config();
 const config = {
   crew: [
     {
-      name: "MapsAgent",
-      description: "A specialized agent with access to Google Maps APIs that can: geocode addresses to coordinates and vice versa, search for and get details about places, calculate travel distances and times between multiple locations, provide elevation data, and generate navigation directions between points.",
-      prompt: "You are a precise geospatial assistant with expert knowledge of Google Maps APIs. Answer user queries by combining place search, geocoding, distance matrix, elevation, and directions. Provide concise, actionable answers, include travel mode assumptions, and cite uncertainties. When location is ambiguous, ask a brief clarifying question before proceeding.",
-      signature: 'userQuery:string "a question to be answered" -> answer:string "the answer to the question"',
-      provider: "anthropic",
-      providerKeyName: "ANTHROPIC_API_KEY",
+      name: "Context7DocsAgent",
+      description: "A specialized agent with access to Context7 Docs APIs that can: search for and get details about API docs",
+      signature: 'apiDocQuery:string "a question to be answered" -> apiDocAnswer:string "the answer to the question"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "claude-3-5-sonnet-latest",
+        model: "gemini-2.5-pro",
         temperature: 0,
-        maxTokens: 1000,
-        stream: true
+        stream: false
       },
       options: {
         debug: true
       },
       "mcpServers": {
-        "google-maps": {
+        "context7": {
           "command": "npx",
-          "args": [
-            "-y",
-            "@modelcontextprotocol/server-google-maps"
-          ],
-          "env": {
-            "GOOGLE_MAPS_API_KEY": process.env.GOOGLE_MAPS_API_KEY
-          }
+          "args": ["-y", "@upstash/context7-mcp", "--api-key", process.env.CONTEXT7_API_KEY]
         }
       },
     },
@@ -41,35 +34,19 @@ const config = {
       prompt: "You are a manager agent that orchestrates tools and sub-agents. Read the user's objective, optionally produce a short plan, then call the MapsAgent when geospatial knowledge is needed. Keep answers direct and avoid extraneous commentary.",
       signature:
         'question:string "a question to be answered" -> answer:string "the answer to the question"',
-      provider: "openai", 
-      providerKeyName: "OPENAI_API_KEY",
+      provider: "google-gemini", 
+      providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "gpt-4o-mini",
+        model: "gemini-2.5-pro",
         maxTokens: 1000,
         temperature: 0,
-        stream: true
+        stream: false
       },
       options: {
         debug: true,
       },
-      agents: ["MapsAgent"]
-    },
-    {
-      name: "MathAgent",
-      description: "Solves math problems",
-      signature:
-        'mathProblem:string "a sentence describing a math problem to be solved using Python code" -> solution:string "the answer to the math problem"',
-      provider: "google-gemini",
-      providerKeyName: "GEMINI_API_KEY",
-      ai: {
-        model: "gemini-1.5-pro",
-        temperature: 0,
-        stream: true
-      },
-      options: {
-        debug: false,
-      },
-    },
+      agents: ["Context7DocsAgent"]
+    }
   ],
 };
 
@@ -81,9 +58,9 @@ await crew.addAllAgents();
 
 // Get agent instances
 const managerAgent = crew.agents?.get("ManagerAgent");
-const mapsAgent = crew.agents?.get("MapsAgent");
+const context7DocsAgent = crew.agents?.get("Context7DocsAgent");
 
-const userQuery: string = "Are there any cool bars around the Eiffel Tower in Paris within 5 min walking distance";
+const userQuery: string = "How do i create an agent in the @amitdeshmukh/ax-crew framework and configure it to use an MCP server? Give me a concrete example.";
 
 console.log(`\n\nQuestion: ${userQuery}`);
 
@@ -97,7 +74,7 @@ const main = async (): Promise<void> => {
     // Print metrics
     console.log("\nMetrics:\n+++++++++++++++++++++++++++++++++");
     console.log("Manager Agent Metrics:", JSON.stringify((managerAgent as any)?.getMetrics?.(), null, 2));
-    console.log("Maps Agent Metrics:", JSON.stringify((mapsAgent as any)?.getMetrics?.(), null, 2));
+    console.log("Context7 Docs Agent Metrics:", JSON.stringify((context7DocsAgent as any)?.getMetrics?.(), null, 2));
     console.log("Crew Metrics:", JSON.stringify((crew as any)?.getCrewMetrics?.(), null, 2));
 };
 

package/examples/perplexityDeepSearch.ts

@@ -1,19 +1,20 @@
 import { AxCrew } from "../dist/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
 
 import dotenv from "dotenv";
 dotenv.config();
 
 // Define the crew configuration
-const config = {
+const config: AxCrewConfig = {
   crew: [
     {
       name: "DeepResearchAgent",
       description: "A specialized agent that performs deep research using perplexity",
-      signature: 'researchTopic:string "a topic of interest" -> result:string "The result of the research"',
-      provider: "openai",
-      providerKeyName: "OPENAI_API_KEY",
+      signature: 'researchTopic:string "a topic of interest" -> researchResult:string "The result of the research"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "gpt-4.1",
+        model: "gemini-2.5-flash-lite",
         temperature: 0.1,
       },
       options: {

package/examples/providerArgs.ts

@@ -1,4 +1,5 @@
-import { AxCrew, AxCrewConfig } from "../dist/index.js";
+import { AxCrew } from "../dist/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
 
 const crewConfig: AxCrewConfig = {
   crew: [

package/examples/search-tweets.ts

@@ -1,15 +1,16 @@
 import { AxCrew } from "../dist/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
 
 import dotenv from "dotenv";
 dotenv.config();
 
 // Define the crew configuration
-const config = {
+const config: AxCrewConfig = {
   crew: [
     {
       name: "XSearchAgent",
       description: "A specialized agent that can search X (Twitter) posts for the latest news and updates about specific topics, people, or events. It can find trending posts, recent tweets, and real-time information from X platform.",
-      signature: 'searchQuery:string "a search query" -> result:string "the response to the user query citing relevant sources including X posts and other web sources"',
+      signature: 'searchQuery:string "a search query" -> searchResults:string "the response to the user query citing relevant sources including X posts and other web sources"',
       provider: "grok",
       providerKeyName: "GROK_API_KEY",
       ai: {
@@ -55,8 +56,8 @@ const main = async (): Promise<void> => {
   if (response) {
     try {
       for await (const chunk of response) {
-        if (chunk.delta && typeof chunk.delta === 'object' && 'results' in chunk.delta) {
-          process.stdout.write(chunk.delta.results);
+        if (chunk.delta && typeof chunk.delta === 'object' && 'searchResults' in chunk.delta) {
+          process.stdout.write(chunk.delta.searchResults);
         }
       }
       console.log('\n');

package/examples/solve-math-problem.ts

@@ -1,5 +1,7 @@
 import { AxCrew } from "../dist/index.js";
 import type { AxCrewConfig } from "../src/index.js";
+import dotenv from "dotenv";
+dotenv.config();
 
 // Define the crew configuration
 const config: AxCrewConfig = {
@@ -12,11 +14,11 @@ const config: AxCrewConfig = {
       provider: "google-gemini",
       providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "gemini-1.5-pro",
+        model: "gemini-2.5-flash-lite",
         temperature: 0,
       },
       options: {
-        debug: false,
+        debug: true,
         codeExecution: true,
       },
     },
@@ -25,10 +27,10 @@ const config: AxCrewConfig = {
       description: "Completes a user specified task",
       signature:
         'question:string "a question to be answered" -> answer:string "the answer to the question"',
-      provider: "openai", 
-      providerKeyName: "OPENAI_API_KEY",
+      provider: "google-gemini", 
+      providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "gpt-4o-mini",
+        model: "gemini-2.5-flash-lite",
         maxTokens: 1000,
         temperature: 0,
       },

package/examples/streaming.ts

@@ -15,7 +15,7 @@ const config: AxCrewConfig = {
       provider: "google-gemini", 
       providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "gemini-2.0-flash",
+        model: "gemini-2.5-flash",
         maxTokens: 1000,
         temperature: 0,
       },
@@ -33,7 +33,7 @@ const config: AxCrewConfig = {
       provider: "google-gemini",
       providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "gemini-1.5-pro",
+        model: "gemini-2.5-pro",
         temperature: 0,
       },
       options: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "5.0.0",
+  "version": "6.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",
@@ -11,7 +11,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc --outDir dist",
     "release": "npm run build && npm publish --access public",
-    "test": "vitest",
+    "test": "vitest run",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui"
@@ -24,8 +24,8 @@
     "uuid": "^10.0.0"
   },
   "peerDependencies": {
-    "@ax-llm/ax": "14.0.16",
-    "@ax-llm/ax-tools": "14.0.16"
+    "@ax-llm/ax": "^14.0.36",
+    "@ax-llm/ax-tools": "^14.0.36"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/src/agents/agentConfig.ts

@@ -1,20 +1,12 @@
-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'
-import type {
-  AxAIAzureOpenAIArgs,
-  AxAIAnthropicArgs,
-  AxAIGoogleGeminiArgs,
-  AxAIOpenRouterArgs,
-  AxAIOllamaArgs
-} from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
 // STDIO transport from tools package
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools'
-import { PROVIDER_API_KEYS } from '../config/index.js';
+// Resolve env by provided key name
 import type { 
   AgentConfig,
-  CrewConfigInput,
+  AxCrewConfig,
   FunctionRegistryType, 
   MCPTransportConfig, 
   MCPStdioTransportConfig, 
@@ -23,26 +15,6 @@ import type {
 } from '../types.js';
 import type { Provider } from '../types.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: MCPTransportConfig): config is MCPStdioTransportConfig {
   return 'command' in config;
@@ -69,53 +41,7 @@ function isConstructor<T>(func: any): func is { new (...args: any[]): T } {
   return typeof func === 'function' && 'prototype' in func && 'toFunction' in func.prototype;
 }
 
-/**
- * Provides a user-friendly error message for JSON parsing errors
- */
-const getFormattedJSONError = (error: Error, fileContents: string): string => {
-  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: AgentConfig): Promise<AxFunction[]> => {
   const mcpServers = agentConfigData.mcpServers;
@@ -158,32 +84,16 @@ const initializeMCPServers = async (agentConfigData: AgentConfig): Promise<AxFun
 };
 
 /**
- * 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: CrewConfigInput): { crew: AgentConfig[] } => {
-  try {
-    if (typeof input === 'string') {
-      // Handle file path input
-      const fileContents = fs.readFileSync(input, 'utf8');
-      const parsedConfig = JSON.parse(fileContents) as { crew: AgentConfig[] };
-      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;
+const parseCrewConfig = (input: AxCrewConfig): { crew: AgentConfig[] } => {
+  if (!input || typeof input !== 'object' || !Array.isArray((input as any).crew)) {
+    throw new Error('Invalid crew configuration: expected an object with a crew array');
   }
+  return input as { crew: AgentConfig[] };
 };
 
 /**
@@ -191,7 +101,7 @@ const parseCrewConfig = (input: CrewConfigInput): { crew: AgentConfig[] } => {
  * 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.
@@ -200,7 +110,7 @@ const parseCrewConfig = (input: CrewConfigInput): { crew: AgentConfig[] } => {
  */
 const parseAgentConfig = async (
   agentName: string, 
-  crewConfig: CrewConfigInput,
+  crewConfig: AxCrewConfig,
   functions: FunctionRegistryType,
   state: Record<string, any>
 ) => {
@@ -211,20 +121,17 @@ const parseAgentConfig = async (
       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() as Provider;
     const provider = lower as Provider;
 
-    // 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 {
       throw new Error(`Provider key name is missing in the agent configuration`);
@@ -253,37 +160,19 @@ const parseAgentConfig = async (
         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 as any).providerArgs;
-    if (provider === 'azure-openai') {
-      type AzureArgs = Pick<AxAIAzureOpenAIArgs<string>, 'resourceName' | 'deploymentName' | 'version'>;
-      const az: Partial<AzureArgs> = 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 as any;
-      }
-      Object.assign(aiArgs, az);
-    } else if (provider === 'anthropic') {
-      type AnthropicArgs = Pick<AxAIAnthropicArgs<string>, 'projectId' | 'region'>;
-      const an: Partial<AnthropicArgs> = providerArgs ?? {};
-      Object.assign(aiArgs, an);
-    } else if (provider === 'google-gemini') {
-      type GeminiArgs = Pick<AxAIGoogleGeminiArgs<string>, 'projectId' | 'region' | 'endpointId'>;
-      const g: Partial<GeminiArgs> = providerArgs ?? {};
-      Object.assign(aiArgs, g);
-    } else if (provider === 'openrouter') {
-      type OpenRouterArgs = Pick<AxAIOpenRouterArgs<string>, 'referer' | 'title'>;
-      const o: Partial<OpenRouterArgs> = providerArgs ?? {};
-      Object.assign(aiArgs, o);
-    } else if (provider === 'ollama') {
-      type OllamaArgs = Pick<AxAIOllamaArgs<string>, 'url'>;
-      const ol: Partial<OllamaArgs> = providerArgs ?? {};
-      Object.assign(aiArgs, ol);
-    } else if (providerArgs && typeof providerArgs === 'object') {
-      // Generic pass-through for other providers if needed in the future
+    if (providerArgs && typeof providerArgs === 'object') {
       Object.assign(aiArgs, providerArgs);
     }
-    const aiInstance = ai(aiArgs);
+    // Validate provider by attempting instantiation; Ax will throw on unknown providers
+    let aiInstance;
+    try {
+      aiInstance = ai(aiArgs);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Unsupported provider '${provider}': ${msg}`);
+    }
 
     // If an mcpServers config is provided in the agent config, convert to functions
     const mcpFunctions = await initializeMCPServers(agentConfigData);
@@ -328,4 +217,21 @@ const parseAgentConfig = async (
 export { 
   parseAgentConfig,
   parseCrewConfig
-};
+};
+
+function resolveApiKey(varName: string): string | undefined {
+  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 as any)?.[varName];
+  } catch {
+    return undefined;
+  }
+}