feat(js/plugins/anthropic): lazily calculate API key at request time

Author: cabljac

js/plugins/anthropic/src/index.ts

@@ -44,24 +44,38 @@ export type { AnthropicCacheControl, AnthropicCitation } from './types.js';
 export { cacheControl } from './utils.js';
 
 /**
- * Gets or creates an Anthropic client instance.
- * Supports test client injection for internal testing.
+ * Gets the test client if injected (for testing only).
+ * @internal
  */
-function getAnthropicClient(options?: PluginOptions): Anthropic {
-  // Check for test client injection first (internal use only)
+function getTestClient(options?: PluginOptions): Anthropic | undefined {
   const internalOptions = options as InternalPluginOptions | undefined;
-  if (internalOptions?.[__testClient]) {
-    return internalOptions[__testClient];
+  return internalOptions?.[__testClient];
+}
+
+/**
+ * Validates the API key configuration at plugin initialization.
+ * When apiKey is false, validation is deferred to request time.
+ *
+ * @throws Error if API key is required but not available
+ */
+function validateApiKey(options?: PluginOptions): void {
+  // If apiKey is explicitly false, defer validation to request time
+  if (options?.apiKey === false) {
+    return;
   }
 
-  // Production path: create real client
+  // Check for test client injection (for testing only)
+  if (getTestClient(options)) {
+    return;
+  }
+
+  // Validate that we have an API key available
   const apiKey = options?.apiKey || process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error(
       'Please pass in the API key or set the ANTHROPIC_API_KEY environment variable'
     );
   }
-  return new Anthropic({ apiKey });
 }
 
 /**
@@ -94,8 +108,12 @@ function getAnthropicClient(options?: PluginOptions): Anthropic {
  * ```
  */
 function anthropicPlugin(options?: PluginOptions): GenkitPluginV2 {
-  const client = getAnthropicClient(options);
+  // Validate API key at plugin init (unless deferred with apiKey: false)
+  validateApiKey(options);
+
+  const pluginApiKey = options?.apiKey;
   const defaultApiVersion = options?.apiVersion;
+  const testClient = getTestClient(options);
 
   let listActionsCache: ActionMetadata[] | null = null;
 
@@ -106,8 +124,9 @@ function anthropicPlugin(options?: PluginOptions): GenkitPluginV2 {
       for (const name of Object.keys(KNOWN_CLAUDE_MODELS)) {
         const action = claudeModel({
           name,
-          client,
+          pluginApiKey,
           defaultApiVersion,
+          testClient,
         });
         actions.push(action);
       }
@@ -119,14 +138,25 @@ function anthropicPlugin(options?: PluginOptions): GenkitPluginV2 {
         const modelName = name.startsWith('anthropic/') ? name.slice(10) : name;
         return claudeModel({
           name: modelName,
-          client,
+          pluginApiKey,
           defaultApiVersion,
+          testClient,
         });
       }
       return undefined;
     },
     list: async () => {
       if (listActionsCache) return listActionsCache;
+      // For listing, we need a client. Create one if we have an API key available.
+      const listApiKey =
+        pluginApiKey !== false
+          ? pluginApiKey || process.env.ANTHROPIC_API_KEY
+          : undefined;
+      if (!listApiKey && !testClient) {
+        // Can't list models without an API key
+        return [];
+      }
+      const client = testClient ?? new Anthropic({ apiKey: listApiKey });
       listActionsCache = await listActions(client);
       return listActionsCache;
     },

js/plugins/anthropic/src/models.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+import Anthropic from '@anthropic-ai/sdk';
 import type {
   GenerateRequest,
   GenerateResponseData,
@@ -33,6 +34,7 @@ import {
   AnthropicBaseConfigSchemaType,
   AnthropicConfigSchema,
   AnthropicThinkingConfigSchema,
+  calculateApiKey,
   resolveBetaEnabled,
   type ClaudeModelParams,
   type ClaudeRunnerParams,
@@ -198,14 +200,7 @@ export function claudeRunner<TConfigSchema extends z.ZodTypeAny>(
   params: ClaudeRunnerParams,
   configSchema: TConfigSchema
 ) {
-  const { defaultApiVersion, ...runnerParams } = params;
-
-  if (!runnerParams.client) {
-    throw new Error('Anthropic client is required to create a runner');
-  }
-
-  let stableRunner: Runner | null = null;
-  let betaRunner: BetaRunner | null = null;
+  const { defaultApiVersion, pluginApiKey, testClient, name } = params;
 
   return async (
     request: GenerateRequest<TConfigSchema>,
@@ -223,13 +218,28 @@ export function claudeRunner<TConfigSchema extends z.ZodTypeAny>(
     const normalizedRequest = request as unknown as GenerateRequest<
       typeof AnthropicConfigSchema
     >;
+
+    // Determine the client to use
+    // Test client takes precedence, otherwise calculate API key at request time
+    const client = testClient
+      ? testClient
+      : new Anthropic({
+          apiKey: calculateApiKey(
+            pluginApiKey,
+            normalizedRequest.config?.apiKey
+          ),
+        });
+
     const isBeta = resolveBetaEnabled(
       normalizedRequest.config,
       defaultApiVersion
     );
+
+    // Create runner with the client
     const runner = isBeta
-      ? (betaRunner ??= new BetaRunner(runnerParams))
-      : (stableRunner ??= new Runner(runnerParams));
+      ? new BetaRunner({ name, client })
+      : new Runner({ name, client });
+
     return runner.run(normalizedRequest, {
       streamingRequested,
       sendChunk,
@@ -265,17 +275,22 @@ export function claudeModelReference(
 }
 
 /**
- * Defines a Claude model with the given name and Anthropic client.
+ * Defines a Claude model with the given name and API key configuration.
  * Accepts any model name and lets the API validate it. If the model is in KNOWN_CLAUDE_MODELS, uses that modelRef
  * for better defaults; otherwise creates a generic model reference.
  */
 export function claudeModel(
   params: ClaudeModelParams
 ): ModelAction<z.ZodTypeAny> {
-  const { name, client: runnerClient, defaultApiVersion: apiVersion } = params;
+  const {
+    name,
+    pluginApiKey,
+    defaultApiVersion: apiVersion,
+    testClient,
+  } = params;
   // Use supported model ref if available, otherwise create generic model ref
   const knownModelRef = KNOWN_CLAUDE_MODELS[name];
-  let modelInfo = knownModelRef
+  const modelInfo = knownModelRef
     ? knownModelRef.info
     : GENERIC_CLAUDE_MODEL_INFO;
   const configSchema = knownModelRef?.configSchema ?? AnthropicConfigSchema;
@@ -291,8 +306,9 @@ export function claudeModel(
     claudeRunner(
       {
         name,
-        client: runnerClient,
+        pluginApiKey,
         defaultApiVersion: apiVersion,
+        testClient,
       },
       configSchema
     )

js/plugins/anthropic/src/runner/base.ts

@@ -33,7 +33,7 @@ import {
   MediaSchema,
   MediaType,
   MediaTypeSchema,
-  type ClaudeRunnerParams,
+  type RunnerConstructorParams,
   type ThinkingConfig,
 } from '../types.js';
 
@@ -66,7 +66,7 @@ export abstract class BaseRunner<ApiTypes extends RunnerTypes> {
    */
   protected readonly DEFAULT_MAX_OUTPUT_TOKENS = 4096;
 
-  constructor(params: ClaudeRunnerParams) {
+  constructor(params: RunnerConstructorParams) {
     this.name = params.name;
     this.client = params.client;
   }

js/plugins/anthropic/src/runner/beta.ts

@@ -46,7 +46,7 @@ import { KNOWN_CLAUDE_MODELS, extractVersion } from '../models.js';
 import {
   AnthropicConfigSchema,
   type AnthropicDocumentOptions,
-  type ClaudeRunnerParams,
+  type RunnerConstructorParams,
 } from '../types.js';
 import { removeUndefinedProperties } from '../utils.js';
 import { BaseRunner } from './base.js';
@@ -142,7 +142,7 @@ interface BetaRunnerTypes extends RunnerTypes {
  * Runner for the Anthropic Beta API.
  */
 export class BetaRunner extends BaseRunner<BetaRunnerTypes> {
-  constructor(params: ClaudeRunnerParams) {
+  constructor(params: RunnerConstructorParams) {
     super(params);
   }
 
@@ -318,12 +318,13 @@ export class BetaRunner extends BaseRunner<BetaRunnerTypes> {
     // Need to extract topP and topK from request.config to avoid duplicate properties being added to the body
     // This happens because topP and topK have different property names (top_p and top_k) in the Anthropic API.
     // Thinking is extracted separately to avoid type issues.
-    // ApiVersion is extracted separately as it's not a valid property for the Anthropic API.
+    // apiVersion and apiKey are extracted separately as they're not valid properties for the Anthropic API.
     const {
       topP,
       topK,
       apiVersion: _1,
       thinking: _2,
+      apiKey: _3,
       ...restConfig
     } = request.config ?? {};
 
@@ -375,12 +376,13 @@ export class BetaRunner extends BaseRunner<BetaRunnerTypes> {
     // Need to extract topP and topK from request.config to avoid duplicate properties being added to the body
     // This happens because topP and topK have different property names (top_p and top_k) in the Anthropic API.
     // Thinking is extracted separately to avoid type issues.
-    // ApiVersion is extracted separately as it's not a valid property for the Anthropic API.
+    // apiVersion and apiKey are extracted separately as they're not valid properties for the Anthropic API.
     const {
       topP,
       topK,
       apiVersion: _1,
       thinking: _2,
+      apiKey: _3,
       ...restConfig
     } = request.config ?? {};
 

js/plugins/anthropic/src/runner/stable.ts

@@ -44,7 +44,7 @@ import { KNOWN_CLAUDE_MODELS, extractVersion } from '../models.js';
 import {
   AnthropicConfigSchema,
   type AnthropicDocumentOptions,
-  type ClaudeRunnerParams,
+  type RunnerConstructorParams,
 } from '../types.js';
 import { removeUndefinedProperties } from '../utils.js';
 import { BaseRunner } from './base.js';
@@ -85,7 +85,7 @@ interface RunnerTypes extends BaseRunnerTypes {
 }
 
 export class Runner extends BaseRunner<RunnerTypes> {
-  constructor(params: ClaudeRunnerParams) {
+  constructor(params: RunnerConstructorParams) {
     super(params);
   }
 
@@ -237,12 +237,13 @@ export class Runner extends BaseRunner<RunnerTypes> {
     // Need to extract topP and topK from request.config to avoid duplicate properties being added to the body
     // This happens because topP and topK have different property names (top_p and top_k) in the Anthropic API.
     // Thinking is extracted separately to avoid type issues.
-    // ApiVersion is extracted separately as it's not a valid property for the Anthropic API.
+    // apiVersion and apiKey are extracted separately as they're not valid properties for the Anthropic API.
     const {
       topP,
       topK,
       apiVersion: _1,
       thinking: _2,
+      apiKey: _3,
       ...restConfig
     } = request.config ?? {};
 
@@ -288,12 +289,13 @@ export class Runner extends BaseRunner<RunnerTypes> {
     // Need to extract topP and topK from request.config to avoid duplicate properties being added to the body
     // This happens because topP and topK have different property names (top_p and top_k) in the Anthropic API.
     // Thinking is extracted separately to avoid type issues.
-    // ApiVersion is extracted separately as it's not a valid property for the Anthropic API.
+    // apiVersion and apiKey are extracted separately as they're not valid properties for the Anthropic API.
     const {
       topP,
       topK,
       apiVersion: _1,
       thinking: _2,
+      apiKey: _3,
       ...restConfig
     } = request.config ?? {};