add warning when models are used with hybrid mode that will not perf…

.changeset/late-parks-taste.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add warning when incorrect models are used with agents hybrid mode

packages/core/lib/v3/handlers/v3AgentHandler.ts

@@ -113,6 +113,18 @@ export class V3AgentHandler {
         },
       });
 
+      if (
+        this.mode === "hybrid" &&
+        !baseModel.modelId.includes("gemini-3-flash") &&
+        !baseModel.modelId.includes("claude")
+      ) {
+        this.logger({
+          category: "agent",
+          message: `Warning: "${baseModel.modelId}" may not perform well in hybrid mode. See recommended models: https://docs.stagehand.dev/v3/basics/agent#hybrid-mode`,
+          level: 0,
+        });
+      }
+
       return {
         options,
         maxSteps,

packages/docs/v3/basics/agent.mdx

@@ -140,7 +140,6 @@ Both DOM and CUA modes have their strengths and weaknesses. Hybrid mode combines
 
 Other models may not reliably produce accurate coordinates for clicking and typing.
 
-**Our recommendation:** `google/gemini-3-flash-preview` for the best balance of reliability, speed, and cost.
 </Warning>
 
 <Note>Hybrid mode requires `experimental: true` in your Stagehand constructor.</Note>