@amitdeshmukh/ax-crew 9.0.1 → 9.0.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [9.0.2] - 2026-03-30
+
+### Added
+- **Dynamic API key support**: `AgentConfig` now accepts an `apiKey` field as a `string` or `() => Promise<string>`. This enables dynamic credential refresh for providers that support it (Google Gemini, Anthropic). When set, `apiKey` takes precedence over `providerKeyName`. Useful for Google Cloud hosted models where access tokens must be refreshed periodically.
+
 ## [9.0.1] - 2026-03-29
 
 ### Fixed

package/dist/agents/agentConfig.js

@@ -112,9 +112,13 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state, options
         // Normalize provider slug to lowercase and validate via Ax factory
         const lower = String(agentConfigData.provider).toLowerCase();
         const provider = lower;
-        // Resolve API key from user-supplied environment variable name
+        // Resolve API key: direct apiKey (string or function) takes precedence over providerKeyName
         let apiKey = '';
-        if (agentConfigData.providerKeyName) {
+        if (agentConfigData.apiKey) {
+            // Direct apiKey provided — use as-is (supports string or async function for token refresh)
+            apiKey = agentConfigData.apiKey;
+        }
+        else if (agentConfigData.providerKeyName) {
             const keyName = agentConfigData.providerKeyName;
             apiKey = resolveApiKey(keyName) || '';
             if (!apiKey) {
@@ -122,7 +126,7 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state, options
             }
         }
         else {
-            throw new Error(`Provider key name is missing in the agent configuration`);
+            throw new Error(`Either apiKey or providerKeyName must be provided in the agent configuration`);
         }
         // Create a cost tracker instance and pass to ai()
         const costTracker = new AxDefaultCostTracker((agentConfigData.options?.costTracking) || undefined);

package/dist/agents/compose.d.ts

@@ -2,7 +2,7 @@ import type { AxAI } from '@ax-llm/ax';
 import type { AxCrewConfig } from '../types.js';
 type BuildProviderArgs = {
     provider: string;
-    apiKey: string;
+    apiKey: string | (() => Promise<string>);
     config: any;
     apiURL?: string;
     providerArgs?: Record<string, unknown>;

package/dist/agents/compose.js

@@ -10,12 +10,18 @@ export function instantiateProvider({ provider, apiKey, config, apiURL, provider
 export function buildProvidersFromConfig(cfg) {
     const services = [];
     for (const agent of cfg.crew) {
-        const apiKeyName = agent.providerKeyName;
-        if (!apiKeyName)
-            throw new Error(`Provider key name is missing for agent ${agent.name}`);
-        const apiKey = resolveApiKey(apiKeyName) || '';
-        if (!apiKey)
-            throw new Error(`API key '${apiKeyName}' not set for agent ${agent.name}`);
+        let apiKey = '';
+        if (agent.apiKey) {
+            apiKey = agent.apiKey;
+        }
+        else if (agent.providerKeyName) {
+            apiKey = resolveApiKey(agent.providerKeyName) || '';
+            if (!apiKey)
+                throw new Error(`API key '${agent.providerKeyName}' not set for agent ${agent.name}`);
+        }
+        else {
+            throw new Error(`Either apiKey or providerKeyName must be provided for agent ${agent.name}`);
+        }
         const service = instantiateProvider({
             provider: String(agent.provider).toLowerCase(),
             apiKey,

package/dist/types.d.ts

@@ -1,5 +1,10 @@
 import type { AxFunction, AxSignature, AxModelConfig, AxMCPStreamableHTTPTransportOptions, AxProgramForwardOptions, AxAIArgs, AxAgentOptions } from '@ax-llm/ax';
 export type Provider = AxAIArgs<any>['name'];
+/**
+ * An async function that returns an API key string.
+ * Useful for providers that support dynamic token refresh (e.g., Google Cloud, Anthropic).
+ */
+export type ApiKeyFunction = () => Promise<string>;
 export type AgentExecutionMode = 'axagent' | 'axgen';
 export type AxCrewAxAgentOptions = Partial<Omit<AxAgentOptions, 'agents' | 'functions' | 'contextFields'>> & {
     contextFields?: AxAgentOptions['contextFields'];
@@ -231,6 +236,13 @@ interface AgentConfig {
     prompt?: string;
     signature: string | AxSignature;
     provider: Provider;
+    /**
+     * Direct API key as a string or an async function that returns one.
+     * When a function is provided, it is called by the provider on each request,
+     * enabling dynamic credential refresh (e.g., Google Cloud access tokens).
+     * Takes precedence over `providerKeyName` when both are set.
+     */
+    apiKey?: string | ApiKeyFunction;
     providerKeyName?: string;
     ai: AxModelConfig & {
         model: string;

package/examples/google-cloud-token-refresh.ts

@@ -0,0 +1,67 @@
+/**
+ * Example: Using Google Cloud Vertex AI with dynamic token refresh.
+ *
+ * When running Gemini models on Google Cloud (Vertex AI), you need
+ * a short-lived access token instead of a static API key. Pass an
+ * async function as `apiKey` and ax-crew will call it each time
+ * the provider needs credentials.
+ *
+ * Prerequisites:
+ *   npm install google-auth-library
+ *   # Authenticate via: gcloud auth application-default login
+ */
+import { AxCrew } from "../dist/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
+import { GoogleAuth } from "google-auth-library";
+
+// Set up Google Auth — uses Application Default Credentials
+const googleAuth = new GoogleAuth({
+  scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+});
+
+// Async function that returns a fresh access token
+const getGoogleToken = async (): Promise<string> => {
+  const client = await googleAuth.getClient();
+  const response = await client.getAccessToken();
+  if (!response.token) {
+    throw new Error("Failed to get Google access token");
+  }
+  return response.token;
+};
+
+const crewConfig: AxCrewConfig = {
+  crew: [
+    {
+      name: "GeminiAgent",
+      description: "Agent using Google Cloud Vertex AI with dynamic token refresh",
+      provider: "google-gemini",
+      apiKey: getGoogleToken, // async function — called on each request
+      signature: "userQuery:string -> answer:string",
+      ai: {
+        model: "gemini-2.0-flash",
+        temperature: 0,
+      },
+      providerArgs: {
+        projectId: "your-gcp-project-id",
+        region: "global",
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(crewConfig);
+  await crew.addAllAgents();
+
+  const agent = crew.agents?.get("GeminiAgent");
+  const response = await agent?.forward({
+    userQuery: "What is the capital of France?",
+  });
+
+  console.log(response?.answer);
+  console.log(agent?.getAccumulatedCosts());
+
+  crew.destroy();
+}
+
+main().catch(console.error);

package/package.json

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

@@ -143,16 +143,19 @@ const parseAgentConfig = async (
     const lower = String(agentConfigData.provider).toLowerCase() as Provider;
     const provider = lower as Provider;
 
-    // Resolve API key from user-supplied environment variable name
-    let apiKey = '';
-    if (agentConfigData.providerKeyName) {
+    // Resolve API key: direct apiKey (string or function) takes precedence over providerKeyName
+    let apiKey: string | (() => Promise<string>) = '';
+    if (agentConfigData.apiKey) {
+      // Direct apiKey provided — use as-is (supports string or async function for token refresh)
+      apiKey = agentConfigData.apiKey;
+    } else if (agentConfigData.providerKeyName) {
       const keyName = agentConfigData.providerKeyName;
       apiKey = resolveApiKey(keyName) || '';
       if (!apiKey) {
         throw new Error(`API key '${keyName}' for provider ${agentConfigData.provider} is not set in environment`);
       }
     } else {
-      throw new Error(`Provider key name is missing in the agent configuration`);
+      throw new Error(`Either apiKey or providerKeyName must be provided in the agent configuration`);
     }
 
     // Create a cost tracker instance and pass to ai()

package/src/agents/compose.ts

@@ -4,7 +4,7 @@ import type { AxCrewConfig } from '../types.js';
 
 type BuildProviderArgs = {
   provider: string;
-  apiKey: string;
+  apiKey: string | (() => Promise<string>);
   config: any;
   apiURL?: string;
   providerArgs?: Record<string, unknown>;
@@ -28,10 +28,15 @@ export function instantiateProvider({
 export function buildProvidersFromConfig(cfg: AxCrewConfig): AxAI<any>[] {
   const services: AxAI<any>[] = [];
   for (const agent of cfg.crew) {
-    const apiKeyName = agent.providerKeyName;
-    if (!apiKeyName) throw new Error(`Provider key name is missing for agent ${agent.name}`);
-    const apiKey = resolveApiKey(apiKeyName) || '';
-    if (!apiKey) throw new Error(`API key '${apiKeyName}' not set for agent ${agent.name}`);
+    let apiKey: string | (() => Promise<string>) = '';
+    if (agent.apiKey) {
+      apiKey = agent.apiKey;
+    } else if (agent.providerKeyName) {
+      apiKey = resolveApiKey(agent.providerKeyName) || '';
+      if (!apiKey) throw new Error(`API key '${agent.providerKeyName}' not set for agent ${agent.name}`);
+    } else {
+      throw new Error(`Either apiKey or providerKeyName must be provided for agent ${agent.name}`);
+    }
 
     const service = instantiateProvider({
       provider: String(agent.provider).toLowerCase(),

package/src/skills/axcrew-agent-config.md

@@ -25,6 +25,7 @@ interface AgentConfig {
   };
 
   // Optional
+  apiKey?: string | (() => Promise<string>); // Direct API key or async token-refresh function
   providerKeyName?: string;        // Env var name for API key (e.g. "OPENAI_API_KEY")
   apiURL?: string;                 // Custom API endpoint (e.g. ollama on localhost)
   providerArgs?: Record<string, unknown>; // Provider-specific args forwarded to Ax factory
@@ -90,6 +91,44 @@ The `providerKeyName` field specifies which environment variable holds the API k
 }
 ```
 
+## Dynamic API Key (Token Refresh)
+
+For providers that support it (Google Gemini, Anthropic), `apiKey` can be an async function that returns a fresh token on each call. This is useful for Google Cloud hosted models where access tokens expire.
+
+```ts
+import { GoogleAuth } from "google-auth-library";
+
+const googleAuth = new GoogleAuth({
+  scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+});
+
+const getGoogleToken = async (): Promise<string> => {
+  const client = await googleAuth.getClient();
+  const response = await client.getAccessToken();
+  if (!response.token) throw new Error("Failed to get Google token");
+  return response.token;
+};
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "GeminiAgent",
+      description: "Agent using Google Cloud Vertex AI with token refresh",
+      provider: "google-gemini",
+      apiKey: getGoogleToken,  // called on each request to get a fresh token
+      signature: "userQuery:string -> answer:string",
+      ai: { model: "gemini-2.0-flash", temperature: 0 },
+      providerArgs: {
+        projectId: "your-gcp-project-id",
+        region: "global",
+      },
+    }
+  ]
+};
+```
+
+When `apiKey` is set, `providerKeyName` is not required.
+
 ## Azure OpenAI Example
 
 Use `providerArgs` for provider-specific configuration:
@@ -175,10 +214,11 @@ Supported types: `string`, `number`, `boolean`, `string[]`, `number[]`, etc.
 - Do NOT omit `name`, `description`, `signature`, `provider`, or `ai.model` -- all are required.
 - Do NOT set `definition` to less than 100 characters if you provide it (Ax enforces this minimum).
 - Do NOT confuse `options.stream` (forward option) with `ai.stream` (AI-level streaming config).
-- Do NOT use `providerArgs` for API keys; use `providerKeyName` instead.
+- Do NOT use `providerArgs` for API keys; use `apiKey` or `providerKeyName` instead.
 - Do NOT list sub-agents in `agents` that haven't been added to the crew before the parent agent.
 
 ## References
 
 - [basic-researcher-writer.ts](examples/basic-researcher-writer.ts)
 - [providerArgs.ts](examples/providerArgs.ts)
+- [google-cloud-token-refresh.ts](examples/google-cloud-token-refresh.ts)

package/src/skills/axcrew-providers.md

@@ -22,6 +22,7 @@ type Provider = AxAIArgs<any>['name'];
 ```ts
 interface AgentConfig {
   provider: Provider;              // e.g. "openai"
+  apiKey?: string | (() => Promise<string>); // direct key or async token-refresh fn
   providerKeyName?: string;        // env var name, e.g. "OPENAI_API_KEY"
   ai: AxModelConfig & { model: string }; // model name + temperature, maxTokens, etc.
   apiURL?: string;                 // custom endpoint (ollama, proxies)
@@ -30,6 +31,36 @@ interface AgentConfig {
 }
 ```
 
+## Dynamic API Key (Token Refresh)
+
+For providers that support it (Google Gemini, Anthropic), `apiKey` can be an async function returning a fresh token. When `apiKey` is set, `providerKeyName` is not required.
+
+```ts
+import { GoogleAuth } from "google-auth-library";
+
+const googleAuth = new GoogleAuth({
+  scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+});
+
+const getGoogleToken = async (): Promise<string> => {
+  const client = await googleAuth.getClient();
+  const response = await client.getAccessToken();
+  if (!response.token) throw new Error("Failed to get Google token");
+  return response.token;
+};
+
+{
+  name: "GeminiAgent",
+  provider: "google-gemini",
+  apiKey: getGoogleToken,
+  ai: { model: "gemini-2.0-flash", temperature: 0 },
+  providerArgs: {
+    projectId: "your-gcp-project-id",
+    region: "global",
+  },
+}
+```
+
 ## Provider-Specific Configuration
 
 ### Azure OpenAI
@@ -194,11 +225,11 @@ main().catch(console.error);
 
 ## Do Not Generate
 
-- Do NOT hardcode API keys in config -- always use `providerKeyName` which reads from `process.env`.
-- Do NOT use `providerArgs` for non-Azure providers unless the Ax factory documents it -- standard providers only need `provider`, `providerKeyName`, `ai`, and optionally `apiURL`.
+- Do NOT hardcode API keys in config -- use `providerKeyName` (env var) or `apiKey` (string or async function).
+- Do NOT use `providerArgs` for non-Azure providers unless the Ax factory documents it -- standard providers only need `provider`, `apiKey` or `providerKeyName`, `ai`, and optionally `apiURL`.
 - Do NOT confuse `options.searchParameters` (Grok-specific forward option) with `mcpServers` (external tool servers).
 - Do NOT set `provider: "perplexity"` -- Perplexity is accessed via an MCP server, not as a native Ax provider.
-- Do NOT omit `providerKeyName` -- the crew will throw at initialization if the env var is missing.
+- Do NOT omit both `apiKey` and `providerKeyName` -- the crew requires at least one to resolve credentials.
 
 ## References
 
@@ -206,4 +237,5 @@ main().catch(console.error);
 - [search-tweets.ts](examples/search-tweets.ts) (Grok/xAI)
 - [perplexityDeepSearch.ts](examples/perplexityDeepSearch.ts) (Perplexity MCP)
 - [write-post-and-publish-to-wordpress.ts](examples/write-post-and-publish-to-wordpress.ts) (mixed providers)
+- [google-cloud-token-refresh.ts](examples/google-cloud-token-refresh.ts) (dynamic API key)
 - [src/agents/compose.ts](src/agents/compose.ts)

package/src/types.ts

@@ -11,6 +11,12 @@ import type {
 // Provider ids are derived from Ax's factory arg type so new providers added in Ax
 // are picked up at compile time without updating AxCrew.
 export type Provider = AxAIArgs<any>['name'];
+
+/**
+ * An async function that returns an API key string.
+ * Useful for providers that support dynamic token refresh (e.g., Google Cloud, Anthropic).
+ */
+export type ApiKeyFunction = () => Promise<string>;
 export type AgentExecutionMode = 'axagent' | 'axgen';
 export type AxCrewAxAgentOptions =
   Partial<Omit<AxAgentOptions, 'agents' | 'functions' | 'contextFields'>> & {
@@ -261,6 +267,13 @@ interface AgentConfig {
   prompt?: string;
   signature: string | AxSignature;
   provider: Provider;
+  /**
+   * Direct API key as a string or an async function that returns one.
+   * When a function is provided, it is called by the provider on each request,
+   * enabling dynamic credential refresh (e.g., Google Cloud access tokens).
+   * Takes precedence over `providerKeyName` when both are set.
+   */
+  apiKey?: string | ApiKeyFunction;
   providerKeyName?: string;
   ai: AxModelConfig & { model: string };
   debug?: boolean;