@amitdeshmukh/ax-crew 8.4.0 → 8.5.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [8.5.0] - 2026-03-13
+
+### Added
+- **Lazy agent initialization** via `crew.addLazyAgent(agentName)`. Builds the tool schema immediately from the crew config (name, description, signature) but defers expensive initialization (MCP server startup, AI client creation) until the Manager actually delegates to the agent. Ideal for sub-agents with stdio MCP servers that spawn a process on init — avoids the cold-start penalty on every request when the agent isn't needed.
+
 ## [8.4.0] - 2026-03-05
 
 ### Added

package/dist/agents/index.d.ts

@@ -1,4 +1,4 @@
-import { AxAgent, AxAI } from "@ax-llm/ax";
+import { AxAgent, AxAI, AxSignature as AxSignatureClass } from "@ax-llm/ax";
 import type { AxSignature, AxAgentic, AxFunction, AxProgramForwardOptions, AxProgramStreamingForwardOptions, AxGenStreamingOut } from "@ax-llm/ax";
 import type { StateInstance, FunctionRegistryType, UsageCost, AxCrewConfig, AxCrewOptions, MCPTransportConfig, ACEConfig, AgentExecutionMode, AxCrewAxAgentOptions } from "../types.js";
 declare class StatefulAxAgent extends AxAgent<any, any> {
@@ -113,6 +113,35 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
      */
     private composeInstructionWithPlaybook;
 }
+/**
+ * Lightweight proxy that stands in for a real agent in the crew's agent map.
+ * It exposes the same `getFunction()` interface (built from the crew config)
+ * but defers the expensive `createAgent()` call — and therefore MCP server
+ * startup — until the Manager actually delegates to it.
+ *
+ * Usage: `crew.addLazyAgent("CreateChart")` instead of `crew.addAgent("CreateChart")`
+ */
+declare class LazyStatefulAxAgent {
+    private realAgent;
+    private crewRef;
+    private agentName;
+    private description;
+    private signatureStr;
+    private func;
+    private _id;
+    constructor(crewRef: any, agentName: string, crewConfig: AxCrewConfig);
+    private resolve;
+    getFunction(): AxFunction;
+    getSignature(): AxSignatureClass<Record<string, any>, Record<string, any>>;
+    getId(): string;
+    setId(id: string): void;
+    getTraces(): any[];
+    setDemos(): void;
+    getUsage(): any[];
+    resetUsage(): void;
+    forward(...args: any[]): Promise<any>;
+    streamingForward(...args: any[]): any;
+}
 /**
  * AxCrew orchestrates a set of Ax agents that share state,
  * tools (functions), optional MCP servers, streaming, and a built-in metrics
@@ -160,6 +189,18 @@ declare class AxCrew {
      * @param {string} agentName - The name of the agent to add.
      */
     addAgent(agentName: string): Promise<void>;
+    /**
+     * Adds a lazy agent to the crew by name.
+     * The agent's tool schema is built immediately from the crew config,
+     * but the expensive initialization (MCP servers, AI client, etc.) is
+     * deferred until the Manager actually delegates to this agent.
+     *
+     * Use this for sub-agents that may not be needed on every request
+     * (e.g., agents with stdio MCP servers that spawn a process).
+     *
+     * @param {string} agentName - The name of the agent to add lazily.
+     */
+    addLazyAgent(agentName: string): void;
     /**
      * Sets up agents in the crew by name.
      * For an array of Agent names provided, it adds
@@ -221,5 +262,5 @@ declare class AxCrew {
      */
     resetCrewMetrics(): void;
 }
-export { AxCrew };
+export { AxCrew, LazyStatefulAxAgent };
 export type { StatefulAxAgent };

package/dist/agents/index.js

@@ -1,5 +1,5 @@
 import { v4 as uuidv4 } from "uuid";
-import { AxAgent, AxGen } from "@ax-llm/ax";
+import { AxAgent, AxGen, AxSignature as AxSignatureClass } from "@ax-llm/ax";
 import { createState } from "../state/index.js";
 import { parseCrewConfig, parseAgentConfig } from "./agentConfig.js";
 import { MetricsRegistry } from "../metrics/index.js";
@@ -515,6 +515,81 @@ class StatefulAxAgent extends AxAgent {
         }
     }
 }
