--- title: Models sidebarTitle: Models description: Use any LLM model with Stagehand for optimal performance --- import { V3Banner } from '/snippets/v3-banner.mdx'; Understand web pages, plan actions, and interact with complex interfaces with Google, OpenAI, Anthropic, xAI, DeepSeek, Perplexity, Azure, Ollama, the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway), or any other LLM model from [the Vercel AI SDK](https://sdk.vercel.ai/providers). --- ## 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): ```typescript TypeScript 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. ```typescript TypeScript 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 →](https://ai.google.dev/gemini-api/docs/models) Google Vertex requires `experimental: true` in the Stagehand constructor. ```typescript TypeScript 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 →](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models) ```typescript TypeScript 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 →](https://docs.anthropic.com/en/docs/models-overview) ```typescript TypeScript 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 →](https://platform.openai.com/docs/models) ```typescript TypeScript 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 →](https://ai.azure.com/catalog) ```typescript TypeScript 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 →](https://inference-docs.cerebras.ai/models/overview) ```typescript TypeScript 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 →](https://api-docs.deepseek.com/quick_start/pricing) ```typescript TypeScript 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 →](https://console.groq.com/docs/models) ```typescript TypeScript 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 →](https://docs.mistral.ai/getting-started/models) ```typescript TypeScript 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 →](https://ollama.com/library) ```typescript TypeScript 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 →](https://docs.perplexity.ai/getting-started/models) ```typescript TypeScript 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 →](https://www.together.ai/models) ```typescript TypeScript 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 →](https://docs.x.ai/docs/models) --- ### Custom Models Amazon Bedrock, Cohere, all [first class models](/v3/configuration/models#first-class-models), and any model from [the Vercel AI SDK](https://sdk.vercel.ai/providers) is supported. Use this configuration for custom endpoints and custom retry or caching logic. We'll use Amazon Bedrock and Google as examples below. Install the Vercel AI SDK for your provider. ```bash npm install @ai-sdk/amazon-bedrock ``` ```bash pnpm add @ai-sdk/amazon-bedrock ``` ```bash yarn add @ai-sdk/amazon-bedrock ``` ```bash bun add @ai-sdk/amazon-bedrock ``` ```typescript 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"), }); ``` ```typescript const stagehand = new Stagehand({ env: "BROWSERBASE", llmClient: bedrockClient }); await stagehand.init(); ``` Install the Vercel AI SDK for your provider. ```bash npm install @ai-sdk/google ``` ```bash pnpm add @ai-sdk/google ``` ```bash yarn add @ai-sdk/google ``` ```bash bun add @ai-sdk/google ``` ```typescript 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"), }); ``` ```typescript 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](https://sdk.vercel.ai/providers). Install the Vercel AI SDK for your provider. ```typescript import { createProvider } from '@ai-sdk/provider'; import { AISdkClient } from '@browserbasehq/stagehand'; const provider = createProvider({ apiKey: 'xxxxxxxxx', }); const providerClient = new AISdkClient({ model: provider("model/name"), }); ``` ```typescript 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. 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](/v3/configuration/models#first-class-models) and [custom](/v3/configuration/models#custom-models)) are supported. Here's an example with Gemini: ```typescript 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](/v3/configuration/models#first-class-models) model, including [computer use agents (CUA)](/v3/configuration/models#agent-models-with-cua-support). 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. ```typescript 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 }); ``` ```typescript const agent = stagehand.agent({ mode: "cua", model: "anthropic/claude-sonnet-4-6", // ANTHROPIC_API_KEY is auto-loaded from .env // ... other agent options }); ``` ```typescript 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](/v3/configuration/models#first-class-models) are supported. Here's an example with Gemini: ```typescript const agent = stagehand.agent({ model: "google/gemini-2.5-pro", // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env // ... other agent options }); ``` | 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](/v3/references/agent). --- ### Custom Endpoints If you need Azure OpenAI deployments or enterprise deployments. For OpenAI, you can pass configuration directly without using `llmClient` using the `model` parameter: ```typescript 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: ```typescript 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: ```typescript // 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](https://vercel.com/docs/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 Use the `gateway/` prefix followed by the provider and model name: ```typescript 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: ```typescript // 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: ```typescript 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 →](https://vercel.com/docs/ai-gateway/models-and-providers) --- ### Extending the AI SDK Client For advanced use cases like custom retries or caching logic, you can extend the `AISdkClient`: ```typescript 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](/v3/best-practices/caching). --- ### 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-sonnet-4-6` - `claude-sonnet-4-5-20250929` - `claude-haiku-4-5-20251001` - `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 found` **Solutions:** - 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` | | Vertex | Service account credentials (see [setup](#first-class-models)) | | 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:** `Unsupported model` **Solutions:** - 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 outputs` **Solutions:** - Check our [Model Evaluation page](https://www.stagehand.dev/evals) for recommended models **Symptoms:** Automation is expensive or slow **Solutions:** - Switch to cost-effective models (check [evals](https://www.stagehand.dev/evals) for comparisons) - Use faster models for simple tasks, powerful ones for complex tasks - Implement [caching](/v3/best-practices/caching) for repeated patterns Python is now supported in Stagehand v3! The Python SDK uses a BYOB (Bring Your Own Browser) architecture. **Solutions:** - See the [Python SDK documentation](/v3/sdk/python) for installation and usage - Check the [Python migration guide](/v3/migrations/python) if upgrading from v2 ### Need Help? Contact Support Can't find a solution? Have a question? Reach out to our support team: Email us at support@browserbase.com --- ## Next Steps Learn how to prompt LLMs for optimal results Test which models work best for your specific use case Cache responses to reduce costs and improve speed Reduce LLM spending with caching and smart model selection