Skip to main content

​
When to use

Use an agent fallback as a failsafe when a one step action unexpectedly becomes a multi-step flow.

​
How it works

  1. act() is attempted for the direct action
  2. If it fails, agent() figures out the new path
  3. Agent completes all needed steps (open menu → click button)

​
Example scenario

Before: Sign in button was in the header
After: Sign in now requires: Click account menu → Click “Sign in” option A single act("click sign in") can’t handle this change. The agent fallback can discover and execute both steps. 
import { Stagehand } from "@browserbasehq/stagehand";

try {
  await page.act("click the 'Sign In' button");
} catch (err) {
  console.log("Agent fallback triggered");

  const agent = stagehand.agent({
    provider: "anthropic",
    model: "claude-sonnet-4-20250514",
    instructions: "You are a helpful assistant that can use a web browser.",
  });

  const result = await agent.execute({
    instruction: "Find and click Sign In button",
    maxSteps: 10,
  });

  console.log(result.success ? "Agent fallback success" : "Agent fallback failed");

  if (!result.success) throw err;
}

from stagehand import Stagehand

try:
    await page.act("click the 'Sign In' button")
except Exception as err:
    print("Agent fallback triggered")

    agent = stagehand.agent({
        "provider": "anthropic",
        "model": "claude-sonnet-4-20250514",
        "instructions": "Complete the action, handling any new steps required.",
    })

    result = await agent.execute({
        "instruction": "Find and click Sign In button",
        "max_steps": 10,
    })

    print("Agent fallback success" if result.success else "Agent fallback failed")

    if not result.success:
        raise err