@amitdeshmukh/ax-crew 4.1.2 → 5.0.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# Changelog
+
+## [5.0.0] - 2025-10-16
+
+### Added
+- Provider-specific arguments via `providerArgs` in `AgentConfig` to pass through typed provider params to the underlying Ax factory.
+- Typed forwarding for common providers in `parseAgentConfig`:
+  - azure-openai: `resourceName`, `deploymentName`, `version` (falls back to `apiURL` as `resourceName` if provided)
+  - anthropic: `projectId`, `region` (on Vertex AI)
+  - google-gemini: `projectId`, `region`, `endpointId`
+  - openrouter: `referer`, `title`
+  - ollama: `url`
+- Example `examples/providerArgs.ts` demonstrating `providerArgs` with Azure OpenAI.
+- JSDoc function hints for cost/usage APIs (`getMetrics`, `resetMetrics`, `resetCosts`, `getCrewMetrics`, `resetCrewMetrics`, and metrics registry helpers).
+
+### Docs
+- README section documenting `providerArgs` usage, supported providers, and Azure configuration examples.
+
+### Notes
+- Existing configs continue to work. For Azure, you can still set `apiURL`; when `resourceName` is omitted, the code uses `apiURL` as the `resourceName` (full endpoint) for convenience.
+
 # Changelog
 ## [4.1.2] - 2025-10-14
 

package/README.md

@@ -35,12 +35,17 @@ AZURE_OPENAI_API_KEY=...
 ```
 In each agent config, set `providerKeyName` to the env var name.
 
-#### Azure OpenAI
-- Use provider `azure-openai`.
-- Set `providerKeyName` to `AZURE_OPENAI_API_KEY`.
-- Set `apiURL` to your Azure endpoint (e.g., `https://your-resource.openai.azure.com`).
+#### Provider-specific arguments (`providerArgs`)
+Some providers require extra top-level configuration beyond `ai.model` (e.g., Azure deployments or Gemini project/region). You can pass these via `providerArgs`; AxCrew forwards them to the underlying Ax factory with type alignment for popular providers.
 
-Minimal example agent config:
+Supported mappings:
+- `azure-openai`: `resourceName`, `deploymentName`, `version` (if `resourceName` omitted and `apiURL` set, `apiURL` is used as full endpoint)
+- `anthropic`: `projectId`, `region`
+- `google-gemini`: `projectId`, `region`, `endpointId`
+- `openrouter`: `referer`, `title`
+- `ollama`: `url`
+
+Azure example with `providerArgs`:
 ```json
 {
   "name": "Writer",
@@ -49,7 +54,11 @@ Minimal example agent config:
   "provider": "azure-openai",
   "providerKeyName": "AZURE_OPENAI_API_KEY",
   "ai": { "model": "gpt-4o-mini", "temperature": 0 },
-  "apiURL": "https://your-resource.openai.azure.com"
+  "apiURL": "https://your-resource.openai.azure.com",  "providerArgs": {
+    "resourceName": "your-resource",
+    "deploymentName": "gpt-4o-mini",
+    "version": "api-version=2024-02-15-preview"
+  }
 }
 ```
 

package/dist/agents/agentConfig.js

@@ -214,6 +214,36 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
                 throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
             }
         }
+        // Forward provider-specific arguments with type-safety for Azure OpenAI
+        const providerArgs = agentConfigData.providerArgs;
+        if (provider === 'azure-openai') {
+            const az = providerArgs ?? {};
+            // If users supplied apiURL instead of resourceName, accept it (Ax supports full URL as resourceName)
+            if (!az.resourceName && agentConfigData.apiURL) {
+                az.resourceName = agentConfigData.apiURL;
+            }
+            Object.assign(aiArgs, az);
+        }
+        else if (provider === 'anthropic') {
+            const an = providerArgs ?? {};
+            Object.assign(aiArgs, an);
+        }
+        else if (provider === 'google-gemini') {
+            const g = providerArgs ?? {};
+            Object.assign(aiArgs, g);
+        }
+        else if (provider === 'openrouter') {
+            const o = providerArgs ?? {};
+            Object.assign(aiArgs, o);
+        }
+        else if (provider === 'ollama') {
+            const ol = providerArgs ?? {};
+            Object.assign(aiArgs, ol);
+        }
+        else if (providerArgs && typeof providerArgs === 'object') {
+            // Generic pass-through for other providers if needed in the future
+            Object.assign(aiArgs, providerArgs);
+        }
         const aiInstance = ai(aiArgs);
         // If an mcpServers config is provided in the agent config, convert to functions
         const mcpFunctions = await initializeMCPServers(agentConfigData);

