Models

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.

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 →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "anthropic/claude-haiku-4-5"
  // API key auto-loads from ANTHROPIC_API_KEY - set in your .env
});

await stagehand.init();

View all supported Anthropic models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "openai/gpt-5"
  // API key auto-loads from OPENAI_API_KEY - set in your .env
});

await stagehand.init();

View all supported OpenAI models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "azure/gpt-5"
  // API key auto-loads from AZURE_API_KEY - set in your .env
});

await stagehand.init();

View all supported Azure models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "cerebras/llama-4-scout"
  // API key auto-loads from CEREBRAS_API_KEY - set in your .env
});

await stagehand.init();

View all supported Cerebras models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "deepseek/deepseek-chat"
  // API key auto-loads from DEEPSEEK_API_KEY - set in your .env
});

await stagehand.init();

View all supported DeepSeek models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "groq/llama-3.1-8b-instant"
  // API key auto-loads from GROQ_API_KEY - set in your .env
});

await stagehand.init();

View all supported Groq models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "mistral/codestral-2508"
  // API key auto-loads from MISTRAL_API_KEY - set in your .env
});

await stagehand.init();

View all supported Mistral models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "ollama/llama3.2"
  // No API key required
});

await stagehand.init();

View all supported Ollama models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "perplexity/sonar-reasoning"
  // API key auto-loads from PERPLEXITY_API_KEY - set in your .env
});

await stagehand.init();

View all supported Perplexity models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "togetherai/Qwen/Qwen3-235B-A22B-Instruct-2507-tput"
  // API key auto-loads from TOGETHER_AI_API_KEY - set in your .env
});

await stagehand.init();

View all supported TogetherAI models →

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "xai/grok-4-fast-reasoning"
  // API key auto-loads from XAI_API_KEY - set in your .env
});

await stagehand.init();

View all xAI 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.

Amazon Bedrock

Install dependencies

Install the Vercel AI SDK for your provider.

npm
pnpm
yarn
bun

npm install @ai-sdk/amazon-bedrock

pnpm add @ai-sdk/amazon-bedrock

yarn add @ai-sdk/amazon-bedrock

bun add @ai-sdk/amazon-bedrock

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"),
});

Pass client to Stagehand

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

await stagehand.init();

Google

Install dependencies

Install the Vercel AI SDK for your provider.

npm
pnpm
yarn
bun

npm install @ai-sdk/google

pnpm add @ai-sdk/google

yarn add @ai-sdk/google

bun add @ai-sdk/google

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"),
});

Pass client to Stagehand

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

await stagehand.init();

All Providers

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.

Install dependencies

Install the Vercel AI SDK for your provider.

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"),
});

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 Case	Recommended Model	Why
Production	`google/gemini-2.5-flash`	Fast, accurate, cost-effective
Intelligence	`google/gemini-3-pro-preview`	Best accuracy on hard tasks
Speed	`google/gemini-2.5-flash`	Fastest response times
Cost	`google/gemini-2.5-flash`	Best value per token
Local/offline	`ollama/qwen3`	No 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 mode: "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.

Deprecation Notice: The cua: true option is deprecated and will be removed in a future version. Use mode: "cua" instead.

Google CUA
Anthropic CUA
OpenAI CUA
Example First Class Model

const agent = stagehand.agent({
  mode: "cua",
  model: "google/gemini-2.5-computer-use-preview-10-2025",
  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env
  // ... other agent options
});

const agent = stagehand.agent({
  mode: "cua",
  model: "anthropic/claude-3-7-sonnet-latest",
  // ANTHROPIC_API_KEY is auto-loaded from .env
  // ... other agent options
});

const agent = stagehand.agent({
  mode: "cua",
  model: "openai/computer-use-preview",
  // OPENAI_API_KEY is auto-loaded from .env
  // ... other agent options
});

All first class models are supported. Here’s an example with Gemini:

const agent = stagehand.agent({
  model: "google/gemini-2.5-pro",
  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env
  // ... other agent options
});

