Stagehand sets invalid OpenAI reasoningEffort: "minimal" for gpt-5.4

[eersnington]

Error:

AI_APICallError: Unsupported value: 'minimal' is not supported with the 'gpt-5.4' model. Supported values are: 'none', 'low', 'medium', 'high', and 'xhigh'.
      cause: undefined,
        url: "https://api.openai.com/v1/responses",

Minimal Repro:

import "dotenv/config";

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    experimental: true,
    model: {
      apiKey: process.env.OPENAI_API_KEY,
      modelName: "openai/gpt-5.4",
    },
    browserbaseSessionCreateParams: {
      projectId: process.env.BROWSERBASE_PROJECT_ID,
      browserSettings: {
        blockAds: true,
        solveCaptchas: true,
        viewport: { width: 1288, height: 711 },
      },
    },
    disablePino: true,
    verbose: 0,
  });

  try {
    await stagehand.init();

    const page = stagehand.context.pages()[0];
    if (!page) {
      throw new Error("Browser session did not initialize correctly");
    }

    await page.goto("https://vercel.com", {
      waitUntil: "domcontentloaded",
      timeoutMs: 20_000,
    });

    const result = await stagehand.extract(
      "Extract the page title and a one sentence summary of what this company does",
      z.object({
        summary: z.string(),
        title: z.string(),
      }),
      { page, timeout: 20_000 }
    );

    console.log(JSON.stringify(result, null, 2));
  } finally {
    await stagehand.close().catch(() => null);
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

I dug into the source code a little bit and it has to do with provider option resolution in aisdk.ts#L183-L194.

the fix is simple, it's just that 5.4 doesn't have "minimal" as a reasoning effort value like previous 5.1>= versions (damn you openai) and using that throws an error. i think a better default is "low".

relevant ai-sdk docs: https://ai-sdk.dev/providers/ai-sdk-providers/openai#reasoning

[eersnington]

looks like a pr is open to fix this #1864.

until that's merged, a workaround im settling with is through creating an openai client and passing that reference. though it isn't ideal due to type mismatch of older openai client

import "dotenv/config";
import { CustomOpenAIClient, Stagehand } from "@browserbasehq/stagehand";
import OpenAI from "openai";
import { z } from "zod";
async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    experimental: true,
    llmClient: new CustomOpenAIClient({
      // @ts-expect-error Stagehand types target an older OpenAI client shape, but openai@6 still works at runtime for this path.
      client: new OpenAI({ apiKey: openAiApiKey }),
      modelName: "gpt-5.4",
    }),
    browserbaseSessionCreateParams: {
      projectId: process.env.BROWSERBASE_PROJECT_ID,
      browserSettings: {
        blockAds: true,
        solveCaptchas: true,
        viewport: { width: 1288, height: 711 },
      },
    },
    disablePino: true,
    verbose: 0,
  });