@amitdeshmukh/ax-crew 8.7.3 → 9.0.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { AxCrew } from './agents/index.js';
 import { AxCrewFunctions } from './functions/index.js';
 import type { AxCrewConfig, AxCrewOptions, AgentConfig, AgentExecutionMode, AxCrewAxAgentOptions } from './types.js';
-import type { UsageCost, AggregatedMetrics, AggregatedCosts, StateInstance, FunctionRegistryType, ACEConfig, ACETeacherConfig, ACEPersistenceConfig, ACEOptionsConfig, ACEMetricConfig } from './types.js';
+import type { UsageCost, AggregatedMetrics, AggregatedCosts, StateInstance, FunctionRegistryType, DeferredToolsConfig, ACEConfig, ACETeacherConfig, ACEPersistenceConfig, ACEOptionsConfig, ACEMetricConfig } from './types.js';
 /**
  * Metrics types and helpers for request counts, token usage, and estimated cost.
  *
@@ -29,4 +29,4 @@ 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 AgentExecutionMode, type AxCrewAxAgentOptions, type AxCrewConfig, type AxCrewOptions, type StateInstance, type UsageCost, type ACEConfig, type ACETeacherConfig, type ACEPersistenceConfig, type ACEOptionsConfig, type ACEMetricConfig, };
+_AxCrewFunctions as AxCrewFunctions, FunctionRegistryType, type AggregatedMetrics, type AggregatedCosts, type AgentConfig, type AgentExecutionMode, type AxCrewAxAgentOptions, type AxCrewConfig, type AxCrewOptions, type StateInstance, type UsageCost, type DeferredToolsConfig, type ACEConfig, type ACETeacherConfig, type ACEPersistenceConfig, type ACEOptionsConfig, type ACEMetricConfig, };

package/dist/types.d.ts

@@ -173,6 +173,21 @@ interface ACEConfig {
     metric?: ACEMetricConfig;
     compileOnStart?: boolean;
 }
+/**
+ * Configuration for deferred tool loading.
+ * When an agent has many tools, only core tools are visible by default.
+ * A search_tools meta-function lets the LLM discover and activate deferred tools on demand.
+ */
+interface DeferredToolsConfig {
+    /** Enable deferred tool loading. Default: auto (true when tool count > threshold) */
+    enabled?: boolean;
+    /** Tool count threshold to activate deferred mode. Default: 20 */
+    threshold?: number;
+    /** Max tools returned per search. Default: 10 */
+    maxSearchResults?: number;
+    /** Tool names to always keep active (bypasses deferral) */
+    coreTools?: string[];
+}
 /**
  * The configuration for an agent.
  *
@@ -234,6 +249,8 @@ interface AgentConfig {
     mcpServers?: Record<string, MCPTransportConfig>;
     /** Optional AxACE configuration to enable optimization for this agent */
     ace?: ACEConfig;
+    /** Deferred tool loading — reduces token usage when an agent has many tools */
+    deferredTools?: DeferredToolsConfig;
 }
 /**
  * The configuration object for an AxCrew instance.
@@ -290,4 +307,4 @@ interface AxCrewOptions {
         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, type ACEConfig, type ACEMetricConfig, type ACEOptionsConfig, type ACEPersistenceConfig, type ACETeacherConfig };
+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, type DeferredToolsConfig, type ACEConfig, type ACEMetricConfig, type ACEOptionsConfig, type ACEPersistenceConfig, type ACETeacherConfig };

package/examples/graphjin-database-agent.ts

@@ -5,27 +5,17 @@ import dotenv from "dotenv";
 dotenv.config();
 
 /**
- * GraphJin MCP Server Example
+ * GraphJin MCP Server Example — with deferred tool loading
  *
- * This example demonstrates how to use GraphJin as an MCP server to give AI agents
- * direct access to databases. GraphJin auto-discovers your database schema and provides
- * tools for querying, schema exploration, and more.
+ * This example demonstrates deferred tool loading: when an agent has many
+ * MCP tools, only core tools + a search_tools meta-function are visible
+ * to the LLM. The LLM discovers and activates deferred tools on demand.
  *
  * Setup:
  * 1. Install GraphJin: npm install -g graphjin
  * 2. Start GraphJin demo server: graphjin serve --demo --path /path/to/graphjin/examples/webshop
  * 3. GraphJin will start on http://localhost:8080
  * 4. The MCP proxy connects to it via stdio
- *
- * Alternative setup (direct mode):
- * If you have a GraphJin config, you can use direct mode without a running server:
- * - Use command: "graphjin" with args: ["mcp", "--demo", "--path", "/path/to/config"]
- *
- * Note: There is currently a schema validation issue between GraphJin and Ax.
- * GraphJin's array parameters don't include "items" definitions in their JSON Schema,
- * which Ax requires per JSON Schema spec. A fix is needed in either:
- * - GraphJin's mcp-go integration (recommended)
- * - Or Ax's schema validation (less recommended)
  */
 
 // Define the crew configuration
