simplify stagehand method calls (#417)

* simplify stagehand method calls

* revert example

* changeset

* use new syntax in evals

* new extract eval

* allow no observe input

Author: sameelarif

Diff for: .changeset/hungry-scissors-mix.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Simplify Stagehand method calls by allowing a simple string input instead of an options object.

Diff for: evals/evals.config.json

@@ -1,5 +1,9 @@
 {
   "tasks": [
+    {
+      "name": "extract_repo_name",
+      "categories": ["extract"]
+    },
     {
       "name": "amazon_add_to_cart",
       "categories": ["act"]

Diff for: evals/tasks/arxiv.ts

@@ -17,9 +17,9 @@ export const arxiv: EvalFunction = async ({
   try {
     await stagehand.page.goto("https://arxiv.org/search/");
 
-    await stagehand.page.act({
-      action: "search for papers about web agents with multimodal models",
-    });
+    await stagehand.page.act(
+      "search for papers about web agents with multimodal models",
+    );
 
     const paper_links = await stagehand.page.extract({
       instruction: "extract the titles and links for two papers",

Diff for: evals/tasks/expedia.ts

@@ -11,14 +11,13 @@ export const expedia: EvalFunction = async ({ modelName, logger }) => {
 
   try {
     await stagehand.page.goto("https://www.expedia.com/flights");
-    await stagehand.page.act({
-      action:
-        "find round-trip flights from San Francisco (SFO) to Toronto (YYZ) for Jan 1, 2025 (up to one to two weeks)",
-    });
-    await stagehand.page.act({ action: "Go to the first non-stop flight" });
-    await stagehand.page.act({ action: "select the cheapest flight" });
-    await stagehand.page.act({ action: "click on the first non-stop flight" });
-    await stagehand.page.act({ action: "Take me to the checkout page" });
+    await stagehand.page.act(
+      "find round-trip flights from San Francisco (SFO) to Toronto (YYZ) for Jan 1, 2025 (up to one to two weeks)",
+    );
+    await stagehand.page.act("Go to the first non-stop flight");
+    await stagehand.page.act("select the cheapest flight");
+    await stagehand.page.act("click on the first non-stop flight");
+    await stagehand.page.act("Take me to the checkout page");
 
     const url = stagehand.page.url();
     return {

Diff for: evals/tasks/extract_repo_name.ts

@@ -0,0 +1,55 @@
+import { EvalFunction } from "../../types/evals";
+import { initStagehand } from "../initStagehand";
+
+export const extract_github_commits: EvalFunction = async ({
+  modelName,
+  logger,
+}) => {
+  const { stagehand, initResponse } = await initStagehand({
+    modelName,
+    logger,
+  });
+
+  const { debugUrl, sessionUrl } = initResponse;
+
+  try {
+    await stagehand.page.goto("https://github.com/facebook/react");
+
+    const { extraction } = await stagehand.page.extract(
+      "extract the repo name",
+    );
+
+    logger.log({
+      message: "Extracted repo name",
+      level: 1,
+      auxiliary: {
+        repo_name: {
+          value: extraction,
+          type: "object",
+        },
+      },
+    });
+
+    await stagehand.close();
+
+    return {
+      _success: extraction === "react",
+      extraction,
+      debugUrl,
+      sessionUrl,
+      logs: logger.getLogs(),
+    };
+  } catch (error) {
+    console.error("Error or timeout occurred:", error);
+
+    await stagehand.close();
+
+    return {
+      _success: false,
+      error: JSON.parse(JSON.stringify(error, null, 2)),
+      debugUrl,
+      sessionUrl,
+      logs: logger.getLogs(),
+    };
+  }
+};

Diff for: evals/tasks/google_jobs.ts

@@ -16,12 +16,12 @@ export const google_jobs: EvalFunction = async ({
 
   try {
     await stagehand.page.goto("https://www.google.com/");
-    await stagehand.page.act({ action: "click on the about page" });
-    await stagehand.page.act({ action: "click on the careers page" });
-    await stagehand.page.act({ action: "input data scientist into role" });
-    await stagehand.page.act({ action: "input new york city into location" });
-    await stagehand.page.act({ action: "click on the search button" });
-    await stagehand.page.act({ action: "click on the first job link" });
+    await stagehand.page.act("click on the about page");
+    await stagehand.page.act("click on the careers page");
+    await stagehand.page.act("input data scientist into role");
+    await stagehand.page.act("input new york city into location");
+    await stagehand.page.act("click on the search button");
+    await stagehand.page.act("click on the first job link");
 
     const jobDetails = await stagehand.page.extract({
       instruction:

Diff for: evals/tasks/homedepot.ts

@@ -17,10 +17,10 @@ export const homedepot: EvalFunction = async ({
 
   try {
     await stagehand.page.goto("https://www.homedepot.com/");
-    await stagehand.page.act({ action: "search for gas grills" });
-    await stagehand.page.act({ action: "click on the best selling gas grill" });
-    await stagehand.page.act({ action: "click on the Product Details" });
-    await stagehand.page.act({ action: "find the Primary Burner BTU" });
+    await stagehand.page.act("search for gas grills");
+    await stagehand.page.act("click on the best selling gas grill");
+    await stagehand.page.act("click on the Product Details");
+    await stagehand.page.act("find the Primary Burner BTU");
 
     const productSpecs = await stagehand.page.extract({
       instruction: "Extract the Primary exact Burner BTU of the product",

Diff for: evals/tasks/wikipedia.ts

@@ -10,9 +10,7 @@ export const wikipedia: EvalFunction = async ({ modelName, logger }) => {
   const { debugUrl, sessionUrl } = initResponse;
 
   await stagehand.page.goto(`https://en.wikipedia.org/wiki/Baseball`);
-  await stagehand.page.act({
-    action: 'click the "hit and run" link in this article',
-  });
+  await stagehand.page.act('click the "hit and run" link in this article');
 
   const url = "https://en.wikipedia.org/wiki/Hit_and_run_(baseball)";
   const currentUrl = stagehand.page.url();

Diff for: lib/StagehandPage.ts

@@ -7,7 +7,7 @@ import { LLMClient } from "./llm/LLMClient";
 import { ActOptions, ActResult, GotoOptions, Stagehand } from "./index";
 import { StagehandActHandler } from "./handlers/actHandler";
 import { StagehandContext } from "./StagehandContext";
-import { Page } from "../types/page";
+import { Page, defaultExtractSchema } from "../types/page";
 import {
   ExtractOptions,
   ExtractResult,
@@ -285,19 +285,25 @@ export class StagehandPage {
     }
   }
 
-  async act({
-    action,
-    modelName,
-    modelClientOptions,
-    useVision = "fallback",
-    variables = {},
-    domSettleTimeoutMs,
-  }: ActOptions): Promise<ActResult> {
+  async act(actionOrOptions: string | ActOptions): Promise<ActResult> {
     if (!this.actHandler) {
       throw new Error("Act handler not initialized");
     }
 
-    useVision = useVision ?? "fallback";
+    const options: ActOptions =
+      typeof actionOrOptions === "string"
+        ? { action: actionOrOptions }
+        : actionOrOptions;
+
+    const {
+      action,
+      modelName,
+      modelClientOptions,
+      useVision = "fallback",
+      variables = {},
+      domSettleTimeoutMs,
+    } = options;
+
     const requestId = Math.random().toString(36).substring(2);
     const llmClient: LLMClient = modelName
       ? this.stagehand.llmProvider.getClient(modelName, modelClientOptions)
@@ -361,18 +367,30 @@ export class StagehandPage {
       });
   }
 
-  async extract<T extends z.AnyZodObject>({
-    instruction,
-    schema,
-    modelName,
-    modelClientOptions,
-    domSettleTimeoutMs,
-    useTextExtract,
-  }: ExtractOptions<T>): Promise<ExtractResult<T>> {
+  async extract<T extends z.AnyZodObject = typeof defaultExtractSchema>(
+    instructionOrOptions: string | ExtractOptions<T>,
+  ): Promise<ExtractResult<T>> {
     if (!this.extractHandler) {
       throw new Error("Extract handler not initialized");
     }
 
+    const options: ExtractOptions<T> =
+      typeof instructionOrOptions === "string"
+        ? {
+            instruction: instructionOrOptions,
+            schema: defaultExtractSchema as T,
+          }
+        : instructionOrOptions;
+
+    const {
+      instruction,
+      schema,
+      modelName,
+      modelClientOptions,
+      domSettleTimeoutMs,
+      useTextExtract,
+    } = options;
+
     const requestId = Math.random().toString(36).substring(2);
     const llmClient = modelName
       ? this.stagehand.llmProvider.getClient(modelName, modelClientOptions)
@@ -432,17 +450,30 @@ export class StagehandPage {
       });
   }
 
-  async observe(options?: ObserveOptions): Promise<ObserveResult[]> {
+  async observe(
+    instructionOrOptions?: string | ObserveOptions,
+  ): Promise<ObserveResult[]> {
     if (!this.observeHandler) {
       throw new Error("Observe handler not initialized");
     }
 
+    const options: ObserveOptions =
+      typeof instructionOrOptions === "string"
+        ? { instruction: instructionOrOptions }
+        : instructionOrOptions || {};
+
+    const {
+      instruction = "Find actions that can be performed on this page.",
+      modelName,
+      modelClientOptions,
+      useVision = false,
+      domSettleTimeoutMs,
+      useAccessibilityTree = false,
+    } = options;
+
     const requestId = Math.random().toString(36).substring(2);
-    const llmClient = options?.modelName
-      ? this.stagehand.llmProvider.getClient(
-          options.modelName,
-          options.modelClientOptions,
-        )
+    const llmClient = modelName
+      ? this.stagehand.llmProvider.getClient(modelName, modelClientOptions)
       : this.llmClient;
 
     this.stagehand.log({
@@ -451,7 +482,7 @@ export class StagehandPage {
       level: 1,
       auxiliary: {
         instruction: {
-          value: options?.instruction,
+          value: instruction,
           type: "string",
         },
         requestId: {
@@ -463,23 +494,21 @@ export class StagehandPage {
           type: "string",
         },
         useAccessibilityTree: {
-          value: options?.useAccessibilityTree ? "true" : "false",
+          value: useAccessibilityTree ? "true" : "false",
           type: "boolean",
         },
       },
     });
 
     return this.observeHandler
       .observe({
-        instruction:
-          options?.instruction ??
-          "Find actions that can be performed on this page.",
+        instruction,
         llmClient,
-        useVision: options?.useVision ?? false,
+        useVision,
         fullPage: false,
         requestId,
-        domSettleTimeoutMs: options?.domSettleTimeoutMs,
-        useAccessibilityTree: options?.useAccessibilityTree ?? false,
+        domSettleTimeoutMs,
+        useAccessibilityTree,
       })
       .catch((e) => {
         this.stagehand.log({
@@ -500,7 +529,7 @@ export class StagehandPage {
               type: "string",
             },
             instruction: {
-              value: options?.instruction,
+              value: instruction,
               type: "string",
             },
           },

Diff for: types/page.ts

@@ -3,7 +3,7 @@ import type {
   BrowserContext as PlaywrightContext,
   Page as PlaywrightPage,
 } from "@playwright/test";
-import type { z } from "zod";
+import { z } from "zod";
 import type {
   ActOptions,
   ActResult,
@@ -13,12 +13,24 @@ import type {
   ObserveResult,
 } from "./stagehand";
 
+export const defaultExtractSchema = z.object({
+  extraction: z.string(),
+});
+
 export interface Page extends Omit<PlaywrightPage, "on"> {
-  act: (options: ActOptions) => Promise<ActResult>;
-  extract: <T extends z.AnyZodObject>(
+  act(action: string): Promise<ActResult>;
+  act(options: ActOptions): Promise<ActResult>;
+
+  extract(
+    instruction: string,
+  ): Promise<ExtractResult<typeof defaultExtractSchema>>;
+  extract<T extends z.AnyZodObject>(
     options: ExtractOptions<T>,
-  ) => Promise<ExtractResult<T>>;
-  observe: (options?: ObserveOptions) => Promise<ObserveResult[]>;
+  ): Promise<ExtractResult<T>>;
+
+  observe(): Promise<ObserveResult[]>;
+  observe(instruction: string): Promise<ObserveResult[]>;
+  observe(options?: ObserveOptions): Promise<ObserveResult[]>;
 
   on: {
     (event: "popup", listener: (page: Page) => unknown): Page;