@amitdeshmukh/ax-crew 9.0.0 → 9.0.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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
+- **Agent-level forward options now respected**: Config options like `maxSteps`, `showThoughts`, and `thinkingTokenBudget` defined in agent config `options` were parsed but never passed to `AxGen.forward()`. They are now merged as defaults under caller-supplied options.
+- **Removed hardcoded `contextCache` breakpoint**: The `cacheBreakpoint: 'after-examples'` setting on AxGen is removed, as it is no longer needed after prompt caching changes in 9.0.0.
+
 ## [9.0.0] - 2026-03-25
 
 ### Breaking Changes

package/dist/agents/agentConfig.d.ts

@@ -40,5 +40,6 @@ declare const parseAgentConfig: (agentName: string, crewConfig: AxCrewConfig, fu
     tracker: AxDefaultCostTracker;
     deferredTools: any;
     debug: any;
+    forwardOptions: any;
 }>;
 export { parseAgentConfig, parseCrewConfig };

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);
@@ -201,6 +205,7 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state, options
             tracker: costTracker,
             deferredTools: agentConfigData.deferredTools,
             debug: agentConfigData.options?.debug ?? agentConfigData.debug ?? false,
+            forwardOptions: agentConfigData.options,
         };
     }
     catch (error) {

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/agents/crew.js

@@ -56,7 +56,7 @@ class AxCrew {
     createAgent = async (agentName) => {
         try {
             const agentConfig = await parseAgentConfig(agentName, this.crewConfig, this.functionsRegistry, this.crewState, this.options);
-            const { ai, name, executionMode, axAgentOptions, description, signature, functions, subAgentNames, examples, tracker } = agentConfig;
+            const { ai, name, executionMode, axAgentOptions, description, signature, functions, subAgentNames, examples, tracker, forwardOptions } = agentConfig;
             // Get subagents for the AI agent
             const subAgents = subAgentNames.map((subAgentName) => {
                 if (!this.agents?.get(subAgentName)) {
@@ -128,6 +128,7 @@ class AxCrew {
                 agents: uniqueSubAgents,
                 examples,
                 debug: agentConfig.debug,
+                forwardOptions,
             }, agentState);
             agent.costTracker = tracker;
             if (deferredManager.isActive) {

package/dist/agents/statefulAgent.d.ts

@@ -16,6 +16,8 @@ export interface ParsedAgentConfig {
     subAgentNames: string[];
     examples?: Array<Record<string, any>>;
     tracker?: any;
+    /** Agent-level forward options (maxSteps, showThoughts, thinkingTokenBudget, etc.) used as defaults when the caller doesn't supply them. */
+    forwardOptions?: Record<string, any>;
 }
 declare class StatefulAxAgent extends AxAgent<any, any> {
     crewState: StateInstance;
@@ -27,6 +29,7 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
     private costTracker?;
     private debugEnabled;
     private deferredToolManager?;
+    private agentForwardOptions?;
     private static readonly modernAxAgentRuntime;
     private aceConfig?;
     private aceOptimizer?;
@@ -45,6 +48,7 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
         examples?: Array<Record<string, any>> | undefined;
         mcpServers?: Record<string, MCPTransportConfig> | undefined;
         debug?: boolean;
+        forwardOptions?: Record<string, any>;
     }>, state: StateInstance);
     /**
      * @deprecated Use setExamplesCompat() to avoid Ax runtime version coupling.

package/dist/agents/statefulAgent.js

@@ -11,6 +11,7 @@ class StatefulAxAgent extends AxAgent {
     costTracker;
     debugEnabled = false;
     deferredToolManager;
+    agentForwardOptions;
     static modernAxAgentRuntime = typeof AxAgent?.prototype?.getFunction === "function" &&
         typeof AxAgent?.prototype?.setExamples !== "function";
     // ACE-related optional state
@@ -88,6 +89,7 @@ class StatefulAxAgent extends AxAgent {
         this.agentDefinition = effectiveDefinition;
         this.executionMode = options.executionMode ?? "axgen";
         this.debugEnabled = debug ?? false;
+        this.agentForwardOptions = options.forwardOptions;
         // Convert sub-agents to callable functions so AxGen can invoke them as tools
         const subAgentFunctions = resolvedAgents
             .map(agent => {
@@ -102,7 +104,6 @@ class StatefulAxAgent extends AxAgent {
         this.axGenProgram = new AxGen(options.signature, {
             description: effectiveDefinition,
             functions: [...resolvedFunctions, ...subAgentFunctions],
-            contextCache: { cacheBreakpoint: 'after-examples' },
         });
         for (const agent of resolvedAgents) {
             try {
@@ -177,7 +178,11 @@ class StatefulAxAgent extends AxAgent {
             throw new Error(`No AI instance is configured for agent "${this.agentName}"`);
         }
         const values = (calledWithAI ? second : first);
-        const options = (calledWithAI ? third : second);
+        const callerOptions = (calledWithAI ? third : second);
+        // Merge agent-level forward options as defaults under caller-supplied options
+        const options = this.agentForwardOptions
+            ? { ...this.agentForwardOptions, ...callerOptions }
+            : callerOptions;
         return { ai, values, options, calledWithAI };
     }
     /** Merge deferred tool step hooks into forward options */

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/examples/graphjin-database-agent.ts

@@ -50,11 +50,10 @@ STRATEGY:
       providerKeyName: "ANTHROPIC_API_KEY",
       ai: {
         model: "claude-sonnet-4-6",
-        temperature: 0,
-        stream: false
+        stream: true
       },
       options: {
-        debug: true
+        debug: false,
       },
       mcpServers: {
         "graphjin": {
@@ -75,10 +74,10 @@ Delegate each question to the most relevant agent in a SINGLE call — do not br
 The sub-agent will handle all the steps internally. Your job is to route and synthesize, not to decompose.
 If multiple agents are needed, call them and combine their answers.`,
       signature: 'question:string "a question to be answered" -> answer:string "the answer to the question"',
-      provider: "anthropic",
-      providerKeyName: "ANTHROPIC_API_KEY",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
       ai: {
-        model: "claude-sonnet-4-6",
+        model: "gemini-3-flash-preview",
         maxTokens: 2000,
         temperature: 0,
         stream: false
@@ -94,10 +93,11 @@ If multiple agents are needed, call them and combine their answers.`,
 // Create a new instance of AxCrew with the config
 const crew = new AxCrew(config as AxCrewConfig);
 
-const userQuery = "which products had the most refund requests and why?";
+const userQuery = "what are the 10 products with the most number of refund requests and what are the top complaints against each of them";
 
 console.log(`\nQuestion: ${userQuery}`);
 
+
 const main = async (): Promise<void> => {
   const timers: Record<string, number> = {};
 
@@ -107,25 +107,35 @@ const main = async (): Promise<void> => {
     await crew.addAllAgents();
     timers["setup"] = performance.now() - t0;
 
-    const managerAgent = crew.agents?.get("ManagerAgent");
-
-    if (!managerAgent) {
-      throw new Error("Failed to initialize ManagerAgent");
+    const dbAgent = crew.agents?.get("DatabaseAgent");
+    if (!dbAgent) {
+      throw new Error("Failed to initialize DatabaseAgent");
     }
 
-    // --- Query phase ---
+    // --- Query phase with streaming thoughts ---
     console.log("\n--- Starting query ---\n");
     const t1 = performance.now();
 
-    const managerResponse = await managerAgent.forward({
-      question: userQuery,
-    });
+    const stream = dbAgent.streamingForward(
+      { question: userQuery },
+      { showThoughts: true, thinkingTokenBudget: "low" }
+    );
+
+    let answer = '';
+    for await (const chunk of stream) {
+      if (chunk.delta && 'thought' in chunk.delta) {
+        process.stdout.write(chunk.delta.thought as string);
+      }
+      if (chunk.delta && 'answer' in chunk.delta) {
+        answer += chunk.delta.answer ?? '';
+      }
+    }
 
     timers["query"] = performance.now() - t1;
     timers["total"] = performance.now() - t0;
 
     // --- Results ---
-    console.log(`\nAnswer: ${JSON.stringify(managerResponse?.answer, null, 2)}`);
+    console.log(`\n\n--- Answer ---\n${answer}`);
 
     // --- Timing & Metrics ---
     console.log("\n--- Performance ---");

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "9.0.0",
+  "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()
@@ -237,6 +240,7 @@ const parseAgentConfig = async (
       tracker: costTracker,
       deferredTools: (agentConfigData as any).deferredTools,
       debug: (agentConfigData as any).options?.debug ?? (agentConfigData as any).debug ?? false,
+      forwardOptions: (agentConfigData as any).options,
     };
   } catch (error) {
     if (error instanceof Error) {

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/agents/crew.ts

@@ -93,7 +93,7 @@ class AxCrew {
         this.options
       );
 
-      const { ai, name, executionMode, axAgentOptions, description, signature, functions, subAgentNames, examples, tracker } = agentConfig;
+      const { ai, name, executionMode, axAgentOptions, description, signature, functions, subAgentNames, examples, tracker, forwardOptions } = agentConfig;
 
       // Get subagents for the AI agent
       const subAgents = subAgentNames.map((subAgentName: string) => {
@@ -182,6 +182,7 @@ class AxCrew {
           agents: uniqueSubAgents,
           examples,
           debug: (agentConfig as any).debug,
+          forwardOptions,
         },
         agentState as StateInstance
       );

package/src/agents/statefulAgent.ts

@@ -42,6 +42,8 @@ export interface ParsedAgentConfig {
   subAgentNames: string[];
   examples?: Array<Record<string, any>>;
   tracker?: any;
+  /** Agent-level forward options (maxSteps, showThoughts, thinkingTokenBudget, etc.) used as defaults when the caller doesn't supply them. */
+  forwardOptions?: Record<string, any>;
 }
 
 // Extend the AxAgent class from ax-llm
@@ -55,6 +57,7 @@ class StatefulAxAgent extends AxAgent<any, any> {
   private costTracker?: any;
   private debugEnabled: boolean = false;
   private deferredToolManager?: DeferredToolManager;
+  private agentForwardOptions?: Record<string, any>;
   private static readonly modernAxAgentRuntime =
     typeof (AxAgent as any)?.prototype?.getFunction === "function" &&
     typeof (AxAgent as any)?.prototype?.setExamples !== "function";
@@ -82,6 +85,7 @@ class StatefulAxAgent extends AxAgent<any, any> {
       examples?: Array<Record<string, any>> | undefined;
       mcpServers?: Record<string, MCPTransportConfig> | undefined;
       debug?: boolean;
+      forwardOptions?: Record<string, any>;
     }>,
     state: StateInstance
   ) {
@@ -162,6 +166,7 @@ class StatefulAxAgent extends AxAgent<any, any> {
     this.agentDefinition = effectiveDefinition;
     this.executionMode = options.executionMode ?? "axgen";
     this.debugEnabled = debug ?? false;
+    this.agentForwardOptions = options.forwardOptions;
     // Convert sub-agents to callable functions so AxGen can invoke them as tools
     const subAgentFunctions: AxFunction[] = resolvedAgents
       .map(agent => {
@@ -173,7 +178,6 @@ class StatefulAxAgent extends AxAgent<any, any> {
     this.axGenProgram = new AxGen(options.signature as any, {
       description: effectiveDefinition,
       functions: [...resolvedFunctions, ...subAgentFunctions],
-      contextCache: { cacheBreakpoint: 'after-examples' },
     } as any);
 
     for (const agent of resolvedAgents) {
@@ -270,7 +274,12 @@ class StatefulAxAgent extends AxAgent<any, any> {
     }
 
     const values = (calledWithAI ? second : first) as Record<string, any>;
-    const options = (calledWithAI ? third : second) as Readonly<TOptions> | undefined;
+    const callerOptions = (calledWithAI ? third : second) as Readonly<TOptions> | undefined;
+
+    // Merge agent-level forward options as defaults under caller-supplied options
+    const options = this.agentForwardOptions
+      ? ({ ...this.agentForwardOptions, ...callerOptions } as Readonly<TOptions>)
+      : callerOptions;
 
     return { ai, values, options, calledWithAI };
   }

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;