+/**
+ * Lightweight proxy that stands in for a real agent in the crew's agent map.
+ * It exposes the same `getFunction()` interface (built from the crew config)
+ * but defers the expensive `createAgent()` call — and therefore MCP server
+ * startup — until the Manager actually delegates to it.
+ *
+ * Usage: `crew.addLazyAgent("CreateChart")` instead of `crew.addAgent("CreateChart")`
+ */
+class LazyStatefulAxAgent {
+    realAgent = null;
+    crewRef; // AxCrew — forward-declared to avoid circular ref
+    agentName;
+    description;
+    signatureStr;
+    func;
+    _id = "lazy";
+    constructor(crewRef, agentName, crewConfig) {
+        this.crewRef = crewRef;
+        this.agentName = agentName;
+        const agentDef = parseCrewConfig(crewConfig).crew.find((a) => a.name === agentName);
+        if (!agentDef) {
+            throw new Error(`Agent "${agentName}" not found in crew config`);
+        }
+        this.description = agentDef.description;
+        this.signatureStr = agentDef.signature;
+        // Build the tool schema from the signature's input fields
+        const sig = new AxSignatureClass(this.signatureStr);
+        const parameters = sig.toInputJSONSchema();
+        this.func = {
+            name: agentName.replace(/[^a-zA-Z0-9_]/g, "_").toLowerCase(),
+            description: this.description,
+            parameters,
+            func: async (args) => {
+                const agent = await this.resolve();
+                return agent.forward(args);
+            },
+        };
+    }
+    async resolve() {
+        if (!this.realAgent) {
+            const agent = await this.crewRef.createAgent(this.agentName);
+            agent.setId(this._id);
+            this.realAgent = agent;
+        }
+        return this.realAgent;
+    }
+    // AxAgentic interface
+    getFunction() {
+        return this.func;
+    }
+    getSignature() {
+        return new AxSignatureClass(this.signatureStr);
+    }
+    // AxProgrammable / AxTunable stubs
+    getId() { return this._id; }
+    setId(id) { this._id = id; }
+    getTraces() { return this.realAgent?.getTraces() ?? []; }
+    setDemos() { }
+    getUsage() { return this.realAgent?.getUsage() ?? []; }
+    resetUsage() { this.realAgent?.resetUsage(); }
+    // Forward / streaming — resolve on demand
+    async forward(...args) {
+        const agent = await this.resolve();
+        return agent.forward(...args);
+    }
+    streamingForward(...args) {
+        // Must be sync to match the interface, so we wrap in an async generator
+        const self = this;
+        async function* lazyStream() {
+            const agent = await self.resolve();
+            yield* agent.streamingForward(...args);
+        }
+        return lazyStream();
+    }
+}
 /**
  * AxCrew orchestrates a set of Ax agents that share state,
  * tools (functions), optional MCP servers, streaming, and a built-in metrics
@@ -689,6 +764,25 @@ class AxCrew {
             throw new Error(`Failed to add agent ${agentName}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Adds a lazy agent to the crew by name.
+     * The agent's tool schema is built immediately from the crew config,
+     * but the expensive initialization (MCP servers, AI client, etc.) is
+     * deferred until the Manager actually delegates to this agent.
+     *
+     * Use this for sub-agents that may not be needed on every request
+     * (e.g., agents with stdio MCP servers that spawn a process).
+     *
+     * @param {string} agentName - The name of the agent to add lazily.
+     */
+    addLazyAgent(agentName) {
+        if (!this.agents) {
+            this.agents = new Map();
+        }
+        if (!this.agents.has(agentName)) {
+            this.agents.set(agentName, new LazyStatefulAxAgent(this, agentName, this.crewConfig));
+        }
+    }
     /**
      * Sets up agents in the crew by name.
      * For an array of Agent names provided, it adds
@@ -917,4 +1011,4 @@ class AxCrew {
         MetricsRegistry.reset({ crewId: this.crewId });
     }
 }
-export { AxCrew };
+export { AxCrew, LazyStatefulAxAgent };

package/examples/run-crew-workflow.ts

@@ -26,7 +26,7 @@ The saved workflow will be reusable by future queries asking similar questions.`
       provider: 'anthropic',
       providerKeyName: 'ANTHROPIC_API_KEY',
       ai: {
-        model: 'claude-sonnet-4-6',
+        model: 'claude-haiku-4-5',
         temperature: 0,
       },
       options: {
@@ -54,7 +54,7 @@ async function main() {
   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.';
+    'show me all the orders that Brett Kowalski was involved with';
   console.log(`\nQuery: ${query}\n`);
 
   const result = await agent.forward({

package/package.json

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

@@ -1,5 +1,5 @@
 import { v4 as uuidv4 } from "uuid";
-import { AxAgent, AxAI, AxGen } from "@ax-llm/ax";
+import { AxAgent, AxAI, AxGen, AxSignature as AxSignatureClass } from "@ax-llm/ax";
 
 import type {
   AxSignature,
@@ -697,6 +697,94 @@ class StatefulAxAgent extends AxAgent<any, any> {
   }
 }
 
+/**
+ * Lightweight proxy that stands in for a real agent in the crew's agent map.
+ * It exposes the same `getFunction()` interface (built from the crew config)
+ * but defers the expensive `createAgent()` call — and therefore MCP server
+ * startup — until the Manager actually delegates to it.
+ *
+ * Usage: `crew.addLazyAgent("CreateChart")` instead of `crew.addAgent("CreateChart")`
+ */
+class LazyStatefulAxAgent {
+  private realAgent: StatefulAxAgent | null = null;
+  private crewRef: any; // AxCrew — forward-declared to avoid circular ref
+  private agentName: string;
+  private description: string;
+  private signatureStr: string;
+  private func: AxFunction;
+  private _id: string = "lazy";
+
+  constructor(crewRef: any, agentName: string, crewConfig: AxCrewConfig) {
+    this.crewRef = crewRef;
+    this.agentName = agentName;
+
+    const agentDef = parseCrewConfig(crewConfig).crew.find(
+      (a) => a.name === agentName
+    );
+    if (!agentDef) {
+      throw new Error(`Agent "${agentName}" not found in crew config`);
+    }
+
+    this.description = agentDef.description;
+    this.signatureStr = agentDef.signature as string;
+
+    // Build the tool schema from the signature's input fields
+    const sig = new AxSignatureClass(this.signatureStr);
+    const parameters = sig.toInputJSONSchema();
+
+    this.func = {
+      name: agentName.replace(/[^a-zA-Z0-9_]/g, "_").toLowerCase(),
+      description: this.description,
+      parameters,
+      func: async (args?: any) => {
+        const agent = await this.resolve();
+        return agent.forward(args);
+      },
+    };
+  }
+
+  private async resolve(): Promise<StatefulAxAgent> {
+    if (!this.realAgent) {
+      const agent = await this.crewRef.createAgent(this.agentName) as StatefulAxAgent;
+      agent.setId(this._id);
+      this.realAgent = agent;
+    }
+    return this.realAgent!;
+  }
+
+  // AxAgentic interface
+  getFunction(): AxFunction {
+    return this.func;
+  }
+
+  getSignature() {
+    return new AxSignatureClass(this.signatureStr);
+  }
+
+  // AxProgrammable / AxTunable stubs
+  getId(): string { return this._id; }
+  setId(id: string): void { this._id = id; }
+  getTraces(): any[] { return this.realAgent?.getTraces() ?? []; }
+  setDemos(): void { /* no-op until resolved */ }
+  getUsage(): any[] { return this.realAgent?.getUsage() ?? []; }
+  resetUsage(): void { this.realAgent?.resetUsage(); }
+
+  // Forward / streaming — resolve on demand
+  async forward(...args: any[]): Promise<any> {
+    const agent = await this.resolve();
+    return (agent as any).forward(...args);
+  }
+  streamingForward(...args: any[]): any {
+    // Must be sync to match the interface, so we wrap in an async generator
+    const self = this;
+    async function* lazyStream() {
+      const agent = await self.resolve();
+      yield* (agent as any).streamingForward(...args);
+    }
+    return lazyStream();
+  }
+}
+
 /**
  * AxCrew orchestrates a set of Ax agents that share state,
  * tools (functions), optional MCP servers, streaming, and a built-in metrics
@@ -912,6 +1000,29 @@ class AxCrew {
     }
   }
 
+  /**
+   * Adds a lazy agent to the crew by name.
+   * The agent's tool schema is built immediately from the crew config,
+   * but the expensive initialization (MCP servers, AI client, etc.) is
+   * deferred until the Manager actually delegates to this agent.
+   *
+   * Use this for sub-agents that may not be needed on every request
+   * (e.g., agents with stdio MCP servers that spawn a process).
+   *
+   * @param {string} agentName - The name of the agent to add lazily.
+   */
+  addLazyAgent(agentName: string): void {
+    if (!this.agents) {
+      this.agents = new Map<string, StatefulAxAgent>();
+    }
+    if (!this.agents.has(agentName)) {
+      this.agents.set(
+        agentName,
+        new LazyStatefulAxAgent(this, agentName, this.crewConfig) as any
+      );
+    }
+  }
+
   /**
    * Sets up agents in the crew by name.
    * For an array of Agent names provided, it adds
@@ -1166,5 +1277,5 @@ class AxCrew {
   }
 }
 
-export { AxCrew };
+export { AxCrew, LazyStatefulAxAgent };
 export type { StatefulAxAgent };