- Notifications
You must be signed in to change notification settings - Fork86
The AI Browser Automation Framework
browserbase/stagehand-python
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
The AI Browser Automation Framework
Read the Docs
If you're looking for the TypeScript implementation, you can find it here
Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language, Stagehand is the natural choice for browser automations in production.
Choose when to write code vs. natural language: use AI when you want to navigate unfamiliar pages, and use code (Playwright) when you know exactly what you want to do.
Preview and cache actions: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens.
Computer use models with one line of code: Stagehand lets you integrate SOTA computer use models from OpenAI and Anthropic into the browser with one line of code.
- act — Instruct the AI to perform actions (e.g. click a button or scroll).
awaitstagehand.page.act("click on the 'Quickstart' button")
- extract — Extract and validate data from a page using a Pydantic schema.
awaitstagehand.page.extract("the summary of the first paragraph")
- observe — Get natural language interpretations to, for example, identify selectors or elements from the page.
awaitstagehand.page.observe("find the search bar")
- agent — Execute autonomous multi-step tasks with provider-specific agents (OpenAI, Anthropic, etc.).
awaitstagehand.agent.execute("book a reservation for 2 people for a trip to the Maldives")
To get started, simply:
pip install stagehand
We recommend usinguv for your package/project manager. If you're using uv can follow these steps:
uv venv .venvsource .venv/bin/activateuv pip install stagehandimportasyncioimportosfromdotenvimportload_dotenvfrompydanticimportBaseModel,FieldfromstagehandimportStagehandConfig,Stagehand# Load environment variablesload_dotenv()# Define Pydantic models for structured data extractionclassCompany(BaseModel):name:str=Field(...,description="Company name")description:str=Field(...,description="Brief company description")classCompanies(BaseModel):companies:list[Company]=Field(...,description="List of companies")asyncdefmain():# Create configurationconfig=StagehandConfig(env="BROWSERBASE",# or LOCALapi_key=os.getenv("BROWSERBASE_API_KEY"),project_id=os.getenv("BROWSERBASE_PROJECT_ID"),model_name="google/gemini-2.5-flash-preview-05-20",model_api_key=os.getenv("MODEL_API_KEY"), )stagehand=Stagehand(config)try:print("\nInitializing 🤘 Stagehand...")# Initialize Stagehandawaitstagehand.init()ifstagehand.env=="BROWSERBASE":print(f"🌐 View your live browser: https://www.browserbase.com/sessions/{stagehand.session_id}")page=stagehand.pageawaitpage.goto("https://www.aigrant.com")# Extract companies using structured schemacompanies_data=awaitpage.extract("Extract names and descriptions of 5 companies in batch 3",schema=Companies )# Display resultsprint("\nExtracted Companies:")foridx,companyinenumerate(companies_data.companies,1):print(f"{idx}.{company.name}:{company.description}")observe=awaitpage.observe("the link to the company Browserbase")print("\nObserve result:",observe)act=awaitpage.act("click the link to the company Browserbase")print("\nAct result:",act)exceptExceptionase:print(f"Error:{str(e)}")raisefinally:# Close the clientprint("\nClosing 🤘 Stagehand...")awaitstagehand.close()if__name__=="__main__":asyncio.run(main())
See our full documentationhere.
You can cache actions in Stagehand to avoid redundant LLM calls. This is particularly useful for actions that are expensive to run or when the underlying DOM structure is not expected to change.
observe lets you preview an action before taking it. If you are satisfied with the action preview, you can run it inpage.act with no further LLM calls.
# Get the action previewaction_preview=awaitpage.observe("Click the quickstart link")# action_preview is a JSON-ified version of a Playwright action:# {# "description": "The quickstart link",# "method": "click",# "selector": "/html/body/div[1]/div[1]/a",# "arguments": []# }# NO LLM INFERENCE when calling act on the previewawaitpage.act(action_preview[0])
If the website happens to change,self_heal will run the loop again to save you from constantly updating your scripts.
At a high level, we're focused on improving reliability, speed, and cost in that order of priority. If you're interested in contributing, reach out onSlack, open an issue or start a discussion.
For more info, check theContributing Guide.
Local Development Installation:
# Clone the repositorygit clone https://github.com/browserbase/stagehand-python.gitcd stagehand-python# Install in editable mode with development dependenciespip install -r requirements.txt# Ensure that a Chromium binary exists for local testingpython -m playwright install chromium
MIT License (c) 2025 Browserbase, Inc.
About
The AI Browser Automation Framework
Resources
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.