Skip to content

Commit 6574ff9

Browse files
add docs on live page proxy (#934)
# why - so people understand that the default page (`stagehand.page`) is a proxy to the most recently opened page
1 parent e0624c1 commit 6574ff9

File tree

1 file changed

+53
-0
lines changed

1 file changed

+53
-0
lines changed

docs/examples/best_practices.mdx

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,59 @@ For Stagehand's Cursor rules, check out [this file](https://github.com/browserba
1111

1212
If you're using Windsurf, you can use the same rules by adding them to your `.windsurfrules` file.
1313

14+
### Manage multiple pages explicitly (Stagehand v≥ 2.4.1, TypeScript)
15+
<Tabs>
16+
<Tab title="TypeScript">
17+
Stagehand can now keep **multiple pages open at the same time** and run
18+
`act()`, `observe()` and `extract()` on each of them.
19+
20+
#### What changed?
21+
22+
* **Before v2.4.1** Stagehand silently closed every new tab and re‑used the first tab.
23+
A single Page instance (`stagehand.page`) was always valid.
24+
* **Since v2.4.1** New tabs stay open. You can switch between them or operate on all of them in parallel.
25+
26+
#### The live‑page proxy (`stagehand.page`)
27+
28+
For backward compatibility, `stagehand.page` is now a **live proxy** that always
29+
points to the **most recently opened page**.
30+
We recommend using it for things like agents, which often don't have the ability to operate on multiple pages.
31+
If you need more control and precision, we recommend managing pages yourself.
32+
33+
#### Recommended workflow
34+
<CodeGroup>
35+
```typescript TypeScript
36+
// Create (or let the site create) additional pages.
37+
await stagehand.context.newPage(); // e.g. open a blank page
38+
const pages = stagehand.context.pages();
39+
40+
const [page1, page2] = pages;
41+
42+
// Work on each page deterministically
43+
await page1.goto('https://github.com/browserbase/stagehand');
44+
await page2.goto('https://github.com/browserbase/stagehand-python');
45+
46+
const [{ extraction: repo1 }, { extraction: repo2 }] = await Promise.all([
47+
page1.extract('extract the repository name'),
48+
page2.extract('extract the repository name'),
49+
]);
50+
51+
// should log "page1 repo: stagehand"
52+
console.log(`page1 repo: ${repo1}`);
53+
54+
// should log "page2 repo: stagehand-python"
55+
console.log(`page2 repo: ${repo2}`);
56+
```
57+
</CodeGroup>
58+
</Tab>
59+
<Tab title="Python">
60+
<Tip>
61+
Multi tab support is not yet implemented in Python, but it's coming soon!
62+
Setting `use_api=True` in your stagehand config will keep tabs open.
63+
</Tip>
64+
</Tab>
65+
</Tabs>
66+
1467
### Avoid sending sensitive information to LLMs
1568

1669
You can use `variables` in an `act` call to avoid sending sensitive information to LLMs.

0 commit comments

Comments
 (0)