Update docs / logging to reflect gpt 5.4 and gemini 3.1 family compatibility with hybrid agent

[tkattkat]

…ability with agent hybrid mode

why

Currently when hybrid mode is used with a non anthropic, or gemini 3 flash model we throw a warning and only recommend those in docs.

what changed

We now do not throw a warning for gpt 5.4 family, or gemini 3.1 as both work well with vision based actions

test plan

Tested models locally to ensure work well with vision based actions

---

Summary by cubic

Stop showing the hybrid-mode warning for openai/gpt-5.4, openai/gpt-5.4-mini, and google/gemini-3.1-*.
Update docs to recommend google/gemini-3-flash-preview, google/gemini-3.1-flash-live-preview, google/gemini-3.1-pro-preview, openai/gpt-5.4*, and any anthropic/claude-* for vision-based actions, and fix a minor typo.

^{Written for commit 7a84b43. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7a84b43

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	Mar 31, 2026, 7:46 PM

[cubic-dev-ai]

2 issues found across 4 files

Confidence score: 4/5

• Main concern is the new hardcoded model-name allowlist in packages/core/lib/v3/handlers/v3AgentHandler.ts, which conflicts with the stated rule and could constrain hybrid mode behavior.
• Other issue is a minor documentation typo in .changeset/tricky-bats-pay.md, so overall impact is low and this seems safe to merge with small follow-ups.
• Pay close attention to packages/core/lib/v3/handlers/v3AgentHandler.ts - avoid extending hardcoded allowed-model lists in the new logic.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".changeset/tricky-bats-pay.md">

<violation number="1" location=".changeset/tricky-bats-pay.md:5">
P3: Fix the typo in the changeset summary (`compatability` → `compatibility`) to keep release notes/docs professional and searchable.</violation>
</file>

<file name="packages/core/lib/v3/handlers/v3AgentHandler.ts">

<violation number="1" location="packages/core/lib/v3/handlers/v3AgentHandler.ts:170">
P2: Custom agent: **Ensure we never check against hardcoded lists of allowed LLM model names**

New code extends a hardcoded model-name allowlist for hybrid mode, which violates the rule prohibiting new hardcoded allowed-model checks.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer / Client
    participant Core as Stagehand Core
    participant Agent as V3AgentHandler
    participant Logger as Internal Logger

    Note over Dev,Agent: Hybrid Mode Initialization Flow

    Dev->>Core: Constructor(model, mode: "hybrid")
    Core->>Agent: Initialize(baseModel, mode)
    
    Agent->>Agent: Check Hybrid Compatibility

    alt Mode is "hybrid"
        rect rgb(240, 240, 240)
            Note right of Agent: Validation Logic
            alt Model matches gemini-3, claude, OR NEW: gpt-5.4, gemini-3.1
                Agent->>Agent: Proceed without warning
            else Other models (e.g., GPT-4o, older Gemini)
                Agent->>Logger: CHANGED: Log recommendation warning
                Note right of Logger: Suggests gemini-3.1, gpt-5.4, or Claude
            end
        end
    else Mode is "dom" or "cua"
        Agent->>Agent: Skip compatibility check
    end

    Agent-->>Core: Handler Ready
    Core-->>Dev: Stagehand Instance Created

    Note over Dev,Agent: Vision-Based Action Execution
    Dev->>Core: act("click the login button")
    Core->>Agent: Execute action
    Agent->>Agent: Perform Vision/Coordinate-based action
    Agent-->>Dev: Action Result

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}