Best Practices

Use Cursor rules for better AI suggestions

Most of the Stagehand team uses Cursor to write code. Cursor has a feature called rules that allows you to customize the AI’s behavior. You can use these rules to make the AI more accurate when suggesting actions. For Stagehand’s Cursor rules, check out this file. If you’re using Windsurf, you can use the same rules by adding them to your .windsurfrules file.

Avoid sending sensitive information to LLMs

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

await page.act({
	action: "Type %email% into the email field",
	variables: {
		email: "[email protected]",
	},
});

await page.act({
	"Type %email% into the email field",
	variables={
		"email": "[email protected]",
	}
})

Preview actions before running them

You can use observe() to get an action to run without running it. If you’re satisfied with the action, you can run it with act() without any LLM inference.

const [topAction] = await page.observe("Click the quickstart link");

/** The action will map 1:1 with a Playwright action:
{
	description: "The quickstart link",
	method: "click",
	selector: "/html/body/div[1]/div[1]/a",
	arguments: [],
}
**/

// NO LLM INFERENCE on observe results
await page.act(topAction)

actions = await page.observe("Click the quickstart link")
top_action = actions[0]

# The action will map 1:1 with a Playwright action:
# {
#		"description": "The quickstart link",
#		"method": "click",
#		"selector": "/html/body/div[1]/div[1]/a",
#		"arguments": [],
# }

# NO LLM INFERENCE on observe results
await page.act(top_action)

You can also use observe() with sensitive information, like below.

const [topAction] = await page.observe("Type %email% into the email field");

/** The observe result will be an object with the following shape:
{
	description: "The email input field",
	method: "type",
	selector: "/html/body/div[1]/div[1]/input",
	arguments: ["%email%"],
}
*/

await page.act({
	...topAction,
	// This prevents LLMs from seeing sensitive information
	// No LLM inference is taken on observe results
	arguments: [sensitiveEmail],
})

actions = await page.observe("Type %email% into the email field")
top_action = actions[0]

# The observe result will be a dictionary with the following shape:
# {
#		"description": "The email input field",
#		"method": "type",
#		"selector": "/html/body/div[1]/div[1]/input",
#		"arguments": ["%email%"],
# }

await page.act({
	**top_action,
	# This prevents LLMs from seeing sensitive information
	# No LLM inference is taken on observe results
	"arguments": [sensitive_email],
})

Use observe() to get actionable suggestions from the current page

const actions = await page.observe();
console.log("Possible actions:", actions);

// You can also use `observe()` with a custom prompt
const buttons = await page.observe({
	instruction: "find all the buttons on the page",
});

actions = await page.observe()
print("Possible actions:", actions)

# You can also use `observe()` with a custom prompt
buttons = await page.observe("find all the buttons on the page")

Avoid broad or ambiguous instructions

Avoid instructions that aren’t specific to the current page or try to do multiple things at once.

// Too vague
await page.act({ action: "find something interesting on the page" });

// Avoid combining actions
await page.act({ action: "fill out the form and submit it" });

# Too vague
await page.act("find something interesting on the page")

# Avoid combining actions
await page.act("fill out the form and submit it")

Use `observe()` to get entire form values

const formValues = await page.observe("get the text inputs on the page");

form_values = await page.observe("get the text inputs on the page")

This will return an array of objects with the following shape:

{
	description: "The text input field",
	method: "type",
	selector: "/html/body/div[1]/div[1]/input",
	arguments: ["some text"],
}

{
	"description": "The text input field",
	"method": "type",
	"selector": "/html/body/div[1]/div[1]/input",
	"arguments": ["some text"],
}

You can then use these actions directly in your code.

for (const formValue of formValues) {
	await page.act({
		...formValue,
		arguments: [yourValueHere],
	});
}

for form_value in form_values:
	await page.act({
		**form_value,
		"arguments": [your_value_here],
	})

For a full example, check out the example in the Stagehand repo here.

Get Started

Concepts

Playbooks

Reference

Integrations

Use Cursor rules for better AI suggestions

Avoid sending sensitive information to LLMs

Preview actions before running them

Avoid broad or ambiguous instructions

Use `observe()` to get entire form values

​Use Cursor rules for better AI suggestions

​Avoid sending sensitive information to LLMs

​Preview actions before running them

​Avoid broad or ambiguous instructions

​Use observe() to get entire form values

Use Cursor rules for better AI suggestions

Avoid sending sensitive information to LLMs

Preview actions before running them

Avoid broad or ambiguous instructions

Use `observe()` to get entire form values