browserbase · tkattkat · Nov 19, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025
diff --git a/.changeset/dark-pans-carry.md b/.changeset/dark-pans-carry.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add support for zod 4, while maintaining backwards compatibility for zod 3 
diff --git a/packages/core/examples/2048.ts b/packages/core/examples/2048.ts
@@ -1,5 +1,5 @@
 import { Stagehand } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function example() {
   console.log("🎮 Starting 2048 bot...");

diff --git a/packages/core/examples/agent-custom-tools.ts b/packages/core/examples/agent-custom-tools.ts
@@ -1,7 +1,7 @@
 /**
  * This example shows how to pass custom tools to stagehand agent (both CUA and non-CUA)
  */
-import { z } from "zod/v3";
+import { z } from "zod";
 import { tool } from "ai";
 import { Stagehand } from "../lib/v3";
 import chalk from "chalk";

diff --git a/packages/core/examples/custom_client_aisdk.ts b/packages/core/examples/custom_client_aisdk.ts
@@ -7,7 +7,7 @@
  */
 import { Stagehand } from "../lib/v3";
 import { AISdkClient } from "./external_clients/aisdk";
-import { z } from "zod/v3";
+import { z } from "zod";
 import { openai } from "@ai-sdk/openai";
 
 async function example() {

diff --git a/packages/core/examples/custom_client_langchain.ts b/packages/core/examples/custom_client_langchain.ts
@@ -3,15 +3,17 @@
  *
  * You will need to reference the Langchain Client in /external_clients/langchain.ts
  */
-import { z } from "zod/v3";
+import { z } from "zod";
 import { Stagehand } from "../lib/v3";
 import { LangchainClient } from "./external_clients/langchain";
 import { ChatOpenAI } from "@langchain/openai";
 
 async function example() {
+  // @ts-expect-error Type instantiation is excessively deep and possibly infinite
   const stagehand = new Stagehand({
     env: "BROWSERBASE",
     verbose: 1,
+    // @ts-expect-error Type instantiation is excessively deep and possibly infinite
     llmClient: new LangchainClient(
       new ChatOpenAI({
         model: "gpt-4o",

diff --git a/packages/core/examples/custom_client_openai.ts b/packages/core/examples/custom_client_openai.ts
@@ -6,7 +6,7 @@
  * You will need to reference the Custom OpenAI Client in /external_clients/customOpenAI.ts
  */
 import { Stagehand } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 import { CustomOpenAIClient } from "./external_clients/customOpenAI";
 import OpenAI from "openai";
 

diff --git a/packages/core/examples/external_clients/customOpenAI.ts b/packages/core/examples/external_clients/customOpenAI.ts
@@ -11,7 +11,6 @@ import {
   LLMClient,
 } from "../../lib/v3";
 import OpenAI from "openai";
-import { zodResponseFormat } from "openai/helpers/zod";
 import type {
   ChatCompletion,
   ChatCompletionAssistantMessageParam,
@@ -22,10 +21,10 @@ import type {
   ChatCompletionSystemMessageParam,
   ChatCompletionUserMessageParam,
 } from "openai/resources/chat/completions";
-import { z } from "zod/v3";
 import { CreateChatCompletionResponseError } from "../../lib/v3";
+import { StagehandZodSchema, toJsonSchema } from "../../lib/v3/zodCompat";
 
-function validateZodSchema(schema: z.ZodTypeAny, data: unknown) {
+function validateZodSchema(schema: StagehandZodSchema, data: unknown) {
   try {
     schema.parse(data);
     return true;
@@ -83,12 +82,18 @@ export class CustomOpenAIClient extends LLMClient {
       );
     }
 
-    let responseFormat = undefined;
+    let responseFormat:
+      | ChatCompletionCreateParamsNonStreaming["response_format"]
+      | undefined;
     if (options.response_model) {
-      responseFormat = zodResponseFormat(
-        options.response_model.schema,
-        options.response_model.name,
-      );
+      const responseModelSchema = options.response_model.schema;
+      responseFormat = {
+        type: "json_schema",
+        json_schema: {
+          name: options.response_model.name,
+          schema: toJsonSchema(responseModelSchema),
+        },
+      };
     }
 
     /* eslint-disable */

diff --git a/packages/core/examples/external_clients/langchain.ts b/packages/core/examples/external_clients/langchain.ts
@@ -4,14 +4,14 @@ import {
   LLMClient,
   AvailableModel,
 } from "../../lib/v3";
-import { zodToJsonSchema } from "zod-to-json-schema";
 import {
   AIMessage,
   BaseMessageLike,
   HumanMessage,
   SystemMessage,
 } from "@langchain/core/messages";
 import { ChatCompletion } from "openai/resources";
+import { toJsonSchema } from "../../lib/v3/zodCompat";
 
 export class LangchainClient extends LLMClient {
   public type = "langchainClient" as const;
@@ -60,9 +60,8 @@ export class LangchainClient extends LLMClient {
     );
 
     if (options.response_model) {
-      const responseSchema = zodToJsonSchema(options.response_model.schema, {
-        $refStrategy: "none",
-      });
+      //ref string no longer needed, this is now default behavior
+      const responseSchema = toJsonSchema(options.response_model.schema);
       const structuredModel = this.model.withStructuredOutput(responseSchema);
       const response = await structuredModel.invoke(formattedMessages);
 

diff --git a/packages/core/examples/operator-example.ts b/packages/core/examples/operator-example.ts
@@ -5,17 +5,14 @@
  *
  * To learn more about Stagehand Agents, see: https://docs.stagehand.dev/concepts/agent
  */
-
 import { Stagehand } from "../lib/v3";
 import dotenv from "dotenv";
 import chalk from "chalk";
 
 // Load environment variables
 dotenv.config();
-
 async function main() {
   console.log(`\n${chalk.bold("Stagehand 🤘 Operator Example")}\n`);
-
   // Initialize Stagehand
   const stagehand = new Stagehand({
     env: "LOCAL",
@@ -48,5 +45,4 @@ async function main() {
     // await stagehand.close();
   }
 }
-
 main();
diff --git a/packages/core/examples/parameterizeApiKey.ts b/packages/core/examples/parameterizeApiKey.ts
@@ -1,5 +1,5 @@
 import { Stagehand } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 /**
  * This example shows how to parameterize the API key for the LLM provider.

diff --git a/packages/core/examples/v3/patchright.ts b/packages/core/examples/v3/patchright.ts
@@ -1,6 +1,6 @@
 import { Stagehand } from "../../lib/v3";
 import { chromium } from "patchright-core";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function example(stagehand: Stagehand) {
   const browser = await chromium.connectOverCDP({

diff --git a/packages/core/examples/v3/playwright.ts b/packages/core/examples/v3/playwright.ts
@@ -1,6 +1,6 @@
 import { Stagehand } from "../../lib/v3";
 import { chromium } from "playwright-core";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function example(stagehand: Stagehand) {
   const browser = await chromium.connectOverCDP({

diff --git a/packages/core/examples/v3/recordVideo.ts b/packages/core/examples/v3/recordVideo.ts
@@ -2,7 +2,7 @@ import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { Stagehand } from "../../lib/v3";
 import { chromium } from "playwright-core";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function recordPlaywrightVideo(stagehand: Stagehand): Promise<void> {
   const browser = await chromium.connectOverCDP({

diff --git a/packages/core/examples/v3/targetedExtract.ts b/packages/core/examples/v3/targetedExtract.ts
@@ -1,5 +1,5 @@
 import { Stagehand } from "../../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function example(stagehand: Stagehand) {
   const page = stagehand.context.pages()[0];

diff --git a/packages/core/examples/v3_example.ts b/packages/core/examples/v3_example.ts
@@ -1,5 +1,5 @@
 import { V3 } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function example(v3: V3) {
   const page = v3.context.pages()[0];

diff --git a/packages/core/lib/inference.ts b/packages/core/lib/inference.ts
@@ -1,4 +1,4 @@
-import { z } from "zod/v3";
+import { z } from "zod";
 import { LogLine } from "./v3/types/public/logs";
 import { ChatMessage, LLMClient } from "./v3/llm/LLMClient";
 import {
@@ -11,25 +11,12 @@ import {
   buildObserveUserMessage,
 } from "./prompt";
 import { appendSummary, writeTimestampedTxtFile } from "./inferenceLogUtils";
+import type { InferStagehandSchema, StagehandZodObject } from "./v3/zodCompat";
 
-/** Simple usage shape if your LLM returns usage tokens. */
-interface LLMUsage {
-  prompt_tokens: number;
-  completion_tokens: number;
-  total_tokens: number;
-  reasoning_tokens?: number;
-  cached_input_tokens?: number;
-}
-
-/**
- * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
- */
-export interface LLMParsedResponse<T> {
-  data: T;
-  usage?: LLMUsage;
-}
+// Re-export for backward compatibility
+export type { LLMParsedResponse, LLMUsage } from "./v3/llm/LLMClient";
 
-export async function extract({
+export async function extract<T extends StagehandZodObject>({
   instruction,
   domElements,
   schema,
@@ -40,7 +27,7 @@ export async function extract({
 }: {
   instruction: string;
   domElements: string;
-  schema: z.ZodObject<z.ZodRawShape>;
+  schema: T;
   llmClient: LLMClient;
   userProvidedInstructions?: string;
   logger: (message: LogLine) => void;
@@ -59,7 +46,7 @@ export async function extract({
       ),
   });
 
-  type ExtractionResponse = z.infer<typeof schema>;
+  type ExtractionResponse = InferStagehandSchema<T>;
   type MetadataResponse = z.infer<typeof metadataSchema>;
 
   const isUsingAnthropic = llmClient.type === "anthropic";
@@ -103,8 +90,7 @@ export async function extract({
     });
   const extractEndTime = Date.now();
 
-  const { data: extractedData, usage: extractUsage } =
-    extractionResponse as LLMParsedResponse<ExtractionResponse>;
+  const { data: extractedData, usage: extractUsage } = extractionResponse;
 
   let extractResponseFile = "";
   if (logInferenceToFile) {
@@ -175,7 +161,7 @@ export async function extract({
       progress: metadataResponseProgress,
     },
     usage: metadataResponseUsage,
-  } = metadataResponse as LLMParsedResponse<MetadataResponse>;
+  } = metadataResponse;
 
   let metadataResponseFile = "";
   if (logInferenceToFile) {
@@ -322,8 +308,7 @@ export async function observe({
   const end = Date.now();
   const usageTimeMs = end - start;
 
-  const { data: observeData, usage: observeUsage } =
-    rawResponse as LLMParsedResponse<ObserveResponse>;
+  const { data: observeData, usage: observeUsage } = rawResponse;
   const promptTokens = observeUsage?.prompt_tokens ?? 0;
   const completionTokens = observeUsage?.completion_tokens ?? 0;
   const reasoningTokens = observeUsage?.reasoning_tokens ?? 0;
@@ -456,8 +441,7 @@ export async function act({
   const end = Date.now();
   const usageTimeMs = end - start;
 
-  const { data: actData, usage: actUsage } =
-    rawResponse as LLMParsedResponse<ActResponse>;
+  const { data: actData, usage: actUsage } = rawResponse;
   const promptTokens = actUsage?.prompt_tokens ?? 0;
   const completionTokens = actUsage?.completion_tokens ?? 0;
   const reasoningTokens = actUsage?.reasoning_tokens ?? 0;