@@ -33,50 +23,68 @@ const config = {
   crew: [
     {
       name: "DatabaseAgent",
-      description: "An agent with direct database access via GraphJin. Can query products, customers, orders, and explore database schema.",
-      signature: 'dbQuery:string "a database question or query request" -> dbResult:string "the query result or answer"',
-      provider: "google-gemini",
-      providerKeyName: "GEMINI_API_KEY",
+      description: "An agent with direct database access via GraphJin. Can explore database schema, query tables, list save and run workflows in the builtin JS sandbox etc.",
+      definition: `You answer questions by querying databases via a GraphJin server.
+You have resource docs available (query syntax, mutation syntax, workflow guides, JS runtime API). Read them to learn the GraphJin DSL — it differs from standard GraphQL.
+Use search_tools to discover additional action tools not shown by default.
+
+STRATEGY:
+1. Check first — call list_workflows and list_saved_queries. If a match exists, execute it and skip to step 5.
+
+2. Learn the environment:
+   a. Read resource docs (get_query_syntax, get_js_runtime_api) to understand the DSL and runtime API.
+   b. Call list_tables + describe_table for schema details. Use explore_relationships or find_path if joins are needed.
+
+3. Build and validate:
+   a. Author a JavaScript workflow using gj.tools.* for server-side computation. Design it with input variables — never hardcode values.
+   b. IMPORTANT: The database enforces a low default row limit (e.g. 20) on ALL queries including aggregations. Your workflow MUST paginate using cursor-based pagination (first: 20, after: cursor) to fetch complete results. Use first: 20 (not higher — the server silently caps it). Loop until the cursor stops changing or returns null.
+   c. Call execute_graphql first to validate query shape and results before embedding in a workflow.
+
+4. Save and run — call save_workflow with a descriptive snake_case name and tags, then execute_workflow.
+
+5. If a query fails, do not retry the same query. Call fix_query_error or explain_query to diagnose, then fix and re-save.
+
+6. Synthesize the answer from results.`,
+      signature: 'question:string "a natural language question about the database" -> answer:string "the answer to the question"',
+      provider: "anthropic",
+      providerKeyName: "ANTHROPIC_API_KEY",
       ai: {
-        model: "gemini-2.5-pro",
+        model: "claude-sonnet-4-6",
         temperature: 0,
         stream: false
       },
       options: {
         debug: true
       },
-      // MCP Server Configuration for GraphJin
-      // This assumes you have graphjin running on http://localhost:8080
-      // Start it with: graphjin serve --demo --path /path/to/graphjin/examples/webshop
       mcpServers: {
         "graphjin": {
           "command": "graphjin",
-          // Proxy mode: connects to a running GraphJin HTTP server
           "args": ["mcp", "--server", "http://localhost:8080"]
-
-          // Direct mode (alternative - uncomment to use):
-          // Runs GraphJin MCP server directly with demo database
-          // "args": ["mcp", "--demo", "--path", "/path/to/your/graphjin/config"]
         }
       },
+      deferredTools: {
+        enabled: true,
+        threshold: 5,
+      },
     },
     {
       name: "ManagerAgent",
       description: "Orchestrates database queries and analysis tasks",
-      prompt: `You are a manager agent that helps users get insights from databases.
-You can delegate to the DatabaseAgent for any database queries or schema exploration.
-Keep your responses clear and well-formatted.`,
+      definition: `You are an orchestrator that routes questions to specialized agents.
+Delegate each question to the most relevant agent in a SINGLE call — do not break questions into sub-queries.
+The sub-agent will handle all the steps internally. Your job is to route and synthesize, not to decompose.
+If multiple agents are needed, call them and combine their answers.`,
       signature: 'question:string "a question to be answered" -> answer:string "the answer to the question"',
-      provider: "google-gemini",
-      providerKeyName: "GEMINI_API_KEY",
+      provider: "anthropic",
+      providerKeyName: "ANTHROPIC_API_KEY",
       ai: {
-        model: "gemini-2.5-pro",
+        model: "claude-sonnet-4-6",
         maxTokens: 2000,
         temperature: 0,
         stream: false
       },
       options: {
-        debug: true,
+        debug: false,
       },
       agents: ["DatabaseAgent"]
     }
@@ -86,50 +94,53 @@ Keep your responses clear and well-formatted.`,
 // Create a new instance of AxCrew with the config
 const crew = new AxCrew(config as AxCrewConfig);
 
-// Example queries to try:
-const queries = [
-  "What tables are available in the database?",
-  "Show me the schema for the products table",
-  "How many products are in the database?",
-  "List the top 5 most expensive products",
-  "What customers have placed orders in the last 30 days?"
-];
+const userQuery = "which products had the most refund requests and why?";
 
-// Use a simpler query for testing
-const userQuery: string = queries[0]; // "What tables are available in the database?"
-
-console.log(`\n\nQuestion: ${userQuery}`);
+console.log(`\nQuestion: ${userQuery}`);
 
 const main = async (): Promise<void> => {
+  const timers: Record<string, number> = {};
+
   try {
-    // Initialize agents inside main so initialization failures are handled here.
+    // --- Setup phase ---
+    const t0 = performance.now();
     await crew.addAllAgents();
+    timers["setup"] = performance.now() - t0;
 
     const managerAgent = crew.agents?.get("ManagerAgent");
-    const databaseAgent = crew.agents?.get("DatabaseAgent");
 
     if (!managerAgent) {
       throw new Error("Failed to initialize ManagerAgent");
     }
 
+    // --- Query phase ---
+    console.log("\n--- Starting query ---\n");
+    const t1 = performance.now();
+
     const managerResponse = await managerAgent.forward({
       question: userQuery,
     });
 
+    timers["query"] = performance.now() - t1;
+    timers["total"] = performance.now() - t0;
+
+    // --- Results ---
     console.log(`\nAnswer: ${JSON.stringify(managerResponse?.answer, null, 2)}`);
 
-    // Print metrics
-    console.log("\nMetrics:\n+++++++++++++++++++++++++++++++++");
-    console.log("Manager Agent Metrics:", JSON.stringify((managerAgent as any)?.getMetrics?.(), null, 2));
-    console.log("Database Agent Metrics:", JSON.stringify((databaseAgent as any)?.getMetrics?.(), null, 2));
-    console.log("Crew Metrics:", JSON.stringify((crew as any)?.getCrewMetrics?.(), null, 2));
+    // --- Timing & Metrics ---
+    console.log("\n--- Performance ---");
+    console.log(`  Setup:  ${(timers["setup"]! / 1000).toFixed(2)}s`);
+    console.log(`  Query:  ${(timers["query"]! / 1000).toFixed(2)}s`);
+    console.log(`  Total:  ${(timers["total"]! / 1000).toFixed(2)}s`);
+
+    console.log("\n--- Metrics ---");
+    console.log(JSON.stringify((crew as any)?.getCrewMetrics?.(), null, 2));
   } catch (error) {
-    console.error("\n❌ Error:", error);
+    console.error("\nError:", error);
     console.error("\nTroubleshooting:");
     console.error("1. Make sure GraphJin is running: graphjin serve --demo --path /path/to/graphjin/examples/webshop");
     console.error("2. Check that GraphJin is accessible at http://localhost:8080");
     console.error("3. Verify graphjin is installed: which graphjin");
-    console.error("4. Note: There's a known schema validation issue - see comments in the code");
     throw error;
   } finally {
     crew.destroy();
@@ -138,10 +149,10 @@ const main = async (): Promise<void> => {
 
 main()
   .then(() => {
-    console.log("\n✅ Done");
+    console.log("\nDone");
     process.exit(0);
   })
   .catch((error) => {
-    console.error("\n❌ Fatal error:", error);
+    console.error("\nFatal error:", error);
     process.exit(1);
   });

package/examples/write-post-and-publish-to-wordpress.ts

@@ -93,7 +93,7 @@ const main = async () => {
   // Refer to https://github.com/WP-API/Basic-Auth?tab=readme-ov-file
   
   // Set environment variables
-  crew.state.set("env", {
+  crew.crewState.set("env", {
     WORDPRESS_URL: "http://my-wordpress-site.com",
     WORDPRESS_USERNAME: "my-username",
     WORDPRESS_PASSWORD: "my-password"

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "8.7.3",
+  "version": "9.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",

package/src/agents/agentConfig.ts

@@ -54,7 +54,7 @@ const initializeMCPServers = async (agentConfigData: AgentConfig): Promise<AxFun
 
   let initializedClients: AxMCPClient[] = [];
   const functions: AxFunction[] = [];
-  
+
   try {
     for (const [mcpServerName, mcpServerConfig] of Object.entries(mcpServers)) {
       let transport;
@@ -68,7 +68,7 @@ const initializeMCPServers = async (agentConfigData: AgentConfig): Promise<AxFun
         transport = new AxMCPHTTPSSETransport(mcpServerConfig.sseUrl);
       } else if (isStreambleHTTPTransport(mcpServerConfig)) {
         transport = new AxMCPStreambleHTTPTransport(mcpServerConfig.mcpEndpoint, mcpServerConfig.options);
-      } else {  
+      } else {
         throw new Error(`Unsupported transport type: ${JSON.stringify(mcpServerConfig)}`);
       }
 
@@ -77,20 +77,21 @@ const initializeMCPServers = async (agentConfigData: AgentConfig): Promise<AxFun
       initializedClients.push(mcpClient);
       // Normalize MCP tool schemas: some MCP servers omit `parameters` for
       // zero-arg tools, but providers like Gemini require a valid schema.
-      let mcpFns = mcpClient.toFunction().map(fn => ({
+      const allFns = mcpClient.toFunction().map(fn => ({
         ...fn,
         parameters: fn.parameters ?? { type: 'object' as const, properties: {} },
       }));
 
-      // Filter to allowlisted tools if specified
+      // Filter to allowlisted tools if specified, but always include resource_* functions
       if (mcpServerConfig.tools && mcpServerConfig.tools.length > 0) {
         const allowed = new Set(mcpServerConfig.tools);
-        mcpFns = mcpFns.filter(fn => allowed.has(fn.name));
+        const filtered = allFns.filter(fn => allowed.has(fn.name) || fn.name.startsWith('resource_'));
+        functions.push(...filtered);
+      } else {
+        functions.push(...allFns);
       }
-
-      functions.push(...mcpFns);
     }
-    
+
     return functions;
   } catch (error) {
     initializedClients = [];
@@ -217,6 +218,9 @@ const parseAgentConfig = async (
     const executionMode: AgentExecutionMode =
       agentConfigData.executionMode === 'axagent' ? 'axagent' : 'axgen';
     
+    // Track MCP function names for deferred tool loading
+    const mcpFunctionNames = new Set(mcpFunctions.map(fn => fn.name));
+
     // Return AI instance and Agent parameters
     return {
       ai: aiInstance,
@@ -227,9 +231,11 @@ const parseAgentConfig = async (
       definition: (agentConfigData as any).definition ?? (agentConfigData as any).prompt,
       signature: agentConfigData.signature,
       functions: agentFunctions,
+      mcpFunctionNames,
       subAgentNames: agentConfigData.agents || [],
       examples: agentConfigData.examples || [],
       tracker: costTracker,
+      deferredTools: (agentConfigData as any).deferredTools,
       debug: (agentConfigData as any).options?.debug ?? (agentConfigData as any).debug ?? false,
     };
   } catch (error) {