Putting a dollar cap on one Stagehand session

[domondi1]

A Stagehand script can make a lot of model calls per session (every act, extract and observe, plus retries when a page doesn't behave), and nothing bounds what one session spends. Here's one way to give each session a hard dollar budget without changing your script, using the llmClient option Stagehand already has.

Point an AI SDK OpenAI-compatible provider at a small gateway running next to your app, and send the session's id and budget as headers:

pip install inferrail
export OPENAI_API_KEY=sk-...
inferrail serve --quickstart --app-mode   # http://127.0.0.1:8000/v1

import { Stagehand, AISdkClient } from "@browserbasehq/stagehand";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

function stagehandForSession(sessionId: string, budgetUsd: string) {
  const gateway = createOpenAICompatible({
    name: "inferrail",
    baseURL: "http://127.0.0.1:8000/v1",
    apiKey: "unused",
    includeUsage: true,
    headers: {
      "X-Inferrail-Attribute-Work-Id": sessionId,
      "X-Inferrail-Budget-Usd": budgetUsd,
    },
  });
  return new Stagehand({
    env: "LOCAL",
    llmClient: new AISdkClient({ model: gateway.chatModel("gpt-4.1-mini") }),
  });
}

const stagehand = stagehandForSession("session-001", "0.25");
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://example.com");
await stagehand.act("click the pricing link");

Each call reserves its worst-case cost before it's sent, and a call that doesn't fit is refused with a 402 before it reaches OpenAI (the AI SDK throws an APICallError with statusCode === 402, so the act or extract that hit the limit fails). Afterwards inferrail work session-001 shows what the session cost.

Caveats: Chat Completions only, so this covers act/extract/observe with a chat model, not computer-use agent models that need OpenAI's Responses API; screenshots are fine (they're counted with a fixed per-image estimate, inferrail 0.4.12 or later). The model needs a price in Inferrail (inferrail models lists them; gpt-4.1-mini, gpt-4.1, gpt-4o-mini are built in). I haven't run a long Browserbase session through it, so reports are welcome.

Setup details: guide. I maintain Inferrail (open source, Apache-2.0), so take the suggestion with that in mind.