{"repo": "cannonbold2412/research", "files": {"repos/stagehand-main/packages/docs/v3/configuration/models.mdx": {"465ddc6584606f791d2d394ee07786bdb1464e27": {"t": 1786068442.5032883, "n": 25636, "h": "2a1e9fbdd8a2684c", "c": "---\ntitle: Models\nsidebarTitle: Models\ndescription: Use any LLM model with Stagehand\n---\nimport { V3Banner } from '/snippets/v3-banner.mdx';\n\n<V3Banner />\n\n\n<Callout icon=\"sparkles\" color=\"#FFC107\" iconType=\"regular\">\n  **(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](https://www.browserbase.com/blog/model-gateway)\n</Callout>\n\n## Model Gateway\n\nModel 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.\n\n### Setup\n\n```typescript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"openai/gpt-5\",\n});\n\nawait stagehand.init();\n```\n\nWhen 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.\n\n<Note>\n  Model Gateway requires Browserbase-hosted browsers. It does not work with `env: \"LOCAL\"`.\n</Note>\n\n### Switching models\n\nWith Model Gateway, switching between providers is just a config change — no new accounts, API keys, or code rewiring required:\n\n<Tabs>\n<Tab title=\"OpenAI\">\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"openai/gpt-5\",\n});\n```\n</Tab>\n<Tab title=\"Anthropic\">\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"anthropic/claude-sonnet-4-6\",\n});\n```\n</Tab>\n<Tab title=\"Google\">\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"google/gemini-3-flash-preview\",\n});\n```\n</Tab>\n</Tabs>\n\n### Key benefits\n\n- **One key, one bill** — LLM inference, browser infrastructure, and caching all run through your Browserbase API key.\n- **Market-price tokens** — We charge the same price as going direct to the provider. No markup.\n- **Built-in reliability** — Retries, backoff, and rate limit handling are managed for you.\n- **No tier-gating** — Access new models immediately without hitting provider spend thresholds.\n- **Action caching** — Model Gateway works with Stagehand's [managed action caching](/v3/best-practices/caching), so repeated steps are reused instead of re-run.\n\n### Supported providers\n\n| Provider   | Example Model                  |\n| ---------- | ------------------------------ |\n| OpenAI     | `openai/gpt-5`                |\n| Anthropic  | `anthropic/claude-sonnet-4-6` |\n| Google     | `google/gemini-2.5-flash`     |\n\n<Tip>\n  Need a provider that isn't listed? [Reach out](https://www.browserbase.com/contact) — we're happy to work with teams on additional model support.\n</Tip>\n\n---\n\n## Configuration Setup\n\n### Quick Start\n\n<Tip>\n  Set your API key in `.env` and Stagehand handles the rest. No explicit\n  configuration needed!\n</Tip>\n\nGet started with Google Gemini (recommended for speed and cost):\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"google/gemini-2.5-flash\"\n  // API key auto-loads from GOOGLE_GENERATIVE_AI_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n\n\n---\n\n### First Class Models\n\nUse any model from the following supported providers.\n\n<Tabs>\n<Tab title=\"Google\">\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"google/gemini-2.5-flash\"\n  // API key auto-loads from GOOGLE_GENERATIVE_AI_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n[View all supported Google models →](https://ai.google.dev/gemini-api/docs/models)\n</Tab>\n\n<Tab title=\"Google Vertex\">\n\n<Warning>\nGoogle Vertex requires `experimental: true` in the Stagehand constructor.\n</Warning>\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  experimental: true, // required for Vertex\n  model: {\n    modelName: \"vertex/gemini-3-flash-preview\",\n    project: \"your-gcp-project-id\",\n    location: \"us-central1\",\n    googleAuthOptions: {\n      credentials: {\n        client_email: \"your-sa@project.iam.gserviceaccount.com\",\n        private_key: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY,\n      },\n    },\n  },\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n\nThe `model` object accepts:\n- `modelName` — The Vertex model, prefixed with `vertex/` (e.g. `vertex/gemini-3-flash-preview`)\n- `project` — Your GCP project ID\n- `location` — Your Vertex AI region (e.g. `us-central1`)\n- `googleAuthOptions.credentials` — Service account credentials with `client_email` and `private_key`\n\n[View all supported Vertex AI models →](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models)\n</Tab>\n\n<Tab title=\"Anthropic\">\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"anthropic/claude-haiku-4-5\"\n  // API key auto-loads from ANTHROPIC_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n[View all supported Anthropic models →](https://docs.anthropic.com/en/docs/models-overview)\n</Tab>\n\n<Tab title=\"OpenAI\">\n\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"openai/gpt-5\"\n  // API key auto-loads from OPENAI_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n[View all supported OpenAI models →](https://platform.openai.com/docs/models)\n</Tab>\n<Tab title=\"Azure\">\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"azure/gpt-5\"\n  // API key auto-loads from AZURE_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n[View all supported Azure models →](https://ai.azure.com/catalog)\n</Tab>\n\n<Tab title=\"Cerebras\">\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"cerebras/llama-4-scout\"\n  // API key auto-loads from CEREBRAS_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n[View all supported Cerebras models →](https://inference-docs.cerebras.ai/models/overview)\n</Tab>\n\n<Tab title=\"DeepSeek\">\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"deepseek/deepseek-chat\"\n  // API key auto-loads from DEEPSEEK_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n[View all supported DeepSeek models →](https://api-docs.deepseek.com/quick_start/pricing)\n</Tab>\n\n<Tab title=\"Groq\">\n\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"groq/llama-3.1-8b-instant\"\n  // API key auto-loads from GROQ_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n[View all supported Groq models →](https://console.groq.com/docs/models)\n</Tab>\n\n<Tab title=\"Mistral\">\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"mistral/codestral-2508\"\n  // API key auto-loads from MISTRAL_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n[View all supported Mistral models →](https://docs.mistral.ai/getting-started/models)\n</Tab>\n\n<Tab title=\"Ollama\">\n\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"ollama/llama3.2\"\n  // No API key required\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n[View all supported Ollama models →](https://ollama.com/library)\n</Tab>\n\n<Tab title=\"Perplexity\">\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"perplexity/sonar-reasoning\"\n  // API key auto-loads from PERPLEXITY_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n[View all supported Perplexity models →](https://docs.perplexity.ai/getting-started/models)\n</Tab>\n<Tab title=\"TogetherAI\">\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"togetherai/Qwen/Qwen3-235B-A22B-Instruct-2507-tput\"\n  // API key auto-loads from TOGETHER_AI_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n```\n\n</CodeGroup>\n[View all supported TogetherAI models →](https://www.together.ai/models)\n\n</Tab>\n<Tab title=\"xAI\">\n\n<CodeGroup>\n```typescript TypeScript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"xai/grok-4-fast-reasoning\"\n  // API key auto-loads from XAI_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n\n```\n</CodeGroup>\n\n[View all xAI models →](https://docs.x.ai/docs/models)\n</Tab>\n\n</Tabs>\n\n---\n\n### Custom Models\n\nAmazon 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.\n\nUse this configuration for custom endpoints and custom retry or caching logic.\n\nWe'll use Amazon Bedrock and Google as examples below.\n\n<AccordionGroup>\n<Accordion title=\"Amazon Bedrock\">\n\n<Steps>\n<Step title=\"Install dependencies\">\nInstall the Vercel AI SDK for your provider.\n\n<Tabs>\n<Tab title=\"npm\">\n```bash\nnpm install @ai-sdk/amazon-bedrock\n```\n\n</Tab>\n<Tab title=\"pnpm\">\n```bash\npnpm add @ai-sdk/amazon-bedrock\n```\n</Tab>\n<Tab title=\"yarn\">\n```bash\nyarn add @ai-sdk/amazon-bedrock\n```\n</Tab>\n<Tab title=\"bun\">\n```bash\nbun add @ai-sdk/amazon-bedrock\n```\n</Tab>\n</Tabs>\n</Step>\n\n<Step title=\"Import, create provider, and create client\">\n```typescript\nimport { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';\nimport { AISdkClient } from '@browserbasehq/stagehand';\n\nconst bedrockProvider = createAmazonBedrock({\n  region: 'us-east-1',\n  accessKeyId: 'xxxxxxxxx',\n  secretAccessKey: 'xxxxxxxxx',\n  sessionToken: 'xxxxxxxxx',\n});\n\nconst bedrockClient = new AISdkClient({\n  model: bedrockProvider(\"amazon/nova-pro-latest\"),\n});\n\n```\n</Step>\n\n<Step title=\"Pass client to Stagehand\">\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  llmClient: bedrockClient\n});\n\nawait stagehand.init();\n```\n\n</Step>\n</Steps>\n</Accordion>\n<Accordion title=\"Google\">\n\n<Steps>\n<Step title=\"Install dependencies\">\nInstall the Vercel AI SDK for your provider.\n\n<Tabs>\n<Tab title=\"npm\">\n```bash\nnpm install @ai-sdk/google\n```\n</Tab>\n<Tab title=\"pnpm\">\n```bash\npnpm add @ai-sdk/google\n```\n</Tab>\n<Tab title=\"yarn\">\n```bash\nyarn add @ai-sdk/google\n```\n</Tab>\n<Tab title=\"bun\">\n```bash\nbun add @ai-sdk/google\n```\n</Tab>\n</Tabs>\n</Step>\n\n<Step title=\"Import, create provider, and create client\">\n```typescript\nimport { createGoogle } from '@ai-sdk/google';\nimport { AISdkClient } from '@browserbasehq/stagehand';\n\nconst googleProvider = createGoogle({\n  apiKey: process.env.GEMINI_API_KEY,\n});\n\nconst googleClient = new AISdkClient({\n  model: googleProvider(\"google/gemini-2.5-flash\"),\n});\n\n```\n</Step>\n\n<Step title=\"Pass client to Stagehand\">\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  llmClient: googleClient\n});\n\nawait stagehand.init();\n```\n\n</Step>\n</Steps>\n</Accordion>\n<Accordion title=\"All Providers\">\n\nTo 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).\n\n<Steps>\n<Step title=\"Install dependencies\">\nInstall the Vercel AI SDK for your provider.\n</Step>\n<Step title=\"Import, create provider, and create client\">\n```typescript\nimport { createProvider } from '@ai-sdk/provider';\nimport { AISdkClient } from '@browserbasehq/stagehand';\n\nconst provider = createProvider({\n  apiKey: 'xxxxxxxxx',\n});\n\nconst providerClient = new AISdkClient({\n  model: provider(\"model/name\"),\n});\n\n```\n</Step>\n<Step title=\"Pass client to Stagehand\">\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  llmClient: providerClient\n});\n\nawait stagehand.init();\n```\n\n</Step>\n</Steps>\n</Accordion>\n</AccordionGroup>\n\n\n---\n\n## Choose a Model\n\nDifferent models excel at different tasks. Consider speed, accuracy, and cost for your use case.\n\n<Card title=\"Model Selection Guide\" href=\"https://www.stagehand.dev/evals\" icon=\"scale-balanced\">\n  Find detailed model comparisons and recommendations on our Model Evaluation page.\n</Card>\n\n**Quick Recommendations**\n\n| Use Case                  | Recommended Model                    | Why                            |\n| ------------------------- | ------------------------------------ | ------------------------------ |\n| **Production** | `google/gemini-2.5-flash`            | Fast, accurate, cost-effective |\n| **Intelligence**     | `google/gemini-3-pro-preview` | Best accuracy on hard tasks    |\n| **Speed**        | `google/gemini-2.5-flash`                 | Fastest response times         |\n| **Cost**     | `google/gemini-2.5-flash`            | Best value per token           |\n| **Local/offline**         | `ollama/qwen3`                    | No API costs, full control     |\n\n\n---\n\n## Advanced Options\n\n### Agent Models (with CUA Support)\n\n**Default**\n\nThe 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:\n\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"google/gemini-2.5-flash\",\n  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env\n  // ... other stagehand options\n});\n\n// Agent will use google/gemini-2.5-flash\nconst agent = stagehand.agent();\n```\n\n**Override (with CUA support)**\n\nHowever, 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.\n\n<Tip>\n  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.\n</Tip>\n\n<Warning>\n**Deprecation Notice:** The `cua: true` option is deprecated and will be removed in a future version. Use `mode: \"cua\"` instead.\n</Warning>\n\n<Tabs>\n<Tab title=\"Google CUA\">\n```typescript\nconst agent = stagehand.agent({\n  mode: \"cua\",\n  model: \"google/gemini-2.5-computer-use-preview-10-2025\",\n  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env\n  // ... other agent options\n});\n```\n</Tab>\n<Tab title=\"Anthropic CUA\">\n```typescript\nconst agent = stagehand.agent({\n  mode: \"cua\",\n  model: \"anthropic/claude-sonnet-4-6\",\n  // ANTHROPIC_API_KEY is auto-loaded from .env\n  // ... other agent options\n});\n```\n</Tab>\n<Tab title=\"OpenAI CUA\">\n```typescript\nconst agent = stagehand.agent({\n  mode: \"cua\",\n  model: \"openai/computer-use-preview\",\n  // OPENAI_API_KEY is auto-loaded from .env\n  // ... other agent options\n});\n```\n</Tab>\n<Tab title=\"Example First Class Model\">\nAll [first class models](/v3/configuration/models#first-class-models) are supported. Here's an example with Gemini:\n\n```typescript\nconst agent = stagehand.agent({\n  model: \"google/gemini-2.5-pro\",\n  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env\n  // ... other agent options\n});\n```\n</Tab>\n</Tabs>\n\n<Accordion title=\"All Supported CUA Models\">\n| Provider | Model |\n| -------- | ----- |\n| Anthropic | `anthropic/claude-haiku-4-5-20251001` |\n| Anthropic | `anthropic/claude-sonnet-4-6` |\n| Anthropic | `anthropic/claude-sonnet-4-5-20250929` |\n| Anthropic | `anthropic/claude-opus-4-5-20251101` |\n| Anthropic | `anthropic/claude-opus-4-6` |\n| Anthropic | `anthropic/claude-opus-4-8` |\n| Google   | `google/gemini-2.5-computer-use-preview-10-2025` |\n| Google   | `google/gemini-3-flash-preview` |\n| Google   | `google/gemini-3-pro-preview` |\n| Microsoft | `microsoft/fara-7b` |\n| OpenAI   | `openai/computer-use-preview` |\n| OpenAI   | `openai/computer-use-preview-2025-03-11` |\n</Accordion>\n\n<Note>\n  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).\n</Note>\n---\n\n### Custom Endpoints\n\nIf you need Azure OpenAI deployments or enterprise deployments.\n\n<Tabs>\n<Tab title=\"OpenAI\">\n\nFor OpenAI, you can pass configuration directly without using `llmClient` using the `model` parameter:\n\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: {\n    modelName: \"openai/gpt-5\",\n    apiKey: process.env.OPENAI_API_KEY,\n    baseURL: \"https://custom-openai-endpoint.com/v1\"\n  }\n});\n```\n\n</Tab>\n\n<Tab title=\"Anthropic\">\n\nFor Anthropic, you can pass configuration directly without using `llmClient` using the `model` parameter:\n\n```typescript\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: {\n    modelName: \"anthropic/claude-haiku-4-5\",\n    apiKey: process.env.ANTHROPIC_API_KEY,\n    baseURL: \"https://custom-anthropic-endpoint.com\",\n  },\n});\n```\n\n  </Tab>\n<Tab title=\"All Other Providers\">\nFor all other providers, use `llmClient`. Here's an example with Hugging Face:\n\n```typescript\n// pnpm add @ai-sdk/huggingface\n\nimport { createHuggingFace } from \"@ai-sdk/huggingface\";\nimport { AISdkClient } from \"@browserbasehq/stagehand\";\n\nconst huggingFaceProvider = createHuggingFace({\n  apiKey: process.env.HUGGINGFACE_API_KEY,\n  baseURL: \"https://custom-huggingface-endpoint.com\",\n});\n\nconst huggingFaceClient = new AISdkClient({\n  model: huggingFaceProvider(\"meta-llama/Llama-3.1-8B-Instruct\"),\n});\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  llmClient: huggingFaceClient,\n});\n```\n\n</Tab>\n</Tabs>\n\n---\n\n### AI Gateway\n\nThe [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.\n\n<Tip>\n  The AI Gateway is built into the `ai` package that Stagehand already uses -- no additional dependencies required.\n</Tip>\n\n**Key benefits:**\n- Access models from all major providers with a single `AI_GATEWAY_API_KEY`\n- Automatic provider fallback and dynamic routing based on uptime and latency\n- Usage tracking and observability through the Vercel dashboard\n- Bring Your Own Key (BYOK) support for existing provider credentials\n\n<Tabs>\n<Tab title=\"Simple\">\n\nUse the `gateway/` prefix followed by the provider and model name:\n\n```typescript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: \"gateway/openai/gpt-5\"\n  // API key auto-loads from AI_GATEWAY_API_KEY - set in your .env\n});\n\nawait stagehand.init();\n```\n\nWorks with any model available on the gateway:\n\n```typescript\n// Anthropic via gateway\nmodel: \"gateway/anthropic/claude-sonnet-4.5\"\n\n// Google via gateway\nmodel: \"gateway/google/gemini-3-flash-preview\"\n```\n\n</Tab>\n<Tab title=\"Custom Config\">\n\nPass the API key and optional base URL explicitly using the model object format:\n\n```typescript\nimport { Stagehand } from \"@browserbasehq/stagehand\";\n\nconst stagehand = new Stagehand({\n  env: \"BROWSERBASE\",\n  model: {\n    modelName: \"gateway/openai/gpt-5\",\n    apiKey: process.env.AI_GATEWAY_API_KEY,\n    baseURL: \"https://ai-gateway.vercel.sh/v3/ai\" // optional custom endpoint\n  }\n});\n\nawait stagehand.init();\n```\n\n</Tab>\n</Tabs>\n\n[View all available AI Gateway models →](https://vercel.com/docs/ai-gateway/models-and-providers)\n\n---\n\n### Extending the AI SDK Client\n\nFor advanced use cases like custom retries or caching logic, you can extend the `AISdkClient`:\n\n```typescript\nimport { LLMClient } from \"@browserbasehq/stagehand\";\n\nclass CustomRetryClient extends LLMClient {\n  async createChatCompletion(options) {\n    let retries = 3;\n    while (retries > 0) {\n      try {\n        return await super.createChatCompletion(options);\n      } catch (error) {\n        retries--;\n        if (retries === 0) throw error;\n        await new Promise((r) => setTimeout(r, 1000 * (4 - retries)));\n      }\n    }\n  }\n}\n```\n\n<Tip>\n  Need custom caching? Consider using built-in [caching\n  feature](/v3/best-practices/caching).\n</Tip>\n\n---\n\n### Legacy Model Format\n\n<Tip>\n**Recommendation:** Use `provider/model` format. Example:\n- `model: \"openai/gpt-4o\"` (recommended)\n- `model: \"gpt-4o\"` (legacy)\n\n</Tip>\n\nThe following models work without the `provider/` prefix in the model parameter as part of legacy support:\n\n<AccordionGroup title=\"Legacy Model Format\">\n<Accordion title=\"Google\">\n\n- `gemini-2.5-flash-preview-04-17`\n- `gemini-2.5-pro-preview-03-25`\n- `gemini-2.0-flash`\n- `gemini-2.0-flash-lite`\n- `gemini-1.5-flash`\n- `gemini-1.5-flash-8b`\n- `gemini-1.5-pro`\n\n</Accordion>\n<Accordion title=\"Anthropic\">\n\n- `claude-sonnet-4-6`\n- `claude-sonnet-4-5-20250929`\n- `claude-haiku-4-5-20251001`\n\n</Accordion>\n<Accordion title=\"OpenAI\">\n- `gpt-4o`\n- `gpt-4o-mini`\n- `o1`\n- `o1-mini`\n- `o3`\n- `o3-mini`\n- `gpt-4.1`\n- `gpt-4.1-mini`\n- `gpt-4.1-nano`\n- `o4-mini`\n- `gpt-4.5-preview`\n- `gpt-4o-2024-08-06`\n- `o1-preview`\n\n</Accordion>\n<Accordion title=\"Cerebras\">\n\n- `cerebras-llama-3.3-70b`\n- `cerebras-llama-3.1-8b`\n\n</Accordion>\n<Accordion title=\"Groq\">\n\n- `groq-llama-3.3-70b-versatile`\n- `groq-llama-3.3-70b-specdec`\n- `moonshotai/kimi-k2-instruct`\n\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Troubleshooting\n\n<AccordionGroup>\n<Accordion title=\"Error: API key not found\">\n**Error:** `API key not found`\n\n**Solutions:**\n\n- Check `.env` file has the correct variable name for the provider you are using\n- Ensure environment variables are loaded (use `dotenv`)\n- Restart your application after updating `.env` file\n\n| Provider   | Environment Variable           |\n| ---------- | ------------------------------ |\n| Model Gateway | `BROWSERBASE_API_KEY` (no provider key needed) |\n| Google     | `GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY` |\n| Vertex | Service account credentials (see [setup](#first-class-models)) |\n| Anthropic  | `ANTHROPIC_API_KEY`            |\n| OpenAI     | `OPENAI_API_KEY`               |\n| Azure      | `AZURE_API_KEY`                |\n| Cerebras   | `CEREBRAS_API_KEY`             |\n| DeepSeek   | `DEEPSEEK_API_KEY`             |\n| Groq       | `GROQ_API_KEY`                 |\n| Mistral    | `MISTRAL_API_KEY`              |\n| Ollama     | None (local)                   |\n| Perplexity | `PERPLEXITY_API_KEY`           |\n| TogetherAI | `TOGETHER_AI_API_KEY`          |\n| xAI        | `XAI_API_KEY`                  |\n| AI Gateway | `AI_GATEWAY_API_KEY`           |\n\n</Accordion>\n\n<Accordion title=\"Error: Model not supported\">\n**Error:** `Unsupported model`\n\n**Solutions:**\n\n- Use the `provider/model` format: `openai/gpt-5`\n- Verify the model name exists in the provider's documentation\n- Check model name is spelled correctly\n- Ensure your Model API key can access the model\n</Accordion>\n\n<Accordion title=\"Model doesn't support structured outputs\">\n**Error:** `Model does not support structured outputs`\n\n**Solutions:**\n\n- Check our [Model Evaluation page](https://www.stagehand.dev/evals) for recommended models\n</Accordion>\n\n<Accordion title=\"High costs or slow performance\">\n**Symptoms:** Automation is expensive or slow\n\n**Solutions:**\n\n- Switch to cost-effective models (check [evals](https://www.stagehand.dev/evals) for comparisons)\n- Use faster models for simple tasks, powerful ones for complex tasks\n- Implement [caching](/v3/best-practices/caching) for repeated patterns\n</Accordion>\n<Accordion title=\"Python SDK or custom models\">\nPython is now supported in Stagehand v3! The Python SDK uses a BYOB (Bring Your Own Browser) architecture.\n\n**Solutions:**\n\n- See the [Python SDK documentation](/v3/sdk/python) for installation and usage\n- Check the [Python migration guide](/v3/migrations/python) if upgrading from v2\n</Accordion>\n</AccordionGroup>\n\n### Need Help? Contact Support\n\nCan't find a solution? Have a question? Reach out to our support team:\n\n<Card\n  title=\"Contact Support\"\n  icon=\"envelope\"\n  href=\"mailto:support@browserbase.com\"\n>\n  Email us at support@browserbase.com\n</Card>\n\n---\n\n## Next Steps\n\n<CardGroup cols={2}>\n<Card title=\"Prompting Guide\" href=\"/v3/best-practices/prompting-best-practices\" icon=\"brain\">\n  Learn how to prompt LLMs for optimal results\n</Card>\n<Card title=\"Run Evals\" href=\"/v3/basics/evals\" icon=\"flask-vial\">\n  Test which models work best for your specific use case\n</Card>\n\n<Card title=\"Caching Guide\" href=\"/v3/best-practices/caching\" icon=\"database\">\n  Cache responses to reduce costs and improve speed\n</Card>\n<Card\n  title=\"Optimize Costs\"\n  href=\"/v3/best-practices/cost-optimization\"\n  icon=\"dollar-sign\"\n>\n  Reduce LLM spending with caching and smart model selection\n</Card>\n</CardGroup>\n"}}}}