Skip to main content
Understand web pages, plan actions, and interact with complex interfaces with Google, OpenAI, Anthropic, xAI, DeepSeek, Perplexity, Azure, Ollama, or any other LLM model from the Vercel AI SDK.

​
Configuration Setup

​
Quick Start

Set your API key in .env and Stagehand handles the rest. No explicit configuration needed!
Get started with Google Gemini (recommended for speed and cost): 
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-2.5-flash"
  // API key auto-loads from GOOGLE_GENERATIVE_AI_API_KEY - set in your .env
});

await stagehand.init();

​
First Class Models

Use any model from the following supported providers.
  • Google
  • Anthropic
  • OpenAI
  • Azure
  • Cerebras
  • DeepSeek
  • Groq
  • Mistral
  • Ollama
  • Perplexity
  • TogetherAI
  • xAI
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-2.5-flash"
  // API key auto-loads from GOOGLE_GENERATIVE_AI_API_KEY - set in your .env
});

await stagehand.init();
View all supported Google models →

​
Custom Models

Amazon Bedrock, Cohere, all first class models, and any model from the Vercel AI SDK is supported. Use this configuration for custom endpoints and custom retry or caching logic. We’ll use Amazon Bedrock and Google as examples below.
1

Install dependencies

Install the Vercel AI SDK for your provider.
  • npm
  • pnpm
  • yarn
  • bun
npm install @ai-sdk/amazon-bedrock
2

Import, create provider, and create client

import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
import { AISdkClient } from '@browserbasehq/stagehand';

const bedrockProvider = createAmazonBedrock({
  region: 'us-east-1',
  accessKeyId: 'xxxxxxxxx',
  secretAccessKey: 'xxxxxxxxx',
  sessionToken: 'xxxxxxxxx',
});

const bedrockClient = new AISdkClient({
  model: bedrockProvider("amazon/nova-pro-latest"),
});
3

Pass client to Stagehand

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  llmClient: bedrockClient
});

await stagehand.init();
1

Install dependencies

Install the Vercel AI SDK for your provider.
  • npm
  • pnpm
  • yarn
  • bun
npm install @ai-sdk/google
2

Import, create provider, and create client

import { createGoogle } from '@ai-sdk/google';
import { AISdkClient } from '@browserbasehq/stagehand';

const googleProvider = createGoogle({
  apiKey: process.env.GEMINI_API_KEY,
});

const googleClient = new AISdkClient({
  model: googleProvider("google/gemini-2.5-flash"),
});
3

Pass client to Stagehand

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  llmClient: googleClient
});

await stagehand.init();
To implement a custom model, follow the steps for the provider you are using. See the Amazon Bedrock and Google examples above. All supported providers and models are in the Vercel AI SDK.
1

Install dependencies

Install the Vercel AI SDK for your provider.
2

Import, create provider, and create client

import { createProvider } from '@ai-sdk/provider';
import { AISdkClient } from '@browserbasehq/stagehand';

const provider = createProvider({
  apiKey: 'xxxxxxxxx',
});

const providerClient = new AISdkClient({
  model: provider("model/name"),
});
3

Pass client to Stagehand

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  llmClient: providerClient
});

await stagehand.init();

​
Choose a Model

Different models excel at different tasks. Consider speed, accuracy, and cost for your use case.

Model Selection Guide

Find detailed model comparisons and recommendations on our Model Evaluation page.
 Quick Recommendations
Use CaseRecommended ModelWhy
Productiongoogle/gemini-2.5-flashFast, accurate, cost-effective
Intelligencegoogle/gemini-2.5-proBest accuracy on hard tasks
Speedgoogle/gemini-2.5-flashFastest response times
Costgoogle/gemini-2.5-flashBest value per token
Local/offlineollama/qwen3No API costs, full control

​
Advanced Options

​
Agent Models (with CUA Support)

Default The Stagehand agent by default uses the same model passed to Stagehand. All models (first class and custom) are supported. Here’s an example with Gemini: 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-2.5-flash",
  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env
  // ... other stagehand options
});

// Agent will use google/gemini-2.5-flash
const agent = stagehand.agent();
Override (with CUA support) However, the stagehand agent also accepts a model parameter, which accepts any first class model, including computer use agents (CUA). This is useful when you’d like the agent to use a different model than the one passed to Stagehand.
To use a cua model, you must pass the cua parameter to the agent() method. If a non-cua model is used, whether specified in Stagehand or overridden in the agent() method, an error will be thrown.
  • Google CUA
  • Anthropic CUA
  • OpenAI CUA
  • Example First Class Model
