Skip to content

Accept instruction and schema positionally in Python observe and extract #2539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miguelg719 merged 1 commit into from
Aug 3, 2026
Merged

Accept instruction and schema positionally in Python observe and extract #2539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions packages/docs/v4/basics/act.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -520,7 +520,7 @@ if (action?.method === "click") {

<View title="Python" icon="python">
```python
result = await stagehand.observe(instruction="click the login button")
result = await stagehand.observe("click the login button")

if result.data and result.data[0].method == "click":
# No inference: Stagehand replays the observed action
Expand Down Expand Up @@ -764,7 +764,7 @@ except Exception as error:
raise

# Observe the same prompt to get the planned action
observed = await stagehand.observe(instruction=prompt)
observed = await stagehand.observe(prompt)
action = observed.data[0] if observed.data else None

if action is not None and action.method == expected_method:
Expand Down Expand Up @@ -930,7 +930,7 @@ except Exception:
await page.wait_for_load_state("domcontentloaded")

# Use observe to check element state
observed = await stagehand.observe(instruction="find the submit button")
observed = await stagehand.observe("find the submit button")

if observed.data:
print("Element found, trying more specific instruction")
Expand Down Expand Up @@ -1013,7 +1013,7 @@ await stagehand.act("click the red 'Delete' button next to the user John Smith")

# Or preview with observe first:
observed = await stagehand.observe(
instruction="click the submit button in the checkout form"
"click the submit button in the checkout form"
)
if observed.data and "checkout" in observed.data[0].description:
await stagehand.act(observed.data[0])
Expand Down
62 changes: 31 additions & 31 deletions packages/docs/v4/basics/extract.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ class Repository(BaseModel):


await stagehand.extract(
instruction="extract the name of the repository",
schema=Repository,
"extract the name of the repository",
Repository,
)
```
</View>
Expand Down Expand Up @@ -93,8 +93,8 @@ class Product(BaseModel):


result = await stagehand.extract(
instruction="extract product details",
schema=Product,
"extract product details",
Product,
)
```
</View>
Expand Down Expand Up @@ -188,8 +188,8 @@ class Apartments(BaseModel):


result = await stagehand.extract(
instruction="extract all apartment listings",
schema=Apartments,
"extract all apartment listings",
Apartments,
)
```
</View>
Expand Down Expand Up @@ -298,8 +298,8 @@ class Price(BaseModel):


