Models

(NEW) Model Gateway — Use your Browserbase API key to access top models from OpenAI, Anthropic, and Google. One key, one bill, no provider accounts needed. Read the blog

Model Gateway

Model Gateway lets you use Stagehand without wiring up model providers yourself. Instead of managing separate API keys for each provider, just pass your Browserbase API key and pick a model. Browserbase routes the request to the upstream provider for you.

Setup

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "openai/gpt-5",
});

await stagehand.init();

When only a Browserbase API key is provided (without a provider-specific API key), Stagehand automatically routes model requests through Model Gateway. No additional configuration is needed.

Model Gateway requires Browserbase-hosted browsers. It does not work with env: "LOCAL".

Switching models

With Model Gateway, switching between providers is just a config change — no new accounts, API keys, or code rewiring required:

OpenAI
Anthropic
Google

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "openai/gpt-5",
});

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "anthropic/claude-sonnet-4-6",
});

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-3-flash-preview",
});

Key benefits

One key, one bill — LLM inference, browser infrastructure, and caching all run through your Browserbase API key.
Market-price tokens — We charge the same price as going direct to the provider. No markup.
Built-in reliability — Retries, backoff, and rate limit handling are managed for you.
No tier-gating — Access new models immediately without hitting provider spend thresholds.
Action caching — Model Gateway works with Stagehand’s managed action caching, so repeated steps are reused instead of re-run.

Supported providers

Provider	Example Model
OpenAI	`openai/gpt-5`
Anthropic	`anthropic/claude-sonnet-4-6`
Google	`google/gemini-2.5-flash`

Need a provider that isn’t listed? Reach out — we’re happy to work with teams on additional model support.

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 →

Google Vertex requires experimental: true in the Stagehand constructor.

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  experimental: true, // required for Vertex
  model: {
    modelName: "vertex/gemini-3-flash-preview",
    project: "your-gcp-project-id",
    location: "us-central1",
    googleAuthOptions: {
      credentials: {
        client_email: "your-sa@project.iam.gserviceaccount.com",
        private_key: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY,
      },
    },
  },
});

await stagehand.init();

The model object accepts:

modelName — The Vertex model, prefixed with vertex/ (e.g. vertex/gemini-3-flash-preview)
project — Your GCP project ID
location — Your Vertex AI region (e.g. us-central1)
googleAuthOptions.credentials — Service account credentials with client_email and private_key

View all supported Vertex AI 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-sonnet-4-6",
  // 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
Anthropic	`anthropic/claude-haiku-4-5-20251001`
Anthropic	`anthropic/claude-sonnet-4-6`
Anthropic	`anthropic/claude-sonnet-4-5-20250929`
Anthropic	`anthropic/claude-opus-4-5-20251101`
Anthropic	`anthropic/claude-opus-4-6`
Google	`google/gemini-2.5-computer-use-preview-10-2025`
Google	`google/gemini-3-flash-preview`
Google	`google/gemini-3-pro-preview`
Microsoft	`microsoft/fara-7b`
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,
});

AI Gateway

The Vercel AI Gateway lets you access models from multiple providers (OpenAI, Anthropic, Google, and more) through a single API key and interface. No extra provider SDKs or per-provider API keys needed.

The AI Gateway is built into the ai package that Stagehand already uses — no additional dependencies required.

Key benefits:

Access models from all major providers with a single AI_GATEWAY_API_KEY
Automatic provider fallback and dynamic routing based on uptime and latency
Usage tracking and observability through the Vercel dashboard
Bring Your Own Key (BYOK) support for existing provider credentials

Simple
Custom Config

Use the gateway/ prefix followed by the provider and model name:

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

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

await stagehand.init();

Works with any model available on the gateway:

// Anthropic via gateway
model: "gateway/anthropic/claude-sonnet-4.5"

// Google via gateway
model: "gateway/google/gemini-3-flash-preview"

Pass the API key and optional base URL explicitly using the model object format:

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: {
    modelName: "gateway/openai/gpt-5",
    apiKey: process.env.AI_GATEWAY_API_KEY,
    baseURL: "https://ai-gateway.vercel.sh/v3/ai" // optional custom endpoint
  }
});

await stagehand.init();

View all available AI Gateway models →

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-sonnet-4-6
claude-sonnet-4-5-20250929
claude-haiku-4-5-20251001

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
Model Gateway	`BROWSERBASE_API_KEY` (no provider key needed)
Google	`GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY`
Vertex	Service account credentials (see setup)
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`
AI Gateway	`AI_GATEWAY_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

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Model Gateway

Setup

Switching models

Key benefits

Supported providers

Configuration Setup

Quick Start

First Class Models

Custom Models

Choose a Model

Model Selection Guide

Advanced Options

Agent Models (with CUA Support)

Custom Endpoints

AI Gateway

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

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

​Model Gateway

​Setup

​Switching models

​Key benefits

​Supported providers

​Configuration Setup

​Quick Start

​First Class Models

​Custom Models

​Choose a Model

Model Selection Guide

​Advanced Options

​Agent Models (with CUA Support)

​Custom Endpoints

​AI Gateway

​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

Model Gateway

Setup

Switching models

Key benefits

Supported providers

Configuration Setup

Quick Start

First Class Models

Custom Models

Choose a Model

Advanced Options

Agent Models (with CUA Support)

Custom Endpoints

AI Gateway

Extending the AI SDK Client

Legacy Model Format

Troubleshooting

Need Help? Contact Support

Next Steps