const agent = stagehand.agent({
  cua: true,
  model: "google/gemini-2.5-computer-use-preview-10-2025",
  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env
  // ... other agent options
});
ProviderModel
Googlegoogle/gemini-2.5-computer-use-preview-10-2025
Anthropicanthropic/claude-3-7-sonnet-latest
Anthropicanthropic/claude-haiku-4-5-20251001
Anthropicanthropic/claude-sonnet-4-20250514
Anthropicanthropic/claude-sonnet-4-5-20250929
OpenAIopenai/computer-use-preview
OpenAIopenai/computer-use-preview-2025-03-11
For overriding the agent API key, using a corporate proxy, adding provider-specific options, or other advanced use cases, the agent model can also take the form of an object. To learn more, see the Agent Reference.

​
Custom Endpoints

If you need Azure OpenAI deployments or enterprise deployments.
  • OpenAI
  • Anthropic
  • All Other Providers
For OpenAI, you can pass configuration directly without using llmClient using the model parameter:
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: {
    model: "openai/gpt-5",
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: "https://custom-openai-endpoint.com/v1"
  }
});

​
Extending the AI SDK Client

For advanced use cases like custom retries or caching logic, you can extend the AISdkClient: 
import { LLMClient } from "@browserbasehq/stagehand";

class CustomRetryClient extends LLMClient {
  async createChatCompletion(options) {
    let retries = 3;
    while (retries > 0) {
      try {
        return await super.createChatCompletion(options);
      } catch (error) {
        retries--;
        if (retries === 0) throw error;
        await new Promise((r) => setTimeout(r, 1000 * (4 - retries)));
      }
    }
  }
}
Need custom caching? Consider using built-in caching feature.

​
Legacy Model Format

Recommendation: Use provider/model format. Example:
  • model: "openai/gpt-4o" (recommended)
  • model: "gpt-4o" (legacy)
The following models work without the provider/ prefix in the model parameter as part of legacy support:
  • gemini-2.5-flash-preview-04-17
  • gemini-2.5-pro-preview-03-25
  • gemini-2.0-flash
  • gemini-2.0-flash-lite
  • gemini-1.5-flash
  • gemini-1.5-flash-8b
  • gemini-1.5-pro
  • claude-3-7-sonnet-latest
  • claude-3-7-sonnet-20250219
  • claude-3-5-sonnet-latest
  • claude-3-5-sonnet-20241022
  • claude-3-5-sonnet-20240620
  • gpt-4o
  • gpt-4o-mini
  • o1
  • o1-mini
  • o3
  • o3-mini
  • gpt-4.1
  • gpt-4.1-mini
  • gpt-4.1-nano
  • o4-mini
  • gpt-4.5-preview
  • gpt-4o-2024-08-06
  • o1-preview
  • cerebras-llama-3.3-70b
  • cerebras-llama-3.1-8b
  • groq-llama-3.3-70b-versatile
  • groq-llama-3.3-70b-specdec
  • moonshotai/kimi-k2-instruct

​
Troubleshooting

Error: API key not foundSolutions:
  • Check .env file has the correct variable name for the provider you are using
  • Ensure environment variables are loaded (use dotenv)
  • Restart your application after updating .env file
ProviderEnvironment Variable
GoogleGOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY
AnthropicANTHROPIC_API_KEY
OpenAIOPENAI_API_KEY
AzureAZURE_API_KEY
CerebrasCEREBRAS_API_KEY
DeepSeekDEEPSEEK_API_KEY
GroqGROQ_API_KEY
MistralMISTRAL_API_KEY
OllamaNone (local)
PerplexityPERPLEXITY_API_KEY
TogetherAITOGETHER_AI_API_KEY
xAIXAI_API_KEY
Error: Unsupported modelSolutions:
  • Use the provider/model format: openai/gpt-5
  • Verify the model name exists in the provider’s documentation
  • Check model name is spelled correctly
  • Ensure your Model API key can access the model
Error: Model does not support structured outputsSolutions:
Symptoms: Automation is expensive or slowSolutions:
  • Switch to cost-effective models (check evals for comparisons)
  • Use faster models for simple tasks, powerful ones for complex tasks
  • Implement caching for repeated patterns
We are working on Python support for Stagehand v3 and custom models.Solutions:

​
Need Help? Contact Support

Can’t find a solution? Have a question? Reach out to our support team:

​
Next Steps

Prompting Guide

Learn how to prompt LLMs for optimal results

Run Evals

Test which models work best for your specific use case

Caching Guide

Cache responses to reduce costs and improve speed

Optimize Costs

Reduce LLM spending with caching and smart model selection