result = await stagehand.extract(
instruction="extract the price",
schema=Price,
"extract the price",
Price,
)
```
</View>
Expand Down Expand Up @@ -371,8 +371,8 @@ class ContactLink(BaseModel):


result = await stagehand.extract(
instruction="extract the contact page link",
schema=ContactLink,
"extract the contact page link",
ContactLink,
)
```
</View>
Expand Down Expand Up @@ -429,8 +429,8 @@ const result = await stagehand.extract(
from stagehand import ModelConfig

result = await stagehand.extract(
instruction="extract the repository name",
schema=Repository,
"extract the repository name",
Repository,
model=ModelConfig.model_validate({
"model_name": "anthropic/claude-sonnet-4-6",
"api_key": os.environ["ANTHROPIC_API_KEY"],
Expand Down Expand Up @@ -516,8 +516,8 @@ stagehand = Stagehand(

# Or disable it for a single call
result = await stagehand.extract(
instruction="extract the repository name",
schema=Repository,
"extract the repository name",
Repository,
cache=False,
)

Expand Down Expand Up @@ -589,8 +589,8 @@ class TableRow(BaseModel):


table_data = (await stagehand.extract(
instruction="Extract the values of the third row",
schema=TableRow,
"Extract the values of the third row",
TableRow,
# xPath or CSS selector
selector="xpath=/html/body/div/table/",
)).data
Expand Down Expand Up @@ -650,8 +650,8 @@ class Article(BaseModel):


article = (await stagehand.extract(
instruction="extract the article title and body",
schema=Article,
"extract the article title and body",
Article,
ignore_selectors=[".ad", ".newsletter-modal", "nav.related-posts"],
)).data
```
Expand Down Expand Up @@ -717,8 +717,8 @@ class SaleBadge(BaseModel):


sale_badge = (await stagehand.extract(
instruction="extract the text shown in the visible sale badge",
schema=SaleBadge,
"extract the text shown in the visible sale badge",
SaleBadge,
screenshot=True,
)).data
```
Expand Down Expand Up @@ -796,11 +796,11 @@ class Apartments(BaseModel):


result = await stagehand.extract(
instruction=(
(
"Extract ALL the apartment listings and their details, "
"including address, price, and square feet."
),
schema=Apartments,
Apartments,
)
```
</View>
Expand Down Expand Up @@ -879,8 +879,8 @@ class ContactLink(BaseModel):


result = await stagehand.extract(
instruction="extract the link to the 'contact us' page",
schema=ContactLink,
"extract the link to the 'contact us' page",
ContactLink,
)

print("the link to the contact us page is: ", result.data.contact_link)
Expand Down Expand Up @@ -973,8 +973,8 @@ class Products(BaseModel):


result = await stagehand.extract(
instruction="extract all product names and prices",
schema=Products,
"extract all product names and prices",
Products,
)
```
</View>
Expand Down Expand Up @@ -1120,7 +1120,7 @@ const { data } = await stagehand.extract(
<View title="Python" icon="python">
```python
# First observe to understand the page structure
observed = await stagehand.observe(instruction="find all product listings")
observed = await stagehand.observe("find all product listings")
print("Found elements:", [element.description for element in observed.data])


Expand All @@ -1135,8 +1135,8 @@ class Products(BaseModel):


result = await stagehand.extract(
instruction="extract name and price from each product listing shown on the page",
schema=Products,
"extract name and price from each product listing shown on the page",
Products,
)
```
</View>
Expand Down Expand Up @@ -1247,8 +1247,8 @@ for page_num in page_numbers:
await stagehand.act(f"navigate to page {page_num}")

result = await stagehand.extract(
instruction="extract product data from the current page only",
schema=Products,
"extract product data from the current page only",
Products,
timeout=60000, # 60 second timeout
)

Expand Down
46 changes: 23 additions & 23 deletions packages/docs/v4/basics/observe.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ await stagehand.observe("find the login button");

<View title="Python" icon="python">
```python
await stagehand.observe(instruction="find the login button")
await stagehand.observe("find the login button")
```
</View>

Expand Down Expand Up @@ -66,7 +66,7 @@ page = await stagehand.context.active_page()
if page is None:
raise RuntimeError("Stagehand initialized without an active page")
await page.goto("https://example.com")
result = await stagehand.observe(instruction="find the learn more button")
result = await stagehand.observe("find the learn more button")
```
</View>

Expand Down Expand Up @@ -173,10 +173,10 @@ await stagehand.observe("find the delete account button in settings");
```python
# Clear and specific
await stagehand.observe(
instruction="find the primary call-to-action button in the hero section"
"find the primary call-to-action button in the hero section"
)
await stagehand.observe(instruction="find all input fields in the checkout form")
await stagehand.observe(instruction="find the delete account button in settings")
await stagehand.observe("find all input fields in the checkout form")
await stagehand.observe("find the delete account button in settings")
```
</View>

Expand Down Expand Up @@ -217,10 +217,10 @@ await stagehand.observe("what is the page title?");
<View title="Python" icon="python">
```python
# Too vague
await stagehand.observe(instruction="find buttons")
await stagehand.observe("find buttons")

# Use extract() for data instead
await stagehand.observe(instruction="what is the page title?")
await stagehand.observe("what is the page title?")
```
</View>

Expand Down Expand Up @@ -266,7 +266,7 @@ from stagehand import ModelConfig

# Custom model configuration
result = await stagehand.observe(
instruction="find navigation links",
"find navigation links",
model=ModelConfig.model_validate({
"model_name": "openai/gpt-5.4-mini",
"api_key": os.environ["OPENAI_API_KEY"],
Expand Down Expand Up @@ -320,7 +320,7 @@ const { data: actions } = await stagehand.observe("find the main call-to-action
<View title="Python" icon="python">
```python
result = await stagehand.observe(
instruction="find the main call-to-action buttons",
"find the main call-to-action buttons",
ignore_selectors=[
"//aside[contains(@class, 'promo-rail')]",
"//div[@id='floating-chat-launcher']",
Expand Down Expand Up @@ -380,7 +380,7 @@ if (emailField && passwordField) {
<View title="Python" icon="python">
```python
observed = await stagehand.observe(
instruction="find the login form fields",
"find the login form fields",
variables={
"username": {"value": "user@example.com", "description": "The login email"},
"password": {
Expand Down Expand Up @@ -503,7 +503,7 @@ stagehand = Stagehand(
)

# Or disable it for a single call
result = await stagehand.observe(instruction="find the login button", cache=False)
result = await stagehand.observe("find the login button", cache=False)
```
</View>

Expand Down Expand Up @@ -575,7 +575,7 @@ await products_page.goto("https://www.example.com/products")

# Use observe with that specific page
result = await stagehand.observe(
instruction="find all product cards",
"find all product cards",
page=products_page,
)
```
Expand Down Expand Up @@ -647,7 +647,7 @@ for (const field of formFields) {

<View title="Python" icon="python">
```python
observed = await stagehand.observe(instruction="find all form input fields")
observed = await stagehand.observe("find all form input fields")

for field in observed.data:
# No LLM call: Stagehand replays the observed action
Expand Down Expand Up @@ -717,11 +717,11 @@ class Pricing(BaseModel):
tiers: list[PricingTier]


observed = await stagehand.observe(instruction="find the pricing table")
observed = await stagehand.observe("find the pricing table")

pricing = (await stagehand.extract(
instruction="extract all pricing tiers",
schema=Pricing,
"extract all pricing tiers",
Pricing,
selector=observed.data[0].selector,
)).data

Expand Down Expand Up @@ -813,7 +813,7 @@ if (deleteButton?.method === "click") {

<View title="Python" icon="python">
```python
observed = await stagehand.observe(instruction="find the delete account button")
observed = await stagehand.observe("find the delete account button")
delete_button = observed.data[0] if observed.data else None

if delete_button is not None and delete_button.method == "click":
Expand Down Expand Up @@ -874,7 +874,7 @@ async def cached_observe(instruction: str) -> list[Action]:
if instruction in action_cache:
return action_cache[instruction]

observed = await stagehand.observe(instruction=instruction)
observed = await stagehand.observe(instruction)
action_cache[instruction] = observed.data
return observed.data
```
Expand Down Expand Up @@ -942,12 +942,12 @@ if page is None:
raise RuntimeError("Stagehand initialized without an active page")
await page.wait_for_load_state("domcontentloaded")

observed = await stagehand.observe(instruction="find the submit button")
observed = await stagehand.observe("find the submit button")

if not observed.data:
print("No elements found, trying alternative instruction")
alt = await stagehand.observe(
instruction="find the button at the bottom of the form"
"find the button at the bottom of the form"
)
```
</View>
Expand Down Expand Up @@ -1006,11 +1006,11 @@ await stagehand.observe("find the red 'Delete' button in the user settings panel
```python
# More specific instructions improve accuracy
# Instead of:
await stagehand.observe(instruction="find the button")
await stagehand.observe("find the button")

# Use context:
await stagehand.observe(
instruction="find the red 'Delete' button in the user settings panel"
"find the red 'Delete' button in the user settings panel"
)
```
</View>
Expand Down Expand Up @@ -1058,7 +1058,7 @@ if (action && validMethods.includes(action.method || "")) {

<View title="Python" icon="python">
```python
observed = await stagehand.observe(instruction="find the submit button")
observed = await stagehand.observe("find the submit button")
action = observed.data[0] if observed.data else None

# Validate method before acting
Expand Down
4 changes: 2 additions & 2 deletions packages/docs/v4/configuration/models.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1312,8 +1312,8 @@ await stagehand.act("click the login button")

# Uses a stronger model for one hard extraction
data = (await stagehand.extract(
instruction="summarize the pricing table",
schema=Pricing,
"summarize the pricing table",
Pricing,
model=ModelConfig.model_validate({
"model_name": "anthropic/claude-sonnet-4-6",
"api_key": os.environ["ANTHROPIC_API_KEY"],
Expand Down
Loading
Loading