@amitdeshmukh/ax-crew 5.0.0 → 7.0.0

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, CrewConfigInput, 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;
@@ -39,21 +39,39 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
     resetMetrics(): void;
 }
 /**
- * Represents a crew of agents with shared state functionality.
+ * AxCrew orchestrates a set of Ax agents that share state,
+ * tools (functions), optional MCP servers, streaming, and a built-in metrics
+ * registry for tokens, requests, and estimated cost.
+ *
+ * Typical usage:
+ *  const crew = new AxCrew(config, AxCrewFunctions)
+ *  await crew.addAllAgents()
+ *  const planner = crew.agents?.get("Planner")
+ *  const res = await planner?.forward({ task: "Plan something" })
+ *
+ * Key behaviors:
+ * - Validates and instantiates agents from a config-first model
+ * - Shares a mutable state object across all agents in the crew
+ * - Supports sub-agents and a function registry per agent
+ * - Tracks per-agent and crew-level metrics via MetricsRegistry
+ * - Provides helpers to add agents (individually, a subset, or all) and
+ *   to reset metrics/costs when needed
  */
 declare class AxCrew {
     private crewConfig;
+    private options?;
     functionsRegistry: FunctionRegistryType;
     crewId: string;
     agents: Map<string, StatefulAxAgent> | null;
     state: StateInstance;
     /**
      * Creates an instance of AxCrew.
-     * @param {CrewConfigInput} crewConfig - Either a path to the agent config file or a JSON object with crew configuration.
+     * @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: CrewConfigInput, 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

@@ -176,27 +176,45 @@ class StatefulAxAgent extends AxAgent {
     }
 }
 /**
- * Represents a crew of agents with shared state functionality.
+ * AxCrew orchestrates a set of Ax agents that share state,
+ * tools (functions), optional MCP servers, streaming, and a built-in metrics
+ * registry for tokens, requests, and estimated cost.
+ *
+ * Typical usage:
+ *  const crew = new AxCrew(config, AxCrewFunctions)
+ *  await crew.addAllAgents()
+ *  const planner = crew.agents?.get("Planner")
+ *  const res = await planner?.forward({ task: "Plan something" })
+ *
+ * Key behaviors:
+ * - Validates and instantiates agents from a config-first model
+ * - Shares a mutable state object across all agents in the crew
+ * - Supports sub-agents and a function registry per agent
+ * - Tracks per-agent and crew-level metrics via MetricsRegistry
+ * - Provides helpers to add agents (individually, a subset, or all) and
+ *   to reset metrics/costs when needed
  */
 class AxCrew {
     crewConfig;
+    options;
     functionsRegistry = {};
     crewId;
     agents;
     state;
     /**
      * Creates an instance of AxCrew.
-     * @param {CrewConfigInput} crewConfig - Either a path to the agent config file or a JSON object with crew configuration.
+     * @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');
         }
         // Validate each agent in the crew
-        crewConfig.crew.forEach(agent => {
+        crewConfig.crew.forEach((agent) => {
             if (!agent.name || agent.name.trim() === '') {
                 throw new Error('Agent name cannot be empty');
             }
@@ -204,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
@@ -217,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/functions/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Built-in function registry for AxCrew agents.
+ *
+ * Contains common utility tools/functions that can be referenced by name from
+ * agent configs (e.g., "functions": ["CurrentDateTime", "DaysBetweenDates"]).
+ * You can pass this object to the AxCrew constructor or merge with your
+ * own registry.
+ * Example:
+ * const crew = new AxCrew(config, AxCrewFunctions); or
+ * const crew = new AxCrew(config, { ...AxCrewFunctions, ...myFunctions });
+ */
 declare const AxCrewFunctions: {
     CurrentDateTime: import("@ax-llm/ax").AxFunction;
     DaysBetweenDates: import("@ax-llm/ax").AxFunction;

package/dist/functions/index.js

@@ -1,5 +1,15 @@
 import { CurrentDateTime, DaysBetweenDates } from './dateTime.js';
-// Built-in functions
+/**
+ * Built-in function registry for AxCrew agents.
+ *
+ * Contains common utility tools/functions that can be referenced by name from
+ * agent configs (e.g., "functions": ["CurrentDateTime", "DaysBetweenDates"]).
+ * You can pass this object to the AxCrew constructor or merge with your
+ * own registry.
+ * Example:
+ * const crew = new AxCrew(config, AxCrewFunctions); or
+ * const crew = new AxCrew(config, { ...AxCrewFunctions, ...myFunctions });
+ */
 const AxCrewFunctions = {
     CurrentDateTime,
     DaysBetweenDates

package/dist/index.d.ts

@@ -1,15 +1,32 @@
 import { AxCrew } from './agents/index.js';
 import { AxCrewFunctions } from './functions/index.js';
-import type { CrewConfigInput, AgentConfig } from './types.js';
+import type { AxCrewConfig, AgentConfig } from './types.js';
 import type { UsageCost, AggregatedMetrics, AggregatedCosts, StateInstance, FunctionRegistryType } from './types.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';
 /**
- * The configuration for an AxCrew.
- *
- * @property {AgentConfig[]} crew - The agents that make up the crew.
+ * Create and manage a crew of Ax agents that share state and metrics.
+ * See the `AxCrew` class for full documentation.
+ */
+declare const _AxCrew: typeof AxCrew;
+/**
+ * Built-in function registry with common tools that can be referenced by name
+ * from agent configs, or extended with your own functions.
  */
-interface AxCrewConfig {
-    crew: AgentConfig[];
-}
-export { AxCrew, AxCrewFunctions, FunctionRegistryType, type AggregatedMetrics, type AggregatedCosts, type AgentConfig, type CrewConfigInput, type AxCrewConfig, type StateInstance, type UsageCost, };
+declare const _AxCrewFunctions: typeof 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, FunctionRegistryType, type AggregatedMetrics, type AggregatedCosts, type AgentConfig, type AxCrewConfig, type StateInstance, type UsageCost, };

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,56 @@ 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 };
+}
+/**
+ * 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/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: {