Hybrid mode docs

[tkattkat]

why

currently we have no documentation on hybrid mode of agent

what changed

adds documentation on hybrid mode

test plan

---

Summary by cubic

Adds Hybrid mode docs for Stagehand Agent, showing how to combine DOM and coordinate-based actions with supported models. Also documents the new agent mode config and updates feature availability across CUA, DOM, and Hybrid.

• Migration
  • Set experimental: true in Stagehand constructor.
  • Use mode: "hybrid" in agent() and select a supported model.
  • Recommended models: google/gemini-3-flash-preview; anthropic/claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001.
  • highlightCursor defaults to true in Hybrid mode (can override).

^{Written for commit 0756fb6. Summary will update automatically on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0756fb6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="claude.md">

<violation number="1" location="claude.md:266">
P2: The hybrid mode description in the modes summary is inconsistent with the introduction paragraph. The intro correctly lists `(act, click, type, dragAndDrop)` but this line omits `act`. Consider adding `act` to maintain consistency.

(Based on your team&#39;s feedback about &#39;act&#39; tool being included in hybrid mode.) [FEEDBACK_USED]</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[greptile-apps]

Greptile Summary

Adds comprehensive documentation for Hybrid mode in Stagehand Agent across all documentation files.

What changed:

• Added Agent Hybrid Mode section to claude.md with recommended models and example code
• Updated feature availability table in packages/docs/v3/basics/agent.mdx to include Hybrid column alongside CUA and DOM modes
• Added detailed Hybrid Mode subsection with model requirements warnings and two code examples (Google and Anthropic)
• Added mode parameter documentation to API reference in packages/docs/v3/references/agent.mdx
• Included Hybrid Mode tab in code examples section with full implementation details

Key points:

• Hybrid mode combines DOM-based tools (act, fillForm) and coordinate-based tools (click, type, dragAndDrop, clickAndHold)
• Requires experimental: true in Stagehand constructor
• Only specific models are recommended: google/gemini-3-flash-preview (recommended), anthropic/claude-sonnet-4-20250514, anthropic/claude-sonnet-4-5-20250929, anthropic/claude-haiku-4-5-20251001
• highlightCursor defaults to true in hybrid mode
• Documentation is consistent across all three files with appropriate warnings about model requirements

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• Documentation-only changes that are well-structured, consistent across all files, include appropriate warnings, and follow established documentation patterns. Code examples are syntactically correct with proper TypeScript formatting and camelCase naming conventions.
• No files require special attention

Important Files Changed

Filename	Overview
claude.md	Added comprehensive Agent Hybrid Mode section with model recommendations, code examples, and mode explanations
packages/docs/v3/basics/agent.mdx	Updated feature availability table and added detailed Hybrid Mode section with warnings and code examples
packages/docs/v3/references/agent.mdx	Added mode parameter documentation and Hybrid Mode code example tab with model requirements

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant Agent
    participant Browser
    participant LLM
    
    User->>Stagehand: new Stagehand({experimental: true})
    User->>Stagehand: init()
    User->>Agent: agent({mode: "hybrid", model: "google/gemini-3-flash-preview"})
    Agent-->>User: AgentInstance
    
    User->>Agent: execute({instruction, maxSteps})
    
    loop Until task complete or maxSteps reached
        Agent->>Browser: Take screenshot
        Browser-->>Agent: Screenshot
        Agent->>Browser: Get DOM structure
        Browser-->>Agent: DOM data
        Agent->>LLM: Process with both visual and DOM context
        LLM-->>Agent: Decision (coordinate-based or DOM-based action)
        
        alt DOM-based action (act, fillForm)
            Agent->>Browser: DOM-based interaction
        else Coordinate-based action (click, type, dragAndDrop)
            Agent->>Browser: Coordinate-based interaction
        end
        
        Browser-->>Agent: Action result
    end
    
    Agent-->>User: AgentResult{success, message, actions, completed}

Loading

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}