@amitdeshmukh/ax-crew 3.11.3 → 4.1.1

package/examples/mcp-agent.ts

@@ -1,4 +1,4 @@
-import { AxCrew } from "../dist/index.js";
+import { AxCrew, AxCrewConfig } from "../dist/index.js";
 
 import dotenv from "dotenv";
 dotenv.config();
@@ -9,15 +9,18 @@ const config = {
     {
       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",
       ai: {
         model: "claude-3-5-sonnet-latest",
         temperature: 0,
+        maxTokens: 1000,
+        stream: true
       },
       options: {
-        debug: true,
+        debug: true
       },
       "mcpServers": {
         "google-maps": {
@@ -35,6 +38,7 @@ const config = {
     {
       name: "ManagerAgent",
       description: "Completes a user specified task",
+      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", 
@@ -43,6 +47,7 @@ const config = {
         model: "gpt-4o-mini",
         maxTokens: 1000,
         temperature: 0,
+        stream: true
       },
       options: {
         debug: true,
@@ -59,17 +64,17 @@ const config = {
       ai: {
         model: "gemini-1.5-pro",
         temperature: 0,
+        stream: true
       },
       options: {
         debug: false,
-        codeExecution: true,
       },
     },
   ],
 };
 
 // Create a new instance of AxCrew with the config
-const crew = new AxCrew(config);
+const crew = new AxCrew(config as AxCrewConfig);
 
 // Add the agents to the crew
 await crew.addAllAgents();
@@ -89,11 +94,11 @@ const main = async (): Promise<void> => {
 
     console.log(`\nAnswer: ${JSON.stringify(managerResponse?.answer, null, 2)}`);
 
-    // Print usage costs
-    console.log("\nUsage:\n+++++++++++++++++++++++++++++++++");
-    console.log("Manager Agent Cost in $:", JSON.stringify(managerAgent?.getAccumulatedCosts()?.totalCost, null, 2));
-    console.log("Maps Agent Cost in $:", JSON.stringify(mapsAgent?.getAccumulatedCosts()?.totalCost, null, 2));
-    console.log("Total Cost in $:", JSON.stringify(crew.getAggregatedCosts()?.totalCost, null, 2));
+    // 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("Crew Metrics:", JSON.stringify((crew as any)?.getCrewMetrics?.(), null, 2));
 };
 
 main()

package/examples/solve-math-problem.ts

@@ -1,7 +1,8 @@
 import { AxCrew } from "../dist/index.js";
+import type { AxCrewConfig } from "../src/index.js";
 
 // Define the crew configuration
-const config = {
+const config: AxCrewConfig = {
   crew: [
     {
       name: "MathAgent",
@@ -62,10 +63,11 @@ const main = async (): Promise<void> => {
 
     console.log(`\nAnswer: ${JSON.stringify(managerResponse.answer, null, 2)}`);
 
-    // Print usage costs
-    console.log("\nUsage:\n+++++++++++++++++++++++++++++++++");
-    console.log("Manager Agent:", JSON.stringify(managerAgent.getAccumulatedCosts(), null, 2));
-    console.log("Total Cost:", JSON.stringify(crew.getAggregatedCosts(), null, 2));
+    // Print metrics
+    console.log("\nMetrics:\n+++++++++++++++++++++++++++++++++");
+    console.log("Manager Agent Metrics:", JSON.stringify((managerAgent as any).getMetrics?.(), null, 2));
+    console.log("Math Agent Metrics:", JSON.stringify((mathAgent as any).getMetrics?.(), null, 2));
+    console.log("Crew Metrics:", JSON.stringify((crew as any).getCrewMetrics?.(), null, 2));
   }
 };
 

package/examples/streaming.ts

@@ -1,10 +1,11 @@
 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 = {
+const config: AxCrewConfig = {
   crew: [
     {
       name: "ManagerAgent",
@@ -75,11 +76,11 @@ const main = async (): Promise<void> => {
       }
     }
 
-    // Print usage costs
-    console.log("\nUsage:\n+++++++++++++++++++++++++++++++++");
-    console.log("Manager Agent Cost in $:", JSON.stringify(managerAgent?.getAccumulatedCosts()?.totalCost, null, 2));
-    console.log("Math Agent Cost in $:", JSON.stringify(mathAgent?.getAccumulatedCosts()?.totalCost, null, 2));
-    console.log("Total Cost in $:", JSON.stringify(crew.getAggregatedCosts()?.totalCost, null, 2));
+    // Print metrics
+    console.log("\nMetrics:\n+++++++++++++++++++++++++++++++++");
+    console.log("Manager Agent Metrics:", JSON.stringify((managerAgent as any)?.getMetrics?.(), null, 2));
+    console.log("Math Agent Metrics:", JSON.stringify((mathAgent as any)?.getMetrics?.(), null, 2));
+    console.log("Crew Metrics:", JSON.stringify((crew as any)?.getCrewMetrics?.(), null, 2));
 };
 
 main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "3.11.3",
+  "version": "4.1.1",
   "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",
@@ -17,17 +17,19 @@
     "test:ui": "vitest --ui"
   },
   "dependencies": {
+    "big.js": "^7.0.1",
     "decimal.js": "^10.5.0",
     "dotenv": "^16.4.5",
     "upgrade": "^1.1.0",
     "uuid": "^10.0.0"
   },
   "peerDependencies": {
-    "@ax-llm/ax": "^13.0.8",
-    "@ax-llm/ax-tools": "^13.0.8"
+    "@ax-llm/ax": "14.0.16",
+    "@ax-llm/ax-tools": "14.0.16"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
+    "@types/big.js": "^6.2.2",
     "@types/node": "^20.14.9",
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^3.0.9",

package/src/agents/agentConfig.ts

@@ -1,10 +1,8 @@
 import fs from 'fs';
-// Import all the providers
-import { AxAIAnthropic, AxAIOpenAI, AxAIAzureOpenAI, AxAICohere, AxAIDeepSeek, AxAIGoogleGemini, AxAIGroq, AxAIHuggingFace, AxAIMistral, AxAIOllama, AxAITogether, AxAIReka, AxAIGrok } from '@ax-llm/ax';
-// Import Ax types
+// Import Ax factory and MCP transports (as exported by current package)
+import { ai, AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport, AxDefaultCostTracker } from '@ax-llm/ax'
 import type { AxFunction } from '@ax-llm/ax';
-// Import the MCP client and transports
-import { AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport } from '@ax-llm/ax'
+// STDIO transport from tools package
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools'
 import { PROVIDER_API_KEYS } from '../config/index.js';
 import type { 
@@ -14,28 +12,29 @@ import type {
   MCPTransportConfig, 
   MCPStdioTransportConfig, 
   MCPHTTPSSETransportConfig,
-  MCPStreambleHTTPTransportConfig
+  MCPStreamableHTTPTransportConfig
 } from '../types.js';
+import type { Provider } from '../types.js';
 
-// Define a mapping from provider names to their respective constructors
-const AIConstructors: Record<string, any> = {
-  'anthropic': AxAIAnthropic,
-  'azure-openai': AxAIAzureOpenAI,
-  'cohere': AxAICohere,
-  'deepseek': AxAIDeepSeek,
-  'google-gemini': AxAIGoogleGemini,
-  'groq': AxAIGroq,
-  'huggingFace': AxAIHuggingFace,
-  'mistral': AxAIMistral,
-  'ollama': AxAIOllama,
-  'openai': AxAIOpenAI,
-  'together': AxAITogether,
-  'reka': AxAIReka,
-  'grok': AxAIGrok
-};
+// Canonical provider slugs supported by ai() factory
+const PROVIDER_CANONICAL = new Set([
+  'openai',
+  'anthropic',
+  'google-gemini',
+  'mistral',
+  'groq',
+  'cohere',
+  'together',
+  'deepseek',
+  'ollama',
+  'huggingface',
+  'openrouter',
+  'azure-openai',
+  'reka',
+  'x-grok'
+]);
 
-// Provider type
-export type Provider = keyof typeof AIConstructors;
+// Provider type lives in src/types.ts
 
 // Type guard to check if config is stdio transport
 export function isStdioTransport(config: MCPTransportConfig): config is MCPStdioTransportConfig {
@@ -48,7 +47,7 @@ export function isHTTPSSETransport(config: MCPTransportConfig): config is MCPHTT
 }
 
 // Type guard to check if config is streamable HTTP transport
-export function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreambleHTTPTransportConfig {
+export function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreamableHTTPTransportConfig {
   return 'mcpEndpoint' in config;
 }
 
@@ -205,11 +204,12 @@ const parseAgentConfig = async (
       throw new Error(`AI agent with name ${agentName} is not configured`);
     }
 
-    // Get the constructor for the AI agent's provider
-    const AIConstructor = AIConstructors[agentConfigData.provider];
-    if (!AIConstructor) {
-      throw new Error(`AI provider ${agentConfigData.provider} is not supported. Did you mean '${agentConfigData.provider.toLowerCase()}'?`);
+    // Enforce canonical provider slug
+    const lower = agentConfigData.provider.toLowerCase();
+    if (!PROVIDER_CANONICAL.has(lower)) {
+      throw new Error(`AI provider ${agentConfigData.provider} is not supported. Use one of: ${Array.from(PROVIDER_CANONICAL).join(', ')}`);
     }
+    const provider = lower as Provider;
 
     // If an API Key property is present, get the API key for the AI agent from the environment variables
     let apiKey = '';
@@ -223,25 +223,30 @@ const parseAgentConfig = async (
       throw new Error(`Provider key name is missing in the agent configuration`);
     }
 
-    // Create an instance of the AI agent and set options
-    const ai = new AIConstructor({
+    // Create a cost tracker instance and pass to ai()
+    const costTracker = new AxDefaultCostTracker(((agentConfigData as any).options?.costTracking) || undefined);
+
+    // Create an instance of the AI agent via factory
+    const aiArgs: any = {
+      name: provider,
       apiKey,
       config: agentConfigData.ai,
       options: {
         debug: agentConfigData.debug || false,
-        ...agentConfigData.options
+        ...agentConfigData.options,
+        // Attach default cost tracker so usage/costs are recorded by provider layer
+        trackers: [costTracker]
       }
-    });
-    // If an apiURL is provided in the agent config, set it in the AI agent
+    };
     if (agentConfigData.apiURL) {
       try {
-        // Validate apiURL format
         new URL(agentConfigData.apiURL);
-        ai.setAPIURL(agentConfigData.apiURL);
+        aiArgs.apiURL = agentConfigData.apiURL;
       } catch (error) {
         throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
-      }      
+      }
     }
+    const aiInstance = ai(aiArgs);
 
     // If an mcpServers config is provided in the agent config, convert to functions
     const mcpFunctions = await initializeMCPServers(agentConfigData);
@@ -265,13 +270,15 @@ const parseAgentConfig = async (
     
     // Return AI instance and Agent parameters
     return {
-      ai,
+      ai: aiInstance,
       name: agentName,
       description: agentConfigData.description,
+      definition: (agentConfigData as any).definition ?? (agentConfigData as any).prompt,
       signature: agentConfigData.signature,
       functions: agentFunctions,
       subAgentNames: agentConfigData.agents || [],
       examples: agentConfigData.examples || [],
+      tracker: costTracker,
     };
   } catch (error) {
     if (error instanceof Error) {

package/src/agents/index.ts

@@ -20,13 +20,14 @@ import type {
 
 import { createState }   from "../state/index.js";
 import { parseCrewConfig, parseAgentConfig } from "./agentConfig.js";
-import { StateFulAxAgentUsage } from "./agentUseCosts.js";
+import { MetricsRegistry } from "../metrics/index.js";
 
 // Define the interface for the agent configuration
 interface ParsedAgentConfig {
   ai: AxAI;
   name: string;
   description: string;
+  definition?: string;
   signature: string | AxSignature;
   functions: (
     | AxFunction
@@ -36,6 +37,7 @@ interface ParsedAgentConfig {
   mcpServers?: Record<string, MCPTransportConfig>;
   subAgentNames: string[];
   examples?: Array<Record<string, any>>;
+  tracker?: any;
 }
 
 // Extend the AxAgent class from ax-llm
@@ -43,12 +45,21 @@ class StatefulAxAgent extends AxAgent<any, any> {
   state: StateInstance;
   axai: any;
   private agentName: string;
+  private costTracker?: any;
+  private lastRecordedCostUSD: number = 0;
+  private isAxAIService(obj: any): obj is AxAI {
+    return !!obj && typeof obj.getName === 'function' && typeof obj.chat === 'function';
+  }
+  private isAxAIInstance(obj: any): obj is AxAI {
+    return !!obj && typeof obj === 'object' && ('defaults' in obj || 'modelInfo' in obj);
+  }
 
   constructor(
     ai: AxAI,
     options: Readonly<{
       name: string;
       description: string;
+      definition?: string;
       signature: string | AxSignature;
       agents?: AxAgentic<any, any>[] | undefined;
       functions?: (AxFunction | (() => AxFunction))[] | undefined;
@@ -76,52 +87,92 @@ class StatefulAxAgent extends AxAgent<any, any> {
   }
 
   // Function overloads for forward method
-  async forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions>): Promise<Record<string, any>>;
-  async forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions>): Promise<Record<string, any>>;
+  async forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+  async forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
   
   // Implementation
   async forward(
     first: Record<string, any> | AxAI,
-    second?: Record<string, any> | Readonly<AxProgramForwardOptions>,
-    third?: Readonly<AxProgramForwardOptions>
+    second?: Record<string, any> | Readonly<AxProgramForwardOptions<any>>,
+    third?: Readonly<AxProgramForwardOptions<any>>
   ): Promise<Record<string, any>> {
     let result;
     
+    const start = performance.now();
+    const crewId = (this.state as any)?.crewId || (this.state.get?.('crewId')) || 'default';
+    const labels = { crewId, agent: this.agentName } as any;
+
     // Track costs regardless of whether it's a direct or sub-agent call
     // This ensures we capture multiple legitimate calls to the same agent
-    if ('apiURL' in first) {
+    if (this.isAxAIService(first)) {
       // Sub-agent case (called with AI service)
       result = await super.forward(this.axai, second as Record<string, any>, third);
     } else {
       // Direct call case
-      result = await super.forward(this.axai, first, second as Readonly<AxProgramForwardOptions>);
+      result = await super.forward(this.axai, first, second as Readonly<AxProgramForwardOptions<any>>);
     }
 
-    // Track costs after the call
-    const cost = this.getLastUsageCost();
-    if (cost) {
-      StateFulAxAgentUsage.trackCostInState(this.agentName, cost, this.state);
+    // Track metrics and costs after the call using built-in usage
+    const durationMs = performance.now() - start;
+    MetricsRegistry.recordRequest(labels, false, durationMs);
+    // Always record tokens from built-in usage array if present
+    const builtIn = (this as any).getUsage?.();
+    if (Array.isArray(builtIn)) {
+      const totals = builtIn.reduce(
+        (acc: any, u: any) => {
+          const pt = u.tokens?.promptTokens ?? u.promptTokens ?? 0;
+          const ct = u.tokens?.completionTokens ?? u.completionTokens ?? 0;
+          acc.promptTokens += typeof pt === 'number' ? pt : 0;
+          acc.completionTokens += typeof ct === 'number' ? ct : 0;
+          // also aggregate per-model to feed Ax tracker
+          const model = u.model || (this.axai as any)?.getLastUsedChatModel?.() || (this.axai as any)?.defaults?.model;
+          if (model) {
+            acc.byModel[model] = (acc.byModel[model] || 0) + (pt + ct);
+          }
+          return acc;
+        },
+        { promptTokens: 0, completionTokens: 0, byModel: {} as Record<string, number> }
+      );
+      MetricsRegistry.recordTokens(labels, {
+        promptTokens: totals.promptTokens,
+        completionTokens: totals.completionTokens,
+        totalTokens: totals.promptTokens + totals.completionTokens,
+      });
+      // Feed Ax's cost tracker with token totals per model; Ax owns pricing
+      const costTracker = (this as any).costTracker;
+      try {
+        for (const [m, count] of Object.entries(totals.byModel)) {
+          costTracker?.trackTokens?.(count, m);
+        }
+        const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+        if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+          MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+        }
+      } catch {}
     }
 
     return result;
   }
 
   // Add streaming forward method overloads
-  streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions>): AxGenStreamingOut<any>;
-  streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions>): AxGenStreamingOut<any>;
+  streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
+  streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
   
   // Implementation
   streamingForward(
     first: Record<string, any> | AxAI,
-    second?: Record<string, any> | Readonly<AxProgramStreamingForwardOptions>,
-    third?: Readonly<AxProgramStreamingForwardOptions>
+    second?: Record<string, any> | Readonly<AxProgramStreamingForwardOptions<any>>,
+    third?: Readonly<AxProgramStreamingForwardOptions<any>>
   ): AxGenStreamingOut<any> {
+    const start = performance.now();
+    const crewId = (this.state as any)?.crewId || (this.state.get?.('crewId')) || 'default';
+    const labels = { crewId, agent: this.agentName } as any;
     let streamingResult: AxGenStreamingOut<any>;
     
-    if ('apiURL' in first) {
+    if (this.isAxAIService(first)) {
       streamingResult = super.streamingForward(this.axai, second as Record<string, any>, third);
     } else {
-      streamingResult = super.streamingForward(this.axai, first, second as Readonly<AxProgramStreamingForwardOptions>);
+      streamingResult = super.streamingForward(this.axai, first, second as Readonly<AxProgramStreamingForwardOptions<any>>);
     }
 
     // Create a new async generator that tracks costs after completion
@@ -131,43 +182,71 @@ class StatefulAxAgent extends AxAgent<any, any> {
           yield chunk;
         }
       } finally {
-        const cost = this.getLastUsageCost();
-        if (cost) {
-          StateFulAxAgentUsage.trackCostInState(this.agentName, cost, this.state);
+        const durationMs = performance.now() - start;
+        MetricsRegistry.recordRequest(labels, true, durationMs);
+        // Record tokens from built-in usage array if present
+        const builtIn = (this as any).getUsage?.();
+        if (Array.isArray(builtIn)) {
+          const totals = builtIn.reduce(
+            (acc: any, u: any) => {
+              const pt = u.tokens?.promptTokens ?? u.promptTokens ?? 0;
+              const ct = u.tokens?.completionTokens ?? u.completionTokens ?? 0;
+              acc.promptTokens += typeof pt === 'number' ? pt : 0;
+              acc.completionTokens += typeof ct === 'number' ? ct : 0;
+              const model = u.model || (this.axai as any)?.getLastUsedChatModel?.() || (this.axai as any)?.defaults?.model;
+              if (model) {
+                acc.byModel[model] = (acc.byModel[model] || 0) + (pt + ct);
+              }
+              return acc;
+            },
+            { promptTokens: 0, completionTokens: 0, byModel: {} as Record<string, number> }
+          );
+          MetricsRegistry.recordTokens(labels, {
+            promptTokens: totals.promptTokens,
+            completionTokens: totals.completionTokens,
+            totalTokens: totals.promptTokens + totals.completionTokens,
+          });
+          const costTracker = (this as any).costTracker;
+          try {
+            for (const [m, count] of Object.entries(totals.byModel)) {
+              costTracker?.trackTokens?.(count, m);
+            }
+            const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+            if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+              MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+            }
+          } catch {}
         }
+        // Record estimated cost (USD) via attached tracker if available
+        const costTracker = (this as any).costTracker;
+        try {
+          const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+          if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+            MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+          }
+        } catch {}
       }
     }).bind(this)();
 
     return wrappedGenerator as AxGenStreamingOut<any>;
   }
 
-  // Get the usage cost for the most recent run of the agent
-  getLastUsageCost(): UsageCost | null {
-    const { modelUsage, modelInfo, defaults } = this.axai;
-    
-    // Check if all required properties exist
-    if (!modelUsage?.promptTokens || !modelUsage?.completionTokens) {
-      return null;
-    }
+  // Legacy cost API removed: rely on Ax trackers for cost reporting
+  getLastUsageCost(): UsageCost | null { return null; }
 
-    if (!modelInfo || !defaults?.model) {
-      return null;
-    }
-
-    const currentModelInfo = modelInfo.find((m: { name: string }) => m.name === defaults.model);
-    
-    if (!currentModelInfo?.promptTokenCostPer1M || !currentModelInfo?.completionTokenCostPer1M) {
-      return null;
-    }
+  // Get the accumulated costs for all runs of this agent
+  getAccumulatedCosts(): UsageCost | null { return null; }
 
-    return StateFulAxAgentUsage.calculateCost(modelUsage, currentModelInfo);
+  // Metrics API for this agent
+  getMetrics() {
+    const crewId = (this.state as any)?.crewId || (this.state.get?.('crewId')) || 'default';
+    return MetricsRegistry.snapshot({ crewId, agent: this.agentName } as any);
   }
-
-  // Get the accumulated costs for all runs of this agent
-  getAccumulatedCosts(): UsageCost | null {
-    const stateKey = `${StateFulAxAgentUsage.STATE_KEY_PREFIX}${this.agentName}`;
-    return this.state.get(stateKey) as UsageCost | null;
+  resetMetrics(): void {
+    const crewId = (this.state as any)?.crewId || (this.state.get?.('crewId')) || 'default';
+    MetricsRegistry.reset({ crewId, agent: this.agentName } as any);
   }
+
 }
 
 /**
@@ -208,6 +287,8 @@ class AxCrew {
     this.crewId = crewId;
     this.agents = new Map<string, StatefulAxAgent>();
     this.state = createState(crewId);
+    // Make crewId discoverable to metrics
+    this.state.set('crewId', crewId);
   }
 
   /**
@@ -226,7 +307,7 @@ class AxCrew {
       );
 
       // Destructure with type assertion
-      const { ai, name, description, signature, functions, subAgentNames, examples } = agentConfig;
+      const { ai, name, description, signature, functions, subAgentNames, examples, tracker } = agentConfig;
 
       // Get subagents for the AI agent
       const subAgents = subAgentNames.map((subAgentName: string) => {
@@ -238,23 +319,45 @@ class AxCrew {
         return this.agents?.get(subAgentName);
       });
 
+      // Dedupe sub-agents by name (defensive)
+      const subAgentSet = new Map<string, StatefulAxAgent>();
+      for (const sa of subAgents.filter((agent): agent is StatefulAxAgent => agent !== undefined)) {
+        const n = (sa as any)?.agentName ?? (sa as any)?.name ?? '';
+        if (!subAgentSet.has(n)) subAgentSet.set(n, sa);
+      }
+      const uniqueSubAgents = Array.from(subAgentSet.values());
+
+      // Dedupe functions by name and avoid collision with sub-agent names
+      const subAgentNameSet = new Set(uniqueSubAgents.map((sa: any) => sa?.agentName ?? sa?.name).filter(Boolean));
+      const uniqueFunctions: AxFunction[] = [];
+      const seenFn = new Set<string>();
+      for (const fn of functions.filter((fn): fn is AxFunction => fn !== undefined)) {
+        const fnName = fn.name;
+        if (subAgentNameSet.has(fnName)) {
+          // Skip function that collides with a sub-agent name
+          continue;
+        }
+        if (!seenFn.has(fnName)) {
+          seenFn.add(fnName);
+          uniqueFunctions.push(fn);
+        }
+      }
+
       // Create an instance of StatefulAxAgent
       const agent = new StatefulAxAgent(
         ai,
         {
           name,
           description,
+          definition: (agentConfig as any).definition,
           signature,
-          functions: functions.filter(
-            (fn): fn is AxFunction => fn !== undefined
-          ),
-          agents: subAgents.filter(
-            (agent): agent is StatefulAxAgent => agent !== undefined
-          ),
+          functions: uniqueFunctions,
+          agents: uniqueSubAgents,
           examples,
         },
         this.state
       );
+      (agent as any).costTracker = tracker;
 
       return agent;
     } catch (error) {
@@ -394,20 +497,29 @@ class AxCrew {
     this.state.reset();
   }
 
-  /**
-   * Gets aggregated costs for all agents in the crew
-   * @returns Aggregated cost information for all agents
-   */
-  getAggregatedCosts(): ReturnType<typeof StateFulAxAgentUsage.getAggregatedCosts> {
-    return StateFulAxAgentUsage.getAggregatedCosts(this.state);
-  }
 
   /**
    * Resets all cost tracking for the crew
    */
   resetCosts(): void {
-    StateFulAxAgentUsage.resetCosts(this.state);
+    // Reset AxAgent built-in usage and our metrics registry
+    if (this.agents) {
+      for (const [, agent] of this.agents) {
+        try { (agent as any).resetUsage?.(); } catch {}
+        try { (agent as any).resetMetrics?.(); } catch {}
+      }
+    }
+    MetricsRegistry.reset({ crewId: this.crewId });
+  }
+
+  // Metrics API
+  getCrewMetrics() {
+    return MetricsRegistry.snapshotCrew(this.crewId);
+  }
+  resetCrewMetrics(): void {
+    MetricsRegistry.reset({ crewId: this.crewId });
   }
 }
 
-export { AxCrew };
+export { AxCrew };
+export type { StatefulAxAgent };