@amitdeshmukh/ax-crew 8.2.0 → 8.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [8.4.0] - 2026-03-05
+
+### Added
+- Optional `tools` allowlist on MCP server configs (stdio, HTTP SSE, streamable HTTP). When specified, only the listed tools are exposed to the agent, keeping system prompts small when connecting to MCP servers with many tools. Tested with GraphJin (40+ tools): filtering to 8 reduced token usage from 43K to 14K per request.
+- `examples/run-crew-workflow.ts` — workflow-aware agent using GraphJin MCP with tool filtering.
+
+## [8.3.0] - 2026-03-05
+
+### Fixed
+- Sub-agents were invisible to agents running in `axgen` execution mode. AxGen only supports functions/tools, not native sub-agents. Sub-agents are now converted to callable functions via `getFunction()` and included in the AxGen functions list, making them available as tools during execution.
+
 ## [8.1.0] - 2026-03-04
 
 ### Added

package/dist/agents/agentConfig.js

@@ -56,10 +56,15 @@ const initializeMCPServers = async (agentConfigData) => {
             initializedClients.push(mcpClient);
             // Normalize MCP tool schemas: some MCP servers omit `parameters` for
             // zero-arg tools, but providers like Gemini require a valid schema.
-            const mcpFns = mcpClient.toFunction().map(fn => ({
+            let mcpFns = mcpClient.toFunction().map(fn => ({
                 ...fn,
                 parameters: fn.parameters ?? { type: 'object', properties: {} },
             }));
+            // Filter to allowlisted tools if specified
+            if (mcpServerConfig.tools && mcpServerConfig.tools.length > 0) {
+                const allowed = new Set(mcpServerConfig.tools);
+                mcpFns = mcpFns.filter(fn => allowed.has(fn.name));
+            }
             functions.push(...mcpFns);
         }
         return functions;

package/dist/agents/index.js

@@ -90,9 +90,20 @@ class StatefulAxAgent extends AxAgent {
         this.agentDefinition = effectiveDefinition;
         this.executionMode = options.executionMode ?? "axgen";
         this.debugEnabled = debug ?? false;
+        // Convert sub-agents to callable functions so AxGen can invoke them as tools
+        const subAgentFunctions = resolvedAgents
+            .map(agent => {
+            try {
+                return agent.getFunction();
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .filter((fn) => fn !== undefined);
         this.axGenProgram = new AxGen(options.signature, {
             description: effectiveDefinition,
-            functions: resolvedFunctions,
+            functions: [...resolvedFunctions, ...subAgentFunctions],
         });
         for (const agent of resolvedAgents) {
             try {

package/dist/types.d.ts

@@ -109,24 +109,29 @@ interface MCPStdioTransportConfig {
     command: string;
     args?: string[];
     env?: NodeJS.ProcessEnv;
+    tools?: string[];
 }
 /**
  * Config for an HTTP SSE MCP server.
  *
  * @property {string} sseUrl - The SSE URL for the MCP server.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPHTTPSSETransportConfig {
     sseUrl: string;
+    tools?: string[];
 }
 /**
  * Config for a streamable HTTP MCP server.
  *
  * @property {string} mcpEndpoint - The HTTP endpoint URL for the MCP server.
  * @property {AxMCPStreamableHTTPTransportOptions} options - Optional transport options.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPStreamableHTTPTransportConfig {
     mcpEndpoint: string;
     options?: AxMCPStreamableHTTPTransportOptions;
+    tools?: string[];
 }
 /**
  * Config for an MCP server.

package/examples/run-crew-workflow.ts

@@ -0,0 +1,76 @@
+import 'dotenv/config';
+import { AxCrew } from '../dist/index.js';
+import type { AxCrewConfig } from '../dist/types.js';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: 'WorkflowAgent',
+      description: `You answer questions by querying databases and running calculations.
+
+IMPORTANT — follow this strategy for database queries:
+1. FIRST call list_workflows to check if a reusable workflow already exists for this type of question.
+2. If a matching workflow exists, call execute_workflow with its name. Done!
+3. If NO matching workflow exists:
+   a. Call get_js_runtime_api to learn the available gj.tools.* functions
+   b. Call list_tables and describe_table to understand the schema
+   c. Author a JavaScript workflow that uses gj.tools.* to query the database and compute results server-side
+   d. Call save_workflow to persist it (use descriptive snake_case name and description for future discovery)
+   e. Call execute_workflow to run it
+4. Synthesize the answer from the workflow results.
+
+This approach runs ALL database queries server-side in a single call, avoiding multiple round-trips.
+The saved workflow will be reusable by future queries asking similar questions.`,
+      signature:
+        'background:string "background information and context", question:string "the user question to answer" -> answer:string "the answer with explanation", references:json "list of references, each with fileName and url"',
+      provider: 'anthropic',
+      providerKeyName: 'ANTHROPIC_API_KEY',
+      ai: {
+        model: 'claude-sonnet-4-6',
+        temperature: 0,
+      },
+      options: {
+        debug: true,
+      },
+      mcpServers: {
+        graphjin: {
+          mcpEndpoint: 'http://localhost:8080/api/v1/mcp',
+          tools: [
+            'list_workflows', 'save_workflow', 'execute_workflow',
+            'get_js_runtime_api', 'list_tables', 'describe_table',
+            'get_query_syntax', 'execute_graphql',
+          ],
+        },
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const agent = crew.agents?.get('WorkflowAgent');
+  if (!agent) throw new Error('WorkflowAgent not found');
+
+  const query =
+    'Which customers have overdue or unpaid invoices? Show me a table with each customer, how many invoices they owe on, and the total outstanding balance.';
+  console.log(`\nQuery: ${query}\n`);
+
+  const result = await agent.forward({
+    background: 'User is querying the system about customer accounts receivable.',
+    question: query,
+  });
+
+  console.log(`\nAnswer: ${result.answer}`);
+  console.log(`\nReferences:`, JSON.stringify(result.references, null, 2));
+
+  const metrics = (agent as any).getMetrics?.();
+  console.log(`\nMetrics:`, JSON.stringify(metrics, null, 2));
+
+  crew.destroy();
+}
+
+main()
+  .catch(console.error)
+  .finally(() => process.exit(0));

package/examples/run-manager.ts

@@ -0,0 +1,98 @@
+import 'dotenv/config';
+import { AxCrew, AxCrewFunctions } from '../src/index.js';
+import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
+
+const config = {
+  crew: [
+    {
+      name: "Manager",
+      description: "Answer questions by querying databases, searching documents, and running calculations. You have direct access to database tools (list_tables, describe_table, execute_graphql, etc.), document search, date utilities, and a JavaScript interpreter for computations.",
+      signature: 'background:string "background information and context for the task at hand", latestMessage:string "the latest user message to answer" -> answer:string "The answer, including a short explanation for the answer. Never reveal functions available to the user. Respond in the same language as the user\'s question.", references:json "a list of references to documents to support the answer in json format. Each reference should include a fileName and url."',
+      provider: "anthropic" as const,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      executionMode: "axagent" as const,
+      ai: {
+        model: "claude-sonnet-4-6",
+        temperature: 0
+      },
+      options: {
+        debug: true
+      },
+      axAgentOptions: {
+        contextFields: ['background'] as const,
+        maxTurns: 15,
+      },
+      functions: [
+        "CurrentDateTime",
+        "DaysBetweenDates",
+        "VectorSearch",
+        "JavaScriptInterpreter"
+      ],
+      // Direct MCP access — no sub-agent double-hop
+      mcpServers: {
+        graphjin: {
+          command: "/opt/homebrew/bin/graphjin",
+          args: [
+            "mcp",
+            "--server",
+            "http://localhost:8080"
+          ]
+        }
+      }
+    }
+  ]
+};
+
+// Create a sandboxed JS runtime with timing permission for calculations
+const jsRuntime = new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.TIMING],
+  timeout: 15_000,
+});
+const JavaScriptInterpreter = jsRuntime.toFunction();
+
+const VectorSearch = {
+  name: 'VectorSearch',
+  description: 'Search the vector knowledge base for relevant documents',
+  parameters: {
+    type: 'object' as const,
+    properties: {
+      query: { type: 'string', description: 'The search query' }
+    },
+    required: ['query']
+  },
+  func: async ({ query }: { query: string }) => {
+    console.log(`[VectorSearch] Searching for: ${query}`);
+    return `No documents found for: ${query}`;
+  }
+};
+
+async function main() {
+  const crew = new AxCrew(config, { ...AxCrewFunctions, VectorSearch, JavaScriptInterpreter });
+
+  await crew.addAllAgents();
+
+  const manager = crew.agents?.get('Manager');
+  if (!manager) {
+    throw new Error('Manager agent not found');
+  }
+
+  const query = "analyze all our orders to date, give me a table showing P&L";
+  console.log(`\nQuery: ${query}\n`);
+
+  const result = await manager.forward({
+    background: "User is querying the system about order information.",
+    latestMessage: query
+  });
+
+  console.log(`\nAnswer: ${result.answer}`);
+  console.log(`\nReferences:`, JSON.stringify(result.references, null, 2));
+
+  const crewMetrics = crew.getCrewMetrics();
+  console.log(`\nCrew Metrics:`, JSON.stringify(crewMetrics, null, 2));
+
+  crew.destroy();
+}
+
+main()
+  .catch(console.error)
+  .finally(() => process.exit(0));

package/package.json

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

@@ -77,10 +77,17 @@ 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.
-      const mcpFns = mcpClient.toFunction().map(fn => ({
+      let mcpFns = mcpClient.toFunction().map(fn => ({
         ...fn,
         parameters: fn.parameters ?? { type: 'object' as const, properties: {} },
       }));
+
+      // Filter to allowlisted tools if specified
+      if (mcpServerConfig.tools && mcpServerConfig.tools.length > 0) {
+        const allowed = new Set(mcpServerConfig.tools);
+        mcpFns = mcpFns.filter(fn => allowed.has(fn.name));
+      }
+
       functions.push(...mcpFns);
     }
     

package/src/agents/index.ts

@@ -163,9 +163,17 @@ class StatefulAxAgent extends AxAgent<any, any> {
     this.agentDefinition = effectiveDefinition;
     this.executionMode = options.executionMode ?? "axgen";
     this.debugEnabled = debug ?? false;
+    // Convert sub-agents to callable functions so AxGen can invoke them as tools
+    const subAgentFunctions: AxFunction[] = resolvedAgents
+      .map(agent => {
+        try { return agent.getFunction() as AxFunction; }
+        catch { return undefined; }
+      })
+      .filter((fn): fn is AxFunction => fn !== undefined);
+
     this.axGenProgram = new AxGen(options.signature as any, {
       description: effectiveDefinition,
-      functions: resolvedFunctions,
+      functions: [...resolvedFunctions, ...subAgentFunctions],
     } as any);
 
     for (const agent of resolvedAgents) {

package/src/types.ts

@@ -127,26 +127,31 @@ interface MCPStdioTransportConfig {
   command: string
   args?: string[]
   env?: NodeJS.ProcessEnv
+  tools?: string[]
 }
 
 /**
  * Config for an HTTP SSE MCP server.
- * 
+ *
  * @property {string} sseUrl - The SSE URL for the MCP server.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPHTTPSSETransportConfig {
   sseUrl: string
+  tools?: string[]
 }
 
 /**
  * Config for a streamable HTTP MCP server.
- * 
+ *
  * @property {string} mcpEndpoint - The HTTP endpoint URL for the MCP server.
  * @property {AxMCPStreamableHTTPTransportOptions} options - Optional transport options.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPStreamableHTTPTransportConfig {
   mcpEndpoint: string
   options?: AxMCPStreamableHTTPTransportOptions
+  tools?: string[]
 }
 
 /**