send client options on every request

Author: sameelarif

CHANGELOG.md

@@ -233,15 +233,13 @@
   We're thrilled to announce the release of Stagehand 2.0, bringing significant improvements to make browser automation more powerful, faster, and easier to use than ever before.
 
   ### 🚀 New Features
-
   - **Introducing `stagehand.agent`**: A powerful new way to integrate SOTA Computer use models or Browserbase's [Open Operator](https://operator.browserbase.com) into Stagehand with one line of code! Perfect for multi-step workflows and complex interactions. [Learn more](https://docs.stagehand.dev/concepts/agent)
   - **Lightning-fast `act` and `extract`**: Major performance improvements to make your automations run significantly faster.
   - **Enhanced Logging**: Better visibility into what's happening during automation with improved logging and debugging capabilities.
   - **Comprehensive Documentation**: A completely revamped documentation site with better examples, guides, and best practices.
   - **Improved Error Handling**: More descriptive errors and better error recovery to help you debug issues faster.
 
   ### 🛠️ Developer Experience
-
   - **Better TypeScript Support**: Enhanced type definitions and better IDE integration
   - **Better Error Messages**: Clearer, more actionable error messages to help you debug faster
   - **Improved Caching**: More reliable action caching for better performance
@@ -502,7 +500,6 @@
 - [#316](https://github.com/browserbase/stagehand/pull/316) [`902e633`](https://github.com/browserbase/stagehand/commit/902e633e126a58b80b757ea0ecada01a7675a473) Thanks [@kamath](https://github.com/kamath)! - rename browserbaseResumeSessionID -> browserbaseSessionID
 
 - [#296](https://github.com/browserbase/stagehand/pull/296) [`f11da27`](https://github.com/browserbase/stagehand/commit/f11da27a20409c240ceeea2003d520f676def61a) Thanks [@kamath](https://github.com/kamath)! - - Deprecate fields in `init` in favor of constructor options
-
   - Deprecate `initFromPage` in favor of `browserbaseResumeSessionID` in constructor
   - Rename `browserBaseSessionCreateParams` -> `browserbaseSessionCreateParams`
 

lib/StagehandPage.ts

@@ -739,6 +739,7 @@ ${scriptContent} \
             const result = await this.api.act({
               ...observeResult,
               frameId: this.rootFrameId,
+              modelClientOptions: this.stagehand["modelClientOptions"],
             });
             this.stagehand.addToHistory("act", observeResult, result);
             return result;
@@ -836,7 +837,10 @@ ${scriptContent} \
       if (!instructionOrOptions) {
         let result: ExtractResult<T>;
         if (this.api) {
-          result = await this.api.extract<T>({ frameId: this.rootFrameId });
+          result = await this.api.extract<T>({
+            frameId: this.rootFrameId,
+            modelClientOptions: this.stagehand["modelClientOptions"],
+          });
         } else {
           result = await this.extractHandler.extract();
         }

lib/a11y/utils.ts

@@ -183,7 +183,8 @@ export async function buildBackendIdMaps(
           if (n.contentDocument && locate(n.contentDocument)) return true;
           return false;
         } else {
-          if (n.backendNodeId === backendNodeId) return (iframeNode = n), true;
+          if (n.backendNodeId === backendNodeId)
+            return ((iframeNode = n), true);
           return (
             (n.children?.some(locate) ?? false) ||
             (n.contentDocument ? locate(n.contentDocument) : false)

lib/api.ts

@@ -48,7 +48,6 @@ export class StagehandAPI {
 
   async init({
     modelName,
-    modelApiKey,
     domSettleTimeoutMs,
     verbose,
     debugDom,
@@ -59,11 +58,6 @@ export class StagehandAPI {
     browserbaseSessionCreateParams,
     browserbaseSessionID,
   }: StartSessionParams): Promise<StartSessionResult> {
-    if (!modelApiKey) {
-      throw new StagehandAPIError("modelApiKey is required");
-    }
-    this.modelApiKey = modelApiKey;
-
     const region = browserbaseSessionCreateParams?.region;
     if (region && region !== "us-west-2") {
       return { sessionId: browserbaseSessionID ?? null, available: false };
@@ -186,10 +180,19 @@ export class StagehandAPI {
     const queryString = urlParams.toString();
     const url = `/sessions/${this.sessionId}/${method}${queryString ? `?${queryString}` : ""}`;
 
-    const response = await this.request(url, {
-      method: "POST",
-      body: JSON.stringify(args),
-    });
+    // Extract modelClientOptions from args if present
+    const modelClientOptions = (
+      args as { modelClientOptions?: Record<string, unknown> }
+    )?.modelClientOptions;
+
+    const response = await this.request(
+      url,
+      {
+        method: "POST",
+        body: JSON.stringify(args),
+      },
+      modelClientOptions,
+    );
 
     if (!response.ok) {
       const errorBody = await response.text();
@@ -248,6 +251,7 @@ export class StagehandAPI {
   private async request(
     path: string,
     options: RequestInit = {},
+    modelClientOptions?: Record<string, unknown>,
   ): Promise<Response> {
     const defaultHeaders: Record<string, string> = {
       "x-bb-api-key": this.apiKey,
@@ -261,6 +265,12 @@ export class StagehandAPI {
       "x-sdk-version": STAGEHAND_VERSION,
     };
 
+    // Add modelClientOptions as a header if provided
+    if (modelClientOptions) {
+      defaultHeaders["x-model-client-options"] =
+        JSON.stringify(modelClientOptions);
+    }
+
     if (options.method === "POST" && options.body) {
       defaultHeaders["Content-Type"] = "application/json";
     }

lib/index.ts

@@ -45,7 +45,11 @@ import { LLMProvider } from "./llm/LLMProvider";
 import { StagehandLogger } from "./logger";
 import { connectToMCPServer } from "./mcp/connection";
 import { resolveTools } from "./mcp/utils";
-import { isRunningInBun, loadApiKeyFromEnv } from "./utils";
+import {
+  isRunningInBun,
+  loadApiKeyFromEnv,
+  loadBedrockClientOptions,
+} from "./utils";
 
 dotenv.config({ path: ".env" });
 
@@ -587,10 +591,23 @@ export class Stagehand {
     if (!modelClientOptions?.apiKey) {
       // If no API key is provided, try to load it from the environment
       if (LLMProvider.getModelProvider(this.modelName) === "aisdk") {
-        modelApiKey = loadApiKeyFromEnv(
-          this.modelName.split("/")[0],
-          this.logger,
-        );
+        const provider = this.modelName.split("/")[0];
+
+        // Special handling for Amazon Bedrock's complex authentication
+        if (provider === "bedrock") {
+          const bedrockOptions = loadBedrockClientOptions(this.logger);
+          this.modelClientOptions = {
+            ...modelClientOptions,
+            ...bedrockOptions,
+          };
+        } else {
+          // Standard single API key handling for other AISDK providers
+          modelApiKey = loadApiKeyFromEnv(provider, this.logger);
+          this.modelClientOptions = {
+            ...modelClientOptions,
+            apiKey: modelApiKey,
+          };
+        }
       } else {
         // Temporary add for legacy providers
         modelApiKey =
@@ -601,11 +618,11 @@ export class Stagehand {
               : LLMProvider.getModelProvider(this.modelName) === "google"
                 ? process.env.GOOGLE_API_KEY
                 : undefined;
+        this.modelClientOptions = {
+          ...modelClientOptions,
+          apiKey: modelApiKey,
+        };
       }
-      this.modelClientOptions = {
-        ...modelClientOptions,
-        apiKey: modelApiKey,
-      };
     } else {
       this.modelClientOptions = modelClientOptions;
     }
@@ -753,7 +770,7 @@ export class Stagehand {
         logger: this.logger,
       });
 
-      const modelApiKey = this.modelClientOptions?.apiKey;
+      const modelApiKey = this.modelClientOptions?.apiKey as string;
       const { sessionId, available } = await this.apiClient.init({
         modelName: this.modelName,
         modelApiKey: modelApiKey,

lib/llm/CerebrasClient.ts

@@ -31,7 +31,7 @@ export class CerebrasClient extends LLMClient {
     enableCaching?: boolean;
     cache?: LLMCache;
     modelName: AvailableModel;
-    clientOptions?: OpenAI.ClientOptions;
+    clientOptions?: ClientOptions;
     userProvidedInstructions?: string;
   }) {
     super(modelName, userProvidedInstructions);

lib/llm/GoogleClient.ts

@@ -83,7 +83,7 @@ export class GoogleClient extends LLMClient {
       clientOptions.apiKey = loadApiKeyFromEnv("google_legacy", logger);
     }
     this.clientOptions = clientOptions;
-    this.client = new GoogleGenAI({ apiKey: clientOptions.apiKey });
+    this.client = new GoogleGenAI({ apiKey: clientOptions.apiKey as string });
     this.cache = cache;
     this.enableCaching = enableCaching;
     this.modelName = modelName;

lib/llm/LLMProvider.ts

@@ -6,6 +6,7 @@ import {
 } from "@/types/stagehandErrors";
 import { anthropic, createAnthropic } from "@ai-sdk/anthropic";
 import { azure, createAzure } from "@ai-sdk/azure";
+import { bedrock, createAmazonBedrock } from "@ai-sdk/amazon-bedrock";
 import { cerebras, createCerebras } from "@ai-sdk/cerebras";
 import { createDeepSeek, deepseek } from "@ai-sdk/deepseek";
 import { createGoogleGenerativeAI, google } from "@ai-sdk/google";
@@ -38,6 +39,7 @@ const AISDKProviders: Record<string, AISDKProvider> = {
   xai,
   azure,
   groq,
+  bedrock,
   cerebras,
   togetherai,
   mistral,
@@ -52,6 +54,7 @@ const AISDKProvidersWithAPIKey: Record<string, AISDKCustomProvider> = {
   xai: createXai,
   azure: createAzure,
   groq: createGroq,
+  bedrock: createAmazonBedrock,
   cerebras: createCerebras,
   togetherai: createTogetherAI,
   mistral: createMistral,
@@ -108,7 +111,7 @@ export function getAISDKLanguageModel(
       );
     }
     // Create the provider instance with the custom configuration options
-    const provider = creator(modelClientOptions);
+    const provider = creator(modelClientOptions as Record<string, unknown>);
     // Get the specific model from the provider
     return provider(subModelName);
   } else {

lib/utils.ts

@@ -452,6 +452,7 @@ export const providerEnvVarMap: Partial<
   perplexity: "PERPLEXITY_API_KEY",
   azure: "AZURE_API_KEY",
   xai: "XAI_API_KEY",
+  bedrock: "AWS_BEARER_TOKEN_BEDROCK", // Primary API key method for Bedrock
   google_legacy: "GOOGLE_API_KEY",
 };
 
@@ -493,6 +494,75 @@ export function loadApiKeyFromEnv(
   return undefined;
 }
 
+/**
+ * Loads Amazon Bedrock client configuration from environment variables.
+ * Supports both API key authentication and SigV4 authentication methods.
+ * @param logger Logger function for info/error messages
+ * @returns Bedrock client options object or undefined if no authentication method is available
+ */
+export function loadBedrockClientOptions(
+  logger: (logLine: LogLine) => void,
+): Record<string, unknown> | undefined {
+  // Authentication precedence:
+  // 1. API key from AWS_BEARER_TOKEN_BEDROCK (recommended)
+  // 2. SigV4 authentication using AWS credentials
+
+  const bearerToken = process.env.AWS_BEARER_TOKEN_BEDROCK;
+  const region =
+    process.env.AWS_DEFAULT_REGION || process.env.AWS_REGION || "us-east-1"; // Default to us-east-1
+
+  // Method 1: API key authentication (recommended)
+  if (bearerToken && bearerToken.length > 0) {
+    logger({
+      category: "init",
+      message: "Using Amazon Bedrock API key authentication",
+      level: 1,
+    });
+
+    const config: Record<string, unknown> = {
+      apiKey: bearerToken,
+      region: region, // Always include region (defaults to us-east-1)
+    };
+
+    return config;
+  }
+
+  // Method 2: Check for SigV4 authentication credentials
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+  const sessionToken = process.env.AWS_SESSION_TOKEN;
+
+  if (accessKeyId && secretAccessKey) {
+    logger({
+      category: "init",
+      message: "Using Amazon Bedrock SigV4 authentication",
+      level: 1,
+    });
+
+    const config: Record<string, unknown> = {
+      accessKeyId,
+      secretAccessKey,
+      region: region, // Always include region (defaults to us-east-1)
+    };
+
+    // Add session token if present (for temporary credentials)
+    if (sessionToken && sessionToken.length > 0) {
+      config.sessionToken = sessionToken;
+    }
+
+    return config;
+  }
+
+  logger({
+    category: "init",
+    message:
+      "No Amazon Bedrock authentication credentials found. Please set either AWS_BEARER_TOKEN_BEDROCK for API key auth or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY (and optionally AWS_SESSION_TOKEN) for SigV4 auth",
+    level: 0,
+  });
+
+  return undefined;
+}
+
 export function trimTrailingTextNode(
   path: string | undefined,
 ): string | undefined {

package.json

@@ -83,11 +83,10 @@
     "pino-pretty": "^13.0.0",
     "playwright": "^1.52.0",
     "ws": "^8.18.0",
-    "zod-to-json-schema": "^3.23.5"
-  },
-  "optionalDependencies": {
+    "zod-to-json-schema": "^3.23.5",
     "@ai-sdk/anthropic": "^1.2.6",
     "@ai-sdk/azure": "^1.3.19",
+    "@ai-sdk/amazon-bedrock": "^1.0.0",
     "@ai-sdk/cerebras": "^0.2.6",
     "@ai-sdk/deepseek": "^0.2.13",
     "@ai-sdk/google": "^1.2.6",