All Supported CUA Models

Provider	Model
Google	`google/gemini-2.5-computer-use-preview-10-2025`
Anthropic	`anthropic/claude-3-7-sonnet-latest`
Anthropic	`anthropic/claude-haiku-4-5-20251001`
Anthropic	`anthropic/claude-sonnet-4-20250514`
Anthropic	`anthropic/claude-sonnet-4-5-20250929`
OpenAI	`openai/computer-use-preview`
OpenAI	`openai/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: {
    modelName: "openai/gpt-5",
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: "https://custom-openai-endpoint.com/v1"
  }
});

For Anthropic, you can pass configuration directly without using llmClient using the model parameter:

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: {
    modelName: "anthropic/claude-haiku-4-5",
    apiKey: process.env.ANTHROPIC_API_KEY,
    baseURL: "https://custom-anthropic-endpoint.com",
  },
});

For all other providers, use llmClient. Here’s an example with Hugging Face:

// pnpm add @ai-sdk/huggingface

import { createHuggingFace } from "@ai-sdk/huggingface";
import { AISdkClient } from "@browserbasehq/stagehand";

const huggingFaceProvider = createHuggingFace({
  apiKey: process.env.HUGGINGFACE_API_KEY,
  baseURL: "https://custom-huggingface-endpoint.com",
});

const huggingFaceClient = new AISdkClient({
  model: huggingFaceProvider("meta-llama/Llama-3.1-8B-Instruct"),
});

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

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:

Google

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

Anthropic

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

OpenAI

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

cerebras-llama-3.3-70b
cerebras-llama-3.1-8b

Groq

groq-llama-3.3-70b-versatile
groq-llama-3.3-70b-specdec
moonshotai/kimi-k2-instruct

Troubleshooting

Error: API key not found

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

Provider	Environment Variable
Google	`GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY`
Anthropic	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
Azure	`AZURE_API_KEY`
Cerebras	`CEREBRAS_API_KEY`
DeepSeek	`DEEPSEEK_API_KEY`
Groq	`GROQ_API_KEY`
Mistral	`MISTRAL_API_KEY`
Ollama	None (local)
Perplexity	`PERPLEXITY_API_KEY`
TogetherAI	`TOGETHER_AI_API_KEY`
xAI	`XAI_API_KEY`

Error: Model not supported

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

Model doesn't support structured outputs

Error: Model does not support structured outputsSolutions:

Check our Model Evaluation page for recommended models

High costs or slow performance

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

Python SDK or custom models

Python is now supported in Stagehand v3! The Python SDK uses a BYOB (Bring Your Own Browser) architecture.Solutions:

See the Python SDK documentation for installation and usage
Check the Python migration guide if upgrading from v2

Need Help? Contact Support

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

Contact Support

Email us at support@browserbase.com

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

Contact Support

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Configuration Setup

Quick Start

First Class Models

Custom Models

Choose a Model

Model Selection Guide

Advanced Options

Agent Models (with CUA Support)

Custom Endpoints

Extending the AI SDK Client

Legacy Model Format

Troubleshooting

Need Help? Contact Support

Next Steps

Prompting Guide

Run Evals

Caching Guide

Optimize Costs

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

​Configuration Setup

​Quick Start

​First Class Models

​Custom Models

​Choose a Model

Model Selection Guide

​Advanced Options

​Agent Models (with CUA Support)

​Custom Endpoints

​Extending the AI SDK Client

​Legacy Model Format

​Troubleshooting

​Need Help? Contact Support

Contact Support

​Next Steps

Prompting Guide

Run Evals

Caching Guide

Optimize Costs

Configuration Setup

Quick Start

First Class Models

Custom Models

Choose a Model

Advanced Options

Agent Models (with CUA Support)

Custom Endpoints

Extending the AI SDK Client

Legacy Model Format

Troubleshooting

Need Help? Contact Support

Next Steps