> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-stg-1784.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Enhance Stagehand with LLMs for optimal performance, cost, and reliability

Stagehand uses Large Language Models (LLMs) to understand web pages, plan actions, and interact with complex interfaces. The choice of LLM significantly impacts your automation's accuracy, speed, and cost.

<Card title="Model Evaluation" href="https://www.stagehand.dev/evals" icon="paper-plane">
  Find more details about how to choose the right model on our Model Evaluation page.
</Card>

## Why LLM Choice Matters

* **Accuracy**: Better models provide more reliable element detection and action planning
* **Speed**: Faster models reduce automation latency
* **Cost**: Different providers offer varying pricing structures
* **Reliability**: Structured output support ensures consistent automation behavior

<Tip>
  Find more details about how to choose the right model on our [Model Evaluation](https://www.stagehand.dev/evals) page.
</Tip>

<Warning>
  Small models on **Ollama** struggle with consistent structured outputs. While technically supported, we don't recommend them for production Stagehand workflows.
</Warning>

## Environment Variables Setup

Set up your API keys before configuring Stagehand:

<CodeGroup>
  ```bash .env theme={null}
  # Choose one or more providers
  OPENAI_API_KEY=your_openai_key_here
  ANTHROPIC_API_KEY=your_anthropic_key_here
  GOOGLE_API_KEY=your_google_key_here
  GROQ_API_KEY=your_groq_key_here
  ```
</CodeGroup>

## Supported Providers

Stagehand supports major LLM providers with structured output capabilities:

### Production-Ready Providers

| Provider      | Best Models                          | Strengths               | Use Case                  |
| ------------- | ------------------------------------ | ----------------------- | ------------------------- |
| **OpenAI**    | `gpt-4.1`, `gpt-4.1-mini`            | High accuracy, reliable | Production, complex sites |
| **Anthropic** | `claude-sonnet-4-6`                  | Excellent reasoning     | Complex automation tasks  |
| **Google**    | `gemini-2.5-flash`, `gemini-2.5-pro` | Fast, cost-effective    | High-volume automation    |

### Additional Providers

<Expandable title="More Providers">
  * **Groq** - `llama-3.3-70b-versatile` (Good for speed critical applications)
  * **xAI** - `grok-beta` (Good for complex reasoning)
  * **Azure** - Enterprise OpenAI deployment
  * **Cerebras** - High-speed inference
  * **TogetherAI** - Open-source models
  * **Mistral** - `mixtral-8x7b-32768` (European option)
  * **DeepSeek** - Cost-effective alternative
  * **Perplexity** - Real-time web data
  * **Ollama** - Local deployment (limited accuracy)
  * **Run any model included in AI SDK** - Find supported models in the [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) (Follow the guide
    [here](#vercel-ai-sdk) to get started.)
</Expandable>

## Basic Configuration

### Model Name Format

Stagehand uses the format `provider/model-name` for model specification.

**Examples:**

* OpenAI: `openai/gpt-4.1`
* Anthropic: `anthropic/claude-sonnet-4-6`
* Google: `google/gemini-2.5-flash` (Recommended)

### Quick Start Examples

<Tabs>
  <Tab title="Google (Recommended)">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { Stagehand } from "@browserbasehq/stagehand";

      const stagehand = new Stagehand({
        modelName: "google/gemini-2.5-flash",
        modelClientOptions: {
          apiKey: process.env.GOOGLE_API_KEY,
        },
      });
      ```

      ```python Python theme={null}
      import os
      from stagehand import Stagehand

      stagehand = Stagehand(
          model_name="google/gemini-2.5-flash",
          model_api_key=os.getenv("GOOGLE_API_KEY")
      )
      ```
    </CodeGroup>
  </Tab>

  <Tab title="OpenAI">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { Stagehand } from "@browserbasehq/stagehand";

      const stagehand = new Stagehand({
        modelName: "openai/gpt-4.1",
        modelClientOptions: {
          apiKey: process.env.OPENAI_API_KEY,
        },
      });
      ```

      ```python Python theme={null}
      import os
      from stagehand import Stagehand

      stagehand = Stagehand(
          model_name="openai/gpt-4.1",
          model_api_key=os.getenv("OPENAI_API_KEY")
      )
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Anthropic">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { Stagehand } from "@browserbasehq/stagehand";

      const stagehand = new Stagehand({
        modelName: "anthropic/claude-sonnet-4-6",
        modelClientOptions: {
          apiKey: process.env.ANTHROPIC_API_KEY,
        },
      });
      ```

      ```python Python theme={null}
      import os
      from stagehand import Stagehand

      stagehand = Stagehand(
          model_name="anthropic/claude-sonnet-4-6",
          model_api_key=os.getenv("ANTHROPIC_API_KEY")
      )
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Custom LLM Integration

<Note>
  Custom LLMs are currently only supported in TypeScript.
</Note>

Integrate any LLM with Stagehand using custom clients. The only requirement is **structured output support** for consistent automation behavior.

### Vercel AI SDK

The [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) is a popular library for interacting with LLMs. You can use any of the providers supported by the Vercel AI SDK to create a client for your model, **as long as they support structured outputs**.

Vercel AI SDK supports providers for OpenAI, Anthropic, and Google, along with support for **Amazon Bedrock** and **Azure OpenAI**.

To get started, you'll need to install the `ai` package and the provider you want to use. For example, to use Amazon Bedrock, you'll need to install the `@ai-sdk/amazon-bedrock` package.

You'll also need to use the [Vercel AI SDK external client](https://github.com/browserbase/stagehand/blob/v2/examples/external_clients/aisdk.ts) as a template to create a client for your model.

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install ai @ai-sdk/amazon-bedrock
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm install ai @ai-sdk/amazon-bedrock
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add ai @ai-sdk/amazon-bedrock
    ```
  </Tab>
</Tabs>

To get started, you can use the [Vercel AI SDK external client](https://github.com/browserbase/stagehand/blob/84f810b4631291307a32a47addad7e26e9c1deb3/examples/external_clients/aisdk.ts) as a template to create a client for your model.

```ts theme={null}
// Install/import the provider you want to use.
// For example, to use OpenAI, import `openai` from @ai-sdk/openai
import { bedrock } from "@ai-sdk/amazon-bedrock";
import { AISdkClient } from "./external_clients/aisdk";

const stagehand = new Stagehand({
  llmClient: new AISdkClient({
	model: bedrock("anthropic.claude-sonnet-4-6-v1:0"),
  }),
});
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Model doesn't support structured outputs">
    **Error**: `Model does not support structured outputs`

    **Solution**:
    Use models that support function calling/structured outputs. The minimum requirements are:

    * Model must support JSON/structured outputs
    * Model must have strong reasoning capabilities
    * Model must be able to handle complex instructions

    For each provider, use their latest models that meet these requirements. Some examples:

    * **OpenAI**: GPT-4 series or newer
    * **Anthropic**: Claude 3 series or newer
    * **Google**: Gemini 2 series or newer
    * **Other providers**: Latest models with structured output support

    **Note**: Avoid base language models without structured output capabilities or fine-tuning for instruction following. When in doubt, check our [Model Evaluation](https://www.stagehand.dev/evals) page for up-to-date recommendations.
  </Accordion>

  <Accordion title="Authentication errors">
    **Error**: `Invalid API key` or `Unauthorized`

    **Solution**:

    * Verify your environment variables are set correctly
    * Check API key permissions and quotas
    * Ensure you're using the correct API key for the provider
    * For Anthropic, make sure you have access to the Claude API
  </Accordion>

  <Accordion title="Inconsistent automation results">
    **Symptoms**: Actions work sometimes but fail other times

    **Causes & Solutions**:

    * **Weak models**: Use more capable models - check our [Model Evaluation](https://www.stagehand.dev/evals) page for current recommendations
    * **High temperature**: Set temperature to 0 for deterministic outputs
    * **Complex pages**: Switch to models with higher accuracy scores on our [Model Evaluation](https://www.stagehand.dev/evals) page
    * **Rate limits**: Implement retry logic with exponential backoff
    * **Context limits**: Reduce page complexity or use models with larger context windows
    * **Prompt clarity**: Ensure your automation instructions are clear and specific
  </Accordion>

  <Accordion title="Slow performance">
    **Issue**: Automation takes too long to respond

    **Solutions**:

    * **Use fast models**: Choose models optimized for speed
      * Any model with \< 1s response time
      * Models with "fast" or "flash" variants
    * **Optimize settings**:
      * Use `verbose: 0` to minimize token usage
      * Set temperature to 0 for fastest processing
      * Keep max tokens as low as possible
    * **Consider local deployment**: Local models can provide lowest latency
    * **Batch operations**: Group multiple actions when possible
  </Accordion>

  <Accordion title="High costs">
    **Issue**: LLM usage costs are too high

    **Cost Optimization Strategies**:

    1. **Switch to cost-effective models**:
       * Check our [Model Evaluation](https://www.stagehand.dev/evals) page for current cost-performance benchmarks
       * Choose models with lower cost per token that still meet accuracy requirements
       * Consider models optimized for speed to reduce total runtime costs
    2. **Optimize token usage**:
       * Set `verbose: 0` to reduce logging overhead
       * Use concise prompts and limit response length
    3. **Smart model selection**: Start with cheaper models, fallback to premium ones only when needed
    4. **Cache responses**: Implement LLM response caching for repeated automation patterns
    5. **Monitor usage**: Set up billing alerts and track costs per automation run
    6. **Batch processing**: Process multiple similar tasks together
  </Accordion>
</AccordionGroup>

### Next Steps

<CardGroup cols={2}>
  <Card title="Choose Models" href="https://www.stagehand.dev/evals" icon="robot">
    See our Model Evaluation page
  </Card>

  <Card title="Test Models" href="/v2/configuration/evals" icon="flask-vial">
    Evaluate performance on your specific use cases in our Model Evaluation guide
  </Card>

  <Card title="Track Costs" href="/v2/configuration/observability" icon="chart-line">
    Monitor token usage and set alerts using our Observability tools
  </Card>

  <Card title="Cache Results" href="/v2/best-practices/caching" icon="database">
    Store successful patterns using our Caching Guide
  </Card>
</CardGroup>