Skip to content

Commit d665e99

Browse files
filip-michalskyfilip-michalsky
committed
update readme
1 parent fe81065 commit d665e99

File tree

1 file changed

+52
-242
lines changed

1 file changed

+52
-242
lines changed

‎README.md‎

Lines changed: 52 additions & 242 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,26 @@
3636
</p>
3737

3838
<div class="note" style="background-color: #808096; border-left: 5px solid #ffeb3b; padding: 15px; margin: 10px 0; color: white;">
39-
<strong>NOTE:</strong> This is a Python SDK for Stagehand. The original implementation is in TypeScript and is available <a href="https://github.com/browserbase/stagehand" style="color: blue;">here</a>.
39+
This is a Python SDK for Stagehand. We also have a TypeScript SDK available <a href="https://github.com/browserbase/stagehand" style="color: blue;">here</a>.
4040
</div>
4141

42-
---
42+
> Stagehand Python SDK is currently available as an early release, and we're actively seeking feedback from the community. Please join our [Slack community](https://stagehand.dev/slack) to stay updated on the latest developments and provide feedback.
4343
44-
Stagehand is the easiest way to build browser automations with AI-powered interactions.
44+
## Why Stagehand?
45+
46+
*Stagehand is the easiest way to build browser automations with AI-powered interactions.*
47+
48+
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.
49+
50+
1. **Choose when to write code vs. natural language**: use AI when you want to navigate unfamiliar pages, and use code ([Playwright](https://playwright.dev/)) when you know exactly what you want to do.
51+
52+
2. **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.
53+
54+
3. **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.
55+
56+
-----
57+
58+
### TL;DR Automate the web *reliably* with natural language:
4559

4660
- **act** — Instruct the AI to perform actions (e.g. click a button or scroll).
4761
```python
@@ -60,6 +74,12 @@ await stagehand.page.observe("find the search bar")
6074
await stagehand.agent.execute("book a reservation for 2 people for a trip to the Maldives")
6175
```
6276

77+
78+
## Installation:
79+
80+
`pip install stagehand`
81+
82+
6383
## Quickstart
6484

6585
```python
@@ -145,174 +165,9 @@ if __name__ == "__main__":
145165
asyncio.run(main())
146166
```
147167

148-
## Installation
149-
150-
### Creating a Virtual Environment (Recommended)
151-
152-
First, create and activate a virtual environment to keep your project dependencies isolated:
153-
154-
```bash
155-
# Create a virtual environment
156-
python -m venv stagehand-env
157-
158-
# Activate the environment
159-
# On macOS/Linux:
160-
source stagehand-env/bin/activate
161-
# On Windows:
162-
stagehand-env\Scripts\activate
163-
```
164-
165-
### Install Stagehand
166-
167-
**Normal Installation:**
168-
```bash
169-
pip install stagehand
170-
```
168+
## Documentation
171169

172-
**Local Development Installation:**
173-
If you're contributing to Stagehand or want to modify the source code:
174-
175-
```bash
176-
# Clone the repository
177-
git clone https://github.com/browserbase/stagehand-python.git
178-
cd stagehand-python
179-
180-
# Install in editable mode with development dependencies
181-
pip install -e ".[dev]"
182-
```
183-
184-
## Requirements
185-
186-
- Python 3.9+
187-
- All dependencies are automatically handled when installing via `pip`
188-
189-
The main dependencies include:
190-
- httpx (for async HTTP client)
191-
- requests (for sync HTTP client)
192-
- pydantic (for data validation)
193-
- playwright (for browser automation)
194-
- python-dotenv (for environment variable support)
195-
- browserbase (for Browserbase integration)
196-
197-
### Development Dependencies
198-
199-
The development dependencies are automatically installed when using `pip install -e ".[dev]"` and include:
200-
- pytest, pytest-asyncio, pytest-mock, pytest-cov (testing)
201-
- black, isort, ruff (code formatting and linting)
202-
- mypy (type checking)
203-
- rich (enhanced terminal output)
204-
205-
## Environment Variables
206-
207-
Before running your script, copy `.env.example` to `.env.` set the following environment variables:
208-
209-
```bash
210-
export BROWSERBASE_API_KEY="your-api-key" # if running remotely
211-
export BROWSERBASE_PROJECT_ID="your-project-id" # if running remotely
212-
export MODEL_API_KEY="your-openai-api-key" # or your preferred model's API key
213-
export STAGEHAND_API_URL="url-of-stagehand-server" # if running remotely
214-
export STAGEHAND_ENV="BROWSERBASE" # or "LOCAL" to run Stagehand locally
215-
```
216-
217-
You can also make a copy of `.env.example` and add these to your `.env` file.
218-
219-
## Agent Example
220-
221-
```python
222-
import os
223-
from stagehand.sync import Stagehand
224-
from stagehand import StagehandConfig
225-
from stagehand.schemas import AgentConfig, AgentExecuteOptions, AgentProvider
226-
from dotenv import load_dotenv
227-
228-
load_dotenv()
229-
230-
def main():
231-
# Configure Stagehand
232-
config = StagehandConfig(
233-
env="BROWSERBASE",
234-
api_key=os.getenv("BROWSERBASE_API_KEY"),
235-
project_id=os.getenv("BROWSERBASE_PROJECT_ID"),
236-
model_name="gpt-4o",
237-
model_client_options={"apiKey": os.getenv("MODEL_API_KEY")}
238-
)
239-
240-
# Initialize Stagehand
241-
stagehand = Stagehand(config=config, api_url=os.getenv("STAGEHAND_API_URL"))
242-
stagehand.init()
243-
print(f"Session created: {stagehand.session_id}")
244-
245-
# Navigate to Google
246-
stagehand.page.goto("https://google.com/")
247-
248-
# Configure the agent
249-
agent_config = AgentConfig(
250-
provider=AgentProvider.OPENAI,
251-
model="computer-use-preview",
252-
instructions="You are a helpful web navigation assistant. You are currently on google.com."
253-
options={"apiKey": os.getenv("MODEL_API_KEY")}
254-
)
255-
256-
# Define execution options
257-
execute_options = AgentExecuteOptions(
258-
instruction="Search for 'latest AI news' and extract the titles of the first 3 results",
259-
max_steps=10,
260-
auto_screenshot=True
261-
)
262-
263-
# Execute the agent task
264-
agent_result = stagehand.agent.execute(agent_config, execute_options)
265-
266-
print(f"Agent execution result: {agent_result}")
267-
268-
# Close the session
269-
stagehand.close()
270-
271-
if __name__ == "__main__":
272-
main()
273-
```
274-
275-
## Pydantic Schemas
276-
277-
- **ActOptions**
278-
279-
The `ActOptions` model takes an `action` field that tells the AI what to do on the page, plus optional fields such as `useVision` and `variables`:
280-
```python
281-
from stagehand.schemas import ActOptions
282-
283-
# Example:
284-
await page.act(ActOptions(action="click on the 'Quickstart' button"))
285-
```
286-
287-
- **ObserveOptions**
288-
289-
The `ObserveOptions` model lets you find elements on the page using natural language. The `onlyVisible` option helps limit the results:
290-
```python
291-
from stagehand.schemas import ObserveOptions
292-
293-
# Example:
294-
await page.observe(ObserveOptions(instruction="find the button labeled 'News'", onlyVisible=True))
295-
```
296-
297-
- **ExtractOptions**
298-
299-
The `ExtractOptions` model extracts structured data from the page. Pass your instructions and a schema defining your expected data format. **Note:** If you are using a Pydantic model for the schema, call its `.model_json_schema()` method to ensure JSON serializability.
300-
```python
301-
from stagehand.schemas import ExtractOptions
302-
from pydantic import BaseModel
303-
304-
class DescriptionSchema(BaseModel):
305-
description: str
306-
307-
# Example:
308-
data = await page.extract(
309-
ExtractOptions(
310-
instruction="extract the description of the page",
311-
schemaDefinition=DescriptionSchema.model_json_schema()
312-
)
313-
)
314-
description = data.get("description") if isinstance(data, dict) else data.description
315-
```
170+
See our full documentation [here](https://docs.stagehand.dev/).
316171

317172
## Actions caching
318173

@@ -338,78 +193,6 @@ action_preview = await page.observe("Click the quickstart link")
338193
await page.act(action_preview[0])
339194
```
340195

341-
### Simple caching
342-
343-
Here's an example of implementing a simple file-based cache:
344-
345-
```python
346-
import json
347-
from pathlib import Path
348-
from typing import Optional, Dict, Any
349-
350-
# Get the cached value (None if it doesn't exist)
351-
async def get_cache(key: str) -> Optional[Dict[str, Any]]:
352-
try:
353-
cache_path = Path("cache.json")
354-
if not cache_path.exists():
355-
return None
356-
with open(cache_path) as f:
357-
cache = json.load(f)
358-
return cache.get(key)
359-
except Exception:
360-
return None
361-
362-
# Set the cache value
363-
async def set_cache(key: str, value: Dict[str, Any]) -> None:
364-
cache_path = Path("cache.json")
365-
cache = {}
366-
if cache_path.exists():
367-
with open(cache_path) as f:
368-
cache = json.load(f)
369-
cache[key] = value
370-
with open(cache_path, "w") as f:
371-
json.dump(cache, f)
372-
```
373-
374-
### Act with cache
375-
376-
Here's a function that checks the cache, gets the action, and runs it:
377-
378-
```python
379-
async def act_with_cache(page, key: str, prompt: str):
380-
# Check if we have a cached action
381-
cached_action = await get_cache(key)
382-
383-
if cached_action:
384-
# Use the cached action
385-
action = cached_action
386-
else:
387-
# Get the observe result (the action)
388-
action = await page.observe(prompt)
389-
# Cache the action
390-
await set_cache(key, action[0])
391-
392-
# Run the action (no LLM inference)
393-
await page.act(action[0])
394-
```
395-
396-
You can now use `act_with_cache` to run an action with caching:
397-
398-
```python
399-
prompt = "Click the quickstart link"
400-
key = prompt # Simple cache key
401-
await act_with_cache(page, key, prompt)
402-
```
403-
404-
405-
## Why?
406-
**Stagehand adds determinism to otherwise unpredictable agents.**
407-
408-
While there's no limit to what you could instruct Stagehand to do, our primitives allow you to control how much you want to leave to an AI. It works best when your code is a sequence of atomic actions. Instead of writing a single script for a single website, Stagehand allows you to write durable, self-healing, and repeatable web automation workflows that actually work.
409-
410-
> [!NOTE]
411-
> `Stagehand` is currently available as an early release, and we're actively seeking feedback from the community. Please join our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-2tdncfgkk-fF8y5U0uJzR2y2_M9c9OJA) to stay updated on the latest developments and provide feedback.
412-
413196

414197
## Configuration
415198

@@ -449,6 +232,33 @@ config = StagehandConfig(
449232
)
450233
```
451234

235+
## Contributing
236+
237+
First, create and activate a virtual environment to keep your project dependencies isolated:
238+
239+
```bash
240+
# Create a virtual environment
241+
python -m venv stagehand-env
242+
243+
# Activate the environment
244+
# On macOS/Linux:
245+
source stagehand-env/bin/activate
246+
# On Windows:
247+
stagehand-env\Scripts\activate
248+
```
249+
250+
**Local Development Installation:**
251+
252+
253+
```bash
254+
# Clone the repository
255+
git clone https://github.com/browserbase/stagehand-python.git
256+
cd stagehand-python
257+
258+
# Install in editable mode with development dependencies
259+
pip install -e ".[dev]"
260+
```
261+
452262

453263
## License
454264

0 commit comments

Comments
 (0)