@amitdeshmukh/ax-crew 8.4.0 → 8.6.0

package/.claude/skills/ax-crew/SKILL.md

@@ -0,0 +1,466 @@
+---
+name: ax-crew
+description: Guide for building multi-agent AI systems with ax-crew. Use when creating agent crews, configuring agents, using MCP servers, shared state, sub-agents, streaming, ACE learning, function registries, metrics/cost tracking, telemetry, or agent workflows with @amitdeshmukh/ax-crew.
+argument-hint: [topic]
+allowed-tools: Read, Grep, Glob
+---
+
+# ax-crew Library Guide
+
+ax-crew (`@amitdeshmukh/ax-crew`) is a TypeScript framework for building teams of AI agents with shared state, tools, streaming, MCP integration, and built-in metrics/cost tracking. It is powered by [AxLLM](https://axllm.dev) (`@ax-llm/ax`).
+
+**Package:** `@amitdeshmukh/ax-crew` (v8.5.0+)
+**Peer deps:** `@ax-llm/ax`, `@ax-llm/ax-tools`, `@opentelemetry/api` (optional)
+**Node.js:** >= 21
+
+## Installation
+
+```bash
+npm install @amitdeshmukh/ax-crew @ax-llm/ax @ax-llm/ax-tools
+```
+
+## Core Concepts
+
+- **Config-first:** Define agents in a JSON/TypeScript config object, instantiate on demand.
+- **Shared state:** Simple key/value store all agents can read/write via `crew.state`.
+- **Sub-agents:** Agents can delegate to other agents listed in their `agents` field.
+- **Functions (tools):** Register callable tools via a function registry, reference by name.
+- **Execution modes:** `axgen` (default, structured generation) or `axagent` (agentic loop with RLM).
+- **MCP:** Connect agents to external MCP servers (STDIO, HTTP SSE, Streamable HTTP).
+- **ACE:** Agentic Context Engineering - agents learn from human feedback at runtime.
+- **Metrics:** Per-agent and crew-level token usage, cost estimation, and request stats.
+
+## Quick Start
+
+```typescript
+import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Researcher",
+      description: "Finds information on a topic",
+      signature: 'query:string "research query" -> research:string "research findings"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      functions: ["CurrentDateTime"]
+    },
+    {
+      name: "Writer",
+      description: "Writes articles based on research",
+      signature: 'topic:string -> article:string',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0.7 },
+      agents: ["Researcher"]  // Writer can delegate to Researcher
+    }
+  ]
+};
+
+const crew = new AxCrew(config, AxCrewFunctions);
+await crew.addAllAgents();
+
+const writer = crew.agents?.get("Writer");
+const { article } = await writer.forward({ topic: "Quantum Computing" });
+console.log(article);
+
+// Metrics
+console.log(crew.getCrewMetrics());
+
+// Cleanup
+crew.destroy();
+```
+
+## Agent Configuration Reference
+
+Each agent in the `crew` array accepts these fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Unique agent name |
+| `description` | string | Yes | What the agent does |
+| `signature` | string | Yes | DSPy-format I/O schema: `input:type "desc" -> output:type "desc"` |
+| `provider` | string | Yes | LLM provider: `google-gemini`, `anthropic`, `openai`, `azure-openai`, etc. |
+| `providerKeyName` | string | No | Env var name for API key (e.g. `"GEMINI_API_KEY"`) |
+| `ai` | object | Yes | `{ model: string, temperature?: number, maxTokens?: number, stream?: boolean }` |
+| `executionMode` | string | No | `"axgen"` (default) or `"axagent"` |
+| `definition` / `prompt` | string | No | System prompt (>= 100 chars). `definition` takes precedence. |
+| `functions` | string[] | No | Tool names from the function registry |
+| `agents` | string[] | No | Sub-agent names this agent can delegate to |
+| `examples` | object[] | No | Few-shot examples matching the signature |
+| `mcpServers` | object | No | MCP server configurations |
+| `ace` | object | No | ACE learning configuration |
+| `debug` | boolean | No | Enable debug logging |
+| `apiURL` | string | No | Custom API endpoint (e.g. for Ollama) |
+| `providerArgs` | object | No | Provider-specific args (e.g. Azure deployment details) |
+| `options` | object | No | Forward options: `debug`, `stream`, `codeExecution`, `thinkingTokenBudget`, etc. |
+| `axAgentOptions` | object | No | RLM options (only for `axagent` mode): `runtime`, `contextFields`, `mode`, `maxTurns` |
+
+### Signature Format (DSPy)
+
+```
+"inputField:type \"description\" -> outputField:type \"description\""
+```
+
+Supported types: `string`, `number`, `boolean`, `json`, `string[]`, etc.
+
+Examples:
+```
+"query:string -> answer:string"
+"task:string \"a task\" -> plan:string \"step-by-step plan\""
+"question:string, context:string? -> answer:string, confidence:number"
+```
+
+## Adding Agents to the Crew
+
+Three methods, from simplest to most controlled:
+
+```typescript
+// 1. All agents (auto-handles dependencies)
+await crew.addAllAgents();
+
+// 2. Subset with auto dependency resolution
+await crew.addAgentsToCrew(["Writer", "Researcher"]);
+
+// 3. Manual (you handle dependency order)
+await crew.addAgent("Researcher");
+await crew.addAgent("Writer");
+
+// 4. Lazy initialization (defers expensive init until delegation)
+await crew.addLazyAgent("ExpensiveSubAgent");
+```
+
+`addLazyAgent()` builds the agent schema immediately (so parent agents can see it as a tool) but defers expensive initialization (MCP server startup, AI client creation) until the agent is actually called.
+
+## Function Registry (Tools)
+
+Two ways to define tools:
+
+### Direct AxFunction objects
+
+```typescript
+import type { AxFunction } from '@ax-llm/ax';
+
+const myFunctions = {
+  SearchWeb: {
+    name: 'SearchWeb',
+    description: 'Searches the web',
+    parameters: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'search query' } }
+    },
+    func: async ({ query }) => { /* ... */ return results; }
+  }
+};
+```
+
+### Class-based (receives shared state)
+
+```typescript
+class DatabaseQuery {
+  constructor(private state: Record<string, any>) {}
+  toFunction(): AxFunction {
+    return {
+      name: 'DatabaseQuery',
+      description: 'Queries the database',
+      parameters: {
+        type: 'object',
+        properties: { sql: { type: 'string', description: 'SQL query' } }
+      },
+      func: async ({ sql }) => {
+        const userId = this.state.userId; // Access shared state
+        return await db.query(sql, userId);
+      }
+    };
+  }
+}
+
+const crew = new AxCrew(config, { DatabaseQuery, ...AxCrewFunctions });
+```
+
+Built-in functions: `CurrentDateTime`, `DaysBetweenDates` (via `AxCrewFunctions`).
+
+## Shared State
+
+```typescript
+crew.state.set('userId', '123');
+crew.state.get('userId');       // '123'
+crew.state.getAll();            // { userId: '123' }
+crew.state.reset();             // Clear all
+
+// Agents share the same state
+const agent = crew.agents?.get("MyAgent");
+agent.state.set('key', 'value');  // Visible to all agents
+```
+
+## Streaming
+
+```typescript
+// Method 1: streamingForward (async iterator)
+const stream = await agent.streamingForward({ topic: "AI" });
+for await (const chunk of stream) {
+  if (chunk.delta && 'answer' in chunk.delta) {
+    process.stdout.write(chunk.delta.answer);
+  }
+}
+
+// Method 2: forward with onStream callback
+await agent.forward(
+  { topic: "AI" },
+  { onStream: (chunk) => process.stdout.write(chunk) }
+);
+```
+
+## MCP Server Integration
+
+Three transport types, auto-detected by config shape:
+
+```typescript
+mcpServers: {
+  // STDIO - local process
+  "filesystem": {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
+    env: { NODE_ENV: "production" }
+  },
+  // HTTP SSE - remote server
+  "api-server": {
+    sseUrl: "https://api.example.com/mcp/sse"
+  },
+  // Streamable HTTP - bidirectional
+  "stream-service": {
+    mcpEndpoint: "http://localhost:3002/stream",
+    options: { timeout: 30000 }
+  }
+}
+```
+
+### MCP Tool Filtering
+
+Reduce token usage by exposing only needed tools:
+
+```typescript
+mcpServers: {
+  graphjin: {
+    mcpEndpoint: "http://localhost:8080/api/v1/mcp",
+    tools: ["list_workflows", "execute_workflow", "describe_table"]  // Only these tools
+  }
+}
+```
+
+## ACE (Agentic Context Engineering)
+
+Enable agents to learn from human feedback at runtime:
+
+```typescript
+{
+  name: "SupportAgent",
+  // ... other config ...
+  ace: {
+    teacher: {
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-flash-latest" }
+    },
+    options: { maxEpochs: 1, allowDynamicSections: true },
+    persistence: {
+      playbookPath: "playbooks/support.json",
+      autoPersist: true
+    },
+    metric: { primaryOutputField: "response" },
+    compileOnStart: false
+  }
+}
+```
+
+### Applying Feedback
+
+```typescript
+const result = await agent.forward({ ticket: "..." });
+
+// Teach the agent
+await crew.applyTaskFeedback({
+  taskId: result._taskId,
+  feedback: "For loyal customers, extend return window to 60 days",
+  strategy: "all"  // "all" | "primary" | "weighted"
+});
+
+// View learned rules
+const playbook = agent.getPlaybook?.();
+```
+
+## Metrics & Cost Tracking
+
+```typescript
+// Per-agent metrics
+const metrics = agent.getMetrics?.();
+// { provider, model, requests: {...}, tokens: {...}, estimatedCostUSD, functions: {...} }
+
+// Crew-level aggregated metrics
+const crewMetrics = crew.getCrewMetrics();
+
+// Reset
+crew.resetCosts();
+crew.resetMetrics();
+```
+
+## OpenTelemetry Integration
+
+```typescript
+import { trace, metrics } from '@opentelemetry/api';
+
+const crew = new AxCrew(config, functions, undefined, {
+  telemetry: {
+    tracer: trace.getTracer('my-app'),
+    meter: metrics.getMeter('my-app')
+  }
+});
+```
+
+## Execution Modes
+
+### axgen (default)
+Structured generation via AxGen. Sub-agents become callable tool functions. Best for deterministic, single-pass tasks.
+
+### axagent
+Agentic loop with RLM (Runtime Language Model) support. Best for multi-step reasoning.
+
+```typescript
+import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
+
+{
+  name: "DeepResearcher",
+  executionMode: "axagent",
+  signature: "query:string, context:string? -> answer:string",
+  // ... provider config ...
+  axAgentOptions: {
+    runtime: new AxJSRuntime({ permissions: [AxJSRuntimePermission.TIMING] }),
+    contextFields: ["context"],
+    mode: "simple",
+    maxTurns: 12
+  }
+}
+```
+
+Both modes use the same `forward()` / `streamingForward()` API.
+
+## Environment Setup
+
+Set provider API keys as env vars. Each agent specifies which key via `providerKeyName`:
+
+```bash
+GEMINI_API_KEY=...
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+```
+
+AxCrew resolves keys via `process.env[providerKeyName]` (Node) or `globalThis[providerKeyName]` (browser).
+
+## Cleanup
+
+Always call `crew.destroy()` when done to clean up MCP servers and resources:
+
+```typescript
+try {
+  // ... use agents ...
+} finally {
+  crew.destroy();
+}
+```
+
+## Key Exports
+
+```typescript
+import {
+  AxCrew,              // Main class
+  AxCrewFunctions,     // Built-in function registry
+  MetricsRegistry,     // Metrics helpers
+} from '@amitdeshmukh/ax-crew';
+
+import type {
+  AxCrewConfig,        // Top-level config
+  AgentConfig,         // Per-agent config
+  AxCrewOptions,       // Constructor options (telemetry, debug)
+  StateInstance,        // State API
+  FunctionRegistryType,// Function registry shape
+  ACEConfig,           // ACE configuration
+} from '@amitdeshmukh/ax-crew';
+```
+
+## Common Patterns
+
+### Manager + Specialist Pattern
+
+```typescript
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "SpecialistAgent",
+      description: "Handles domain-specific queries",
+      signature: 'query:string -> answer:string',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", temperature: 0 },
+      mcpServers: { /* domain tools */ }
+    },
+    {
+      name: "ManagerAgent",
+      description: "Orchestrates specialists to answer questions",
+      prompt: "You orchestrate sub-agents to answer user questions. Delegate domain queries to specialists.",
+      signature: 'question:string -> answer:string',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", temperature: 0 },
+      agents: ["SpecialistAgent"]
+    }
+  ]
+};
+```
+
+### Lazy Sub-Agent for Expensive Resources
+
+```typescript
+const crew = new AxCrew(config);
+await crew.addLazyAgent("HeavyMCPAgent");   // Schema only, no MCP startup yet
+await crew.addAgentsToCrew(["ManagerAgent"]); // Manager sees HeavyMCPAgent as a tool
+// HeavyMCPAgent initializes only when Manager actually delegates to it
+```
+
+### Pipeline Pattern (Sequential Processing)
+
+```typescript
+const crew = new AxCrew(config);
+await crew.addAllAgents();
+
+const researcher = crew.agents?.get("Researcher");
+const writer = crew.agents?.get("Writer");
+
+const { research } = await researcher.forward({ query: "topic" });
+crew.state.set("research", research);
+const { article } = await writer.forward({ topic: "topic" });
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `basic-researcher-writer.ts` - Simple two-agent crew
+- `mcp-agent.ts` - MCP server integration with sub-agents
+- `streaming.ts` - Real-time token streaming
+- `run-crew-workflow.ts` - Database workflows with MCP tool filtering
+- `ace-customer-support.ts` - ACE learning from feedback
+- `ace-flight-finder.ts` - Flight assistant with preference learning
+- `rlm-long-task.ts` - RLM mode with context management
+- `rlm-shared-fields.ts` - RLM with field propagation
+- `telemetry-demo.ts` - OpenTelemetry with Jaeger
+- `solve-math-problem.ts` - Code execution with sub-agents
+
+## Troubleshooting
+
+- **Missing API key:** Ensure `providerKeyName` matches an env var that is set before crew creation.
+- **Circular dependencies:** AxCrew detects and reports circular `agents` references.
+- **MCP server won't start:** Enable `debug: true` on the agent to see MCP init logs.
+- **Sub-agent not visible:** Ensure the sub-agent is added to the crew before the parent agent, or use `addAllAgents()` / `addAgentsToCrew()` for automatic ordering.
+- **definition too short:** Must be >= 100 characters. Use `prompt` as an alias.

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [8.6.0] - 2026-03-14
+
+### Added
+- Claude Code skill (`.claude/skills/ax-crew/SKILL.md`) providing comprehensive library guidance for LLMs. Covers agent configuration, sub-agents, shared state, MCP integration, ACE learning, streaming, metrics, execution modes, function registries, and common patterns.
+
+## [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/package.json

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

package/examples/run-manager.ts

@@ -1,98 +0,0 @@
-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));