Skip to content

[fix] Stagehand Agent param is instructions instead of systemPrompt #1212

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
merged 3 commits into from
Nov 3, 2025
Merged

[fix] Stagehand Agent param is instructions instead of systemPrompt #1212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b9e59bb
Stagehand agent no longer directly takes in instructions. It takes in…
bennycortese Oct 31, 2025
1da0d3b
Changeset added
bennycortese Oct 31, 2025
b987a74
Update packages/core/examples/mcp.ts
miguelg719 Nov 3, 2025
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
6 changes: 6 additions & 0 deletions .changeset/clean-spiders-sell.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@browserbasehq/stagehand": patch
"@browserbasehq/stagehand-docs": patch
---

Updates for documentation and an example for the instructions param becoming a system prompt param in the agent config for stagehand v3
2 changes: 1 addition & 1 deletion packages/docs/v3/best-practices/agent-fallbacks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ try {

const agent = stagehand.agent({
model: "anthropic/claude-sonnet-4-20250514",
instructions: "You are a helpful assistant that can use a web browser.",
systemPrompt: "You are a helpful assistant that can use a web browser.",
});

const result = await agent.execute({
Expand Down
16 changes: 8 additions & 8 deletions packages/docs/v3/best-practices/mcp-integrations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ const agent = stagehand.agent({
integrations: [
`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
],
instructions: `You have access to web search through Exa. Use it to find current information before browsing.`,
systemPrompt: `You have access to web search through Exa. Use it to find current information before browsing.`,
options: {
apiKey: process.env.OPENAI_API_KEY,
},
Expand Down Expand Up @@ -68,7 +68,7 @@ const agent = stagehand.agent({
provider: "openai",
model: "computer-use-preview",
integrations: [supabaseClient, notionClient],
instructions: `You can interact with Supabase databases and Notion. Use these tools to store and retrieve data.`,
systemPrompt: `You can interact with Supabase databases and Notion. Use these tools to store and retrieve data.`,
options: {
apiKey: process.env.OPENAI_API_KEY,
},
Expand All @@ -91,7 +91,7 @@ const agent = stagehand.agent({
`https://search-service.example.com/mcp?apiKey=${process.env.SEARCH_API_KEY}`,
databaseClient
],
instructions: `You have access to external tools for search and data storage. Use these tools strategically to complete tasks efficiently.`
systemPrompt: `You have access to external tools for search and data storage. Use these tools strategically to complete tasks efficiently.`
});
```

Expand Down Expand Up @@ -144,7 +144,7 @@ Provide clear instructions about available tools:
<Tabs>
<Tab title="Good Instructions">
```typescript
instructions: `You have access to:
systemPrompt: `You have access to:
1. Web search tools - Use to find current information
2. Database tools - Use to store/retrieve data
3. Browser automation - Use for web interactions
Expand All @@ -156,7 +156,7 @@ Store important data for later reference.`

<Tab title="Poor Instructions">
```typescript
instructions: "You can search and save data."
systemPrompt: "You can search and save data."
```
</Tab>
</Tabs>
Expand Down Expand Up @@ -221,7 +221,7 @@ try {
```typescript
const agent = stagehand.agent({
integrations: [`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`],
instructions: `First search for current information, then use the browser to complete tasks based on what you find.`
systemPrompt: `First search for current information, then use the browser to complete tasks based on what you find.`
});

await agent.execute("Find the best laptop deals for 2025 and navigate to purchase the top recommendation");
Expand All @@ -233,7 +233,7 @@ const supabaseClient = await connectToMCPServer(/* config */);

const agent = stagehand.agent({
integrations: [supabaseClient],
instructions: `Extract data from websites and store it using available database tools.`
systemPrompt: `Extract data from websites and store it using available database tools.`
});

await agent.execute("Extract all restaurant information from this directory and save it to the database");
Expand All @@ -246,7 +246,7 @@ const agent = stagehand.agent({
`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
supabaseClient
],
instructions: `Use all available tools strategically: search for current info, browse websites, and store important data.`
systemPrompt: `Use all available tools strategically: search for current info, browse websites, and store important data.`
});

await agent.execute("Research competitor pricing, compare with our site, and store the analysis");
Expand Down