package/dist/agents/agentUseCosts.d.ts

@@ -5,8 +5,22 @@ import type { StateInstance, ModelUsage, ModelInfo, UsageCost, AggregatedCosts }
  */
 export declare class StateFulAxAgentUsage {
     static STATE_KEY_PREFIX: string;
+    /**
+     * Compute usage costs given a model usage record and model pricing info.
+     * Returns null if inputs are invalid. Token-based costs are computed with high precision.
+     */
     static calculateCost(modelUsage: ModelUsage, modelInfo: ModelInfo): UsageCost | null;
+    /**
+     * Persist or aggregate the cost for an agent in the shared crew state.
+     * No-op if cost is null.
+     */
     static trackCostInState(agentName: string, cost: UsageCost | null, state: StateInstance): void;
+    /**
+     * Aggregate and return total costs across all agents from the shared crew state.
+     */
     static getAggregatedCosts(state: StateInstance): AggregatedCosts;
+    /**
+     * Remove all stored per-agent costs from the shared crew state.
+     */
     static resetCosts(state: StateInstance): void;
 }

package/dist/agents/agentUseCosts.js

@@ -5,6 +5,10 @@ import { Decimal } from 'decimal.js';
  */
 export class StateFulAxAgentUsage {
     static STATE_KEY_PREFIX = 'agent_usage_';
+    /**
+     * Compute usage costs given a model usage record and model pricing info.
+     * Returns null if inputs are invalid. Token-based costs are computed with high precision.
+     */
     static calculateCost(modelUsage, modelInfo) {
         // Handle both direct properties and nested tokens structure
         const promptTokens = modelUsage.tokens?.promptTokens ?? modelUsage.promptTokens;
@@ -44,6 +48,10 @@ export class StateFulAxAgentUsage {
             return null;
         }
     }
+    /**
+     * Persist or aggregate the cost for an agent in the shared crew state.
+     * No-op if cost is null.
+     */
     static trackCostInState(agentName, cost, state) {
         // If cost is null, skip tracking
         if (!cost)
@@ -75,6 +83,9 @@ export class StateFulAxAgentUsage {
             state.set(stateKey, cost);
         }
     }
+    /**
+     * Aggregate and return total costs across all agents from the shared crew state.
+     */
     static getAggregatedCosts(state) {
         const allState = state.getAll();
         const agentCosts = {};
@@ -108,6 +119,9 @@ export class StateFulAxAgentUsage {
             }
         };
     }
+    /**
+     * Remove all stored per-agent costs from the shared crew state.
+     */
     static resetCosts(state) {
         const allState = state.getAll();
         Object.keys(allState).forEach(key => {

package/dist/agents/index.d.ts

@@ -25,7 +25,17 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
     streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
     getLastUsageCost(): UsageCost | null;
     getAccumulatedCosts(): UsageCost | null;
+    /**
+     * Get the current metrics snapshot for this agent.
+     * Includes request counts, error rates, token usage, estimated USD cost, and function call stats.
+     *
+     * @returns A metrics snapshot scoped to this agent within its crew.
+     */
     getMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    /**
+     * Reset all tracked metrics for this agent (does not affect other agents).
+     * Call this to start fresh measurement windows for the agent.
+     */
     resetMetrics(): void;
 }
 /**
@@ -70,10 +80,21 @@ declare class AxCrew {
      */
     destroy(): void;
     /**
-     * Resets all cost tracking for the crew
+     * Resets all cost and usage tracking for the entire crew.
+     * Also calls each agent's `resetUsage` (if available) and clears crew-level metrics.
      */
     resetCosts(): void;
+    /**
+     * Get an aggregate metrics snapshot for the entire crew.
+     * Sums requests, errors, tokens, and estimated cost across all agents in the crew.
+     *
+     * @returns Crew-level metrics snapshot.
+     */
     getCrewMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    /**
+     * Reset all tracked metrics for the entire crew.
+     * Use to clear totals before a new measurement period.
+     */
     resetCrewMetrics(): void;
 }
 export { AxCrew };

package/dist/agents/index.js

@@ -156,10 +156,20 @@ class StatefulAxAgent extends AxAgent {
     // Get the accumulated costs for all runs of this agent
     getAccumulatedCosts() { return null; }
     // Metrics API for this agent
+    /**
+     * Get the current metrics snapshot for this agent.
+     * Includes request counts, error rates, token usage, estimated USD cost, and function call stats.
+     *
+     * @returns A metrics snapshot scoped to this agent within its crew.
+     */
     getMetrics() {
         const crewId = this.state?.crewId || (this.state.get?.('crewId')) || 'default';
         return MetricsRegistry.snapshot({ crewId, agent: this.agentName });
     }
+    /**
+     * Reset all tracked metrics for this agent (does not affect other agents).
+     * Call this to start fresh measurement windows for the agent.
+     */
     resetMetrics() {
         const crewId = this.state?.crewId || (this.state.get?.('crewId')) || 'default';
         MetricsRegistry.reset({ crewId, agent: this.agentName });
@@ -376,7 +386,8 @@ class AxCrew {
         this.state.reset();
     }
     /**
-     * Resets all cost tracking for the crew
+     * Resets all cost and usage tracking for the entire crew.
+     * Also calls each agent's `resetUsage` (if available) and clears crew-level metrics.
      */
     resetCosts() {
         // Reset AxAgent built-in usage and our metrics registry
@@ -395,9 +406,19 @@ class AxCrew {
         MetricsRegistry.reset({ crewId: this.crewId });
     }
     // Metrics API
+    /**
+     * Get an aggregate metrics snapshot for the entire crew.
+     * Sums requests, errors, tokens, and estimated cost across all agents in the crew.
+     *
+     * @returns Crew-level metrics snapshot.
+     */
     getCrewMetrics() {
         return MetricsRegistry.snapshotCrew(this.crewId);
     }
+    /**
+     * Reset all tracked metrics for the entire crew.
+     * Use to clear totals before a new measurement period.
+     */
     resetCrewMetrics() {
         MetricsRegistry.reset({ crewId: this.crewId });
     }

package/dist/metrics/registry.d.ts

@@ -1,9 +1,36 @@
 import type { LabelKeys, MetricsSnapshot, TokenUsage } from './types.js';
+/**
+ * Record a completed request.
+ * @param labels Crew/agent/provider/model identifiers
+ * @param streaming Whether this was a streaming request
+ * @param durationMs Duration in milliseconds
+ */
 export declare function recordRequest(labels: LabelKeys, streaming: boolean, durationMs: number): void;
+/**
+ * Record an error occurrence for the given labels.
+ */
 export declare function recordError(labels: LabelKeys): void;
+/**
+ * Record token usage for a request (prompt and completion).
+ */
 export declare function recordTokens(labels: LabelKeys, usage: TokenUsage): void;
+/**
+ * Add estimated cost (USD) to the cumulative total for the labels.
+ */
 export declare function recordEstimatedCost(labels: LabelKeys, usd: number): void;
+/**
+ * Record a function call invocation and add its latency to totals.
+ */
 export declare function recordFunctionCall(labels: LabelKeys, latencyMs: number): void;
+/**
+ * Get a metrics snapshot for specific labels (crew + agent + optional provider/model).
+ */
 export declare function snapshot(labels: LabelKeys): MetricsSnapshot;
+/**
+ * Reset metrics for specific labels, or clear all if no labels provided.
+ */
 export declare function reset(labels?: LabelKeys): void;
+/**
+ * Aggregate a crew-wide metrics snapshot across all agents in the crew.
+ */
 export declare function snapshotCrew(crewId: string): MetricsSnapshot;

package/dist/metrics/registry.js

@@ -24,6 +24,12 @@ function getOrInit(labels) {
     }
     return c;
 }
+/**
+ * Record a completed request.
+ * @param labels Crew/agent/provider/model identifiers
+ * @param streaming Whether this was a streaming request
+ * @param durationMs Duration in milliseconds
+ */
 export function recordRequest(labels, streaming, durationMs) {
     const c = getOrInit(labels);
     c.requests += 1;
@@ -32,26 +38,41 @@ export function recordRequest(labels, streaming, durationMs) {
     c.durationMsSum += durationMs;
     c.durationCount += 1;
 }
+/**
+ * Record an error occurrence for the given labels.
+ */
 export function recordError(labels) {
     const c = getOrInit(labels);
     c.errors += 1;
 }
+/**
+ * Record token usage for a request (prompt and completion).
+ */
 export function recordTokens(labels, usage) {
     const c = getOrInit(labels);
     c.inputTokens += usage.promptTokens || 0;
     c.outputTokens += usage.completionTokens || 0;
 }
+/**
+ * Add estimated cost (USD) to the cumulative total for the labels.
+ */
 export function recordEstimatedCost(labels, usd) {
     const c = getOrInit(labels);
     const current = new Big(c.estimatedCostUSD || 0);
     const addition = new Big(usd || 0);
     c.estimatedCostUSD = Number(current.plus(addition));
 }
+/**
+ * Record a function call invocation and add its latency to totals.
+ */
 export function recordFunctionCall(labels, latencyMs) {
     const c = getOrInit(labels);
     c.functionCalls += 1;
     c.functionLatencyMs += latencyMs || 0;
 }
+/**
+ * Get a metrics snapshot for specific labels (crew + agent + optional provider/model).
+ */
 export function snapshot(labels) {
     const c = getOrInit(labels);
     const totalTokens = c.inputTokens + c.outputTokens;
@@ -78,6 +99,9 @@ export function snapshot(labels) {
         },
     };
 }
+/**
+ * Reset metrics for specific labels, or clear all if no labels provided.
+ */
 export function reset(labels) {
     if (!labels) {
         store.clear();
@@ -86,6 +110,9 @@ export function reset(labels) {
     const k = keyOf(labels);
     store.delete(k);
 }
+/**
+ * Aggregate a crew-wide metrics snapshot across all agents in the crew.
+ */
 export function snapshotCrew(crewId) {
     const empty = {
         requests: 0,

package/dist/types.d.ts

@@ -165,6 +165,11 @@ interface AgentConfig {
     };
     debug?: boolean;
     apiURL?: string;
+    /**
+     * Provider-specific arguments that are forwarded to the underlying Ax factory.
+     * Example (azure-openai): { resourceName, deploymentName, version }
+     */
+    providerArgs?: Record<string, unknown>;
     options?: Partial<AxProgramForwardOptions<any>> & Record<string, any>;
     functions?: string[];
     agents?: string[];

package/examples/providerArgs.ts

@@ -0,0 +1,41 @@
+import { AxCrew, AxCrewConfig } from "../dist/index.js";
+
+const crewConfig: AxCrewConfig = {
+  crew: [
+    {
+      name: "TestAgent",
+      description: "Test Agent for testing provider arguments",
+      provider: "azure-openai",
+      providerKeyName: "AZURE_OPENAI_API_KEY",
+      signature: "userQuery:string -> answer:string",
+      ai: {
+        model: "gpt-5-mini",
+        temperature: 0,
+        stream: false
+      },
+      providerArgs: {
+        resourceName: "your-resource-name",
+        deploymentName: "your-deployment-name",
+        version: "2025-01-01-preview"
+      },
+      functions: [],
+      options: {
+        debug: true,
+        stream: false
+      }
+    }
+  ]
+};
+
+const crew = new AxCrew(crewConfig);
+await crew.addAllAgents();
+
+const testAgent = crew.agents?.get("TestAgent");
+
+const response = await testAgent?.forward({
+  userQuery: "What is the capital of France?"
+});
+
+console.log(response?.answer);
+
+console.log(testAgent?.getAccumulatedCosts());

package/package.json

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

@@ -1,6 +1,13 @@
 import fs from 'fs';
 // Import Ax factory and MCP transports (as exported by current package)
 import { ai, AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport, AxDefaultCostTracker } from '@ax-llm/ax'
+import type {
+  AxAIAzureOpenAIArgs,
+  AxAIAnthropicArgs,
+  AxAIGoogleGeminiArgs,
+  AxAIOpenRouterArgs,
+  AxAIOllamaArgs
+} from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
 // STDIO transport from tools package
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools'
@@ -246,6 +253,36 @@ const parseAgentConfig = async (
         throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
       }
     }
+    // Forward provider-specific arguments with type-safety for Azure OpenAI
+    const providerArgs = (agentConfigData as any).providerArgs;
+    if (provider === 'azure-openai') {
+      type AzureArgs = Pick<AxAIAzureOpenAIArgs<string>, 'resourceName' | 'deploymentName' | 'version'>;
+      const az: Partial<AzureArgs> = providerArgs ?? {};
+      // If users supplied apiURL instead of resourceName, accept it (Ax supports full URL as resourceName)
+      if (!az.resourceName && agentConfigData.apiURL) {
+        az.resourceName = agentConfigData.apiURL as any;
+      }
+      Object.assign(aiArgs, az);
+    } else if (provider === 'anthropic') {
+      type AnthropicArgs = Pick<AxAIAnthropicArgs<string>, 'projectId' | 'region'>;
+      const an: Partial<AnthropicArgs> = providerArgs ?? {};
+      Object.assign(aiArgs, an);
+    } else if (provider === 'google-gemini') {
+      type GeminiArgs = Pick<AxAIGoogleGeminiArgs<string>, 'projectId' | 'region' | 'endpointId'>;
+      const g: Partial<GeminiArgs> = providerArgs ?? {};
+      Object.assign(aiArgs, g);
+    } else if (provider === 'openrouter') {
+      type OpenRouterArgs = Pick<AxAIOpenRouterArgs<string>, 'referer' | 'title'>;
+      const o: Partial<OpenRouterArgs> = providerArgs ?? {};
+      Object.assign(aiArgs, o);
+    } else if (provider === 'ollama') {
+      type OllamaArgs = Pick<AxAIOllamaArgs<string>, 'url'>;
+      const ol: Partial<OllamaArgs> = providerArgs ?? {};
+      Object.assign(aiArgs, ol);
+    } else if (providerArgs && typeof providerArgs === 'object') {
+      // Generic pass-through for other providers if needed in the future
+      Object.assign(aiArgs, providerArgs);
+    }
     const aiInstance = ai(aiArgs);
 
     // If an mcpServers config is provided in the agent config, convert to functions

package/src/agents/agentUseCosts.ts

@@ -15,6 +15,10 @@ import type {
 export class StateFulAxAgentUsage {
   static STATE_KEY_PREFIX = 'agent_usage_';
 
+  /**
+   * Compute usage costs given a model usage record and model pricing info.
+   * Returns null if inputs are invalid. Token-based costs are computed with high precision.
+   */
   static calculateCost(modelUsage: ModelUsage, modelInfo: ModelInfo): UsageCost | null {
     // Handle both direct properties and nested tokens structure
     const promptTokens = (modelUsage as any).tokens?.promptTokens ?? modelUsage.promptTokens;
@@ -59,6 +63,10 @@ export class StateFulAxAgentUsage {
     }
   }
 
+  /**
+   * Persist or aggregate the cost for an agent in the shared crew state.
+   * No-op if cost is null.
+   */
   static trackCostInState(agentName: string, cost: UsageCost | null, state: StateInstance) {
     // If cost is null, skip tracking
     if (!cost) return;
@@ -90,6 +98,9 @@ export class StateFulAxAgentUsage {
     }
   }
 
+  /**
+   * Aggregate and return total costs across all agents from the shared crew state.
+   */
   static getAggregatedCosts(state: StateInstance): AggregatedCosts {
     const allState = state.getAll();
     const agentCosts: Record<string, UsageCost> = {};
@@ -128,6 +139,9 @@ export class StateFulAxAgentUsage {
     };
   }
 
+  /**
+   * Remove all stored per-agent costs from the shared crew state.
+   */
   static resetCosts(state: StateInstance) {
     const allState = state.getAll();
     Object.keys(allState).forEach(key => {

package/src/agents/index.ts

@@ -238,10 +238,20 @@ class StatefulAxAgent extends AxAgent<any, any> {
   getAccumulatedCosts(): UsageCost | null { return null; }
 
   // Metrics API for this agent
+  /**
+   * Get the current metrics snapshot for this agent.
+   * Includes request counts, error rates, token usage, estimated USD cost, and function call stats.
+   *
+   * @returns A metrics snapshot scoped to this agent within its crew.
+   */
   getMetrics() {
     const crewId = (this.state as any)?.crewId || (this.state.get?.('crewId')) || 'default';
     return MetricsRegistry.snapshot({ crewId, agent: this.agentName } as any);
   }
+  /**
+   * Reset all tracked metrics for this agent (does not affect other agents).
+   * Call this to start fresh measurement windows for the agent.
+   */
   resetMetrics(): void {
     const crewId = (this.state as any)?.crewId || (this.state.get?.('crewId')) || 'default';
     MetricsRegistry.reset({ crewId, agent: this.agentName } as any);
@@ -499,7 +509,8 @@ class AxCrew {
 
 
   /**
-   * Resets all cost tracking for the crew
+   * Resets all cost and usage tracking for the entire crew.
+   * Also calls each agent's `resetUsage` (if available) and clears crew-level metrics.
    */
   resetCosts(): void {
     // Reset AxAgent built-in usage and our metrics registry
@@ -513,9 +524,19 @@ class AxCrew {
   }
 
   // Metrics API
+  /**
+   * Get an aggregate metrics snapshot for the entire crew.
+   * Sums requests, errors, tokens, and estimated cost across all agents in the crew.
+   *
+   * @returns Crew-level metrics snapshot.
+   */
   getCrewMetrics() {
     return MetricsRegistry.snapshotCrew(this.crewId);
   }
+  /**
+   * Reset all tracked metrics for the entire crew.
+   * Use to clear totals before a new measurement period.
+   */
   resetCrewMetrics(): void {
     MetricsRegistry.reset({ crewId: this.crewId });
   }

package/src/metrics/registry.ts

@@ -44,6 +44,12 @@ function getOrInit(labels: LabelKeys): Counters {
   return c;
 }
 
+/**
+ * Record a completed request.
+ * @param labels Crew/agent/provider/model identifiers
+ * @param streaming Whether this was a streaming request
+ * @param durationMs Duration in milliseconds
+ */
 export function recordRequest(labels: LabelKeys, streaming: boolean, durationMs: number) {
   const c = getOrInit(labels);
   c.requests += 1;
@@ -52,17 +58,26 @@ export function recordRequest(labels: LabelKeys, streaming: boolean, durationMs:
   c.durationCount += 1;
 }
 
+/**
+ * Record an error occurrence for the given labels.
+ */
 export function recordError(labels: LabelKeys) {
   const c = getOrInit(labels);
   c.errors += 1;
 }
 
+/**
+ * Record token usage for a request (prompt and completion).
+ */
 export function recordTokens(labels: LabelKeys, usage: TokenUsage) {
   const c = getOrInit(labels);
   c.inputTokens += usage.promptTokens || 0;
   c.outputTokens += usage.completionTokens || 0;
 }
 
+/**
+ * Add estimated cost (USD) to the cumulative total for the labels.
+ */
 export function recordEstimatedCost(labels: LabelKeys, usd: number) {
   const c = getOrInit(labels);
   const current = new Big(c.estimatedCostUSD || 0);
@@ -70,12 +85,18 @@ export function recordEstimatedCost(labels: LabelKeys, usd: number) {
   c.estimatedCostUSD = Number(current.plus(addition));
 }
 
+/**
+ * Record a function call invocation and add its latency to totals.
+ */
 export function recordFunctionCall(labels: LabelKeys, latencyMs: number) {
   const c = getOrInit(labels);
   c.functionCalls += 1;
   c.functionLatencyMs += latencyMs || 0;
 }
 
+/**
+ * Get a metrics snapshot for specific labels (crew + agent + optional provider/model).
+ */
 export function snapshot(labels: LabelKeys): MetricsSnapshot {
   const c = getOrInit(labels);
   const totalTokens = c.inputTokens + c.outputTokens;
@@ -103,6 +124,9 @@ export function snapshot(labels: LabelKeys): MetricsSnapshot {
   };
 }
 
+/**
+ * Reset metrics for specific labels, or clear all if no labels provided.
+ */
 export function reset(labels?: LabelKeys) {
   if (!labels) {
     store.clear();
@@ -112,6 +136,9 @@ export function reset(labels?: LabelKeys) {
   store.delete(k);
 }
 
+/**
+ * Aggregate a crew-wide metrics snapshot across all agents in the crew.
+ */
 export function snapshotCrew(crewId: string): MetricsSnapshot {
   const empty: Counters = {
     requests: 0,

package/src/types.ts

@@ -196,6 +196,11 @@ interface AgentConfig {
   ai: AxModelConfig & { model: string };
   debug?: boolean;
   apiURL?: string;
+  /**
+   * Provider-specific arguments that are forwarded to the underlying Ax factory.
+   * Example (azure-openai): { resourceName, deploymentName, version }
+   */
+  providerArgs?: Record<string, unknown>;
   options?: Partial<AxProgramForwardOptions<any>> & Record<string, any>;
   functions?: string[];
   agents?: string[];