From b9e59bb6ee432b1758073f8fc82396a7ebdc42da Mon Sep 17 00:00:00 2001 From: bennycortese Date: Fri, 31 Oct 2025 00:01:32 -0700 Subject: [PATCH 1/3] Stagehand agent no longer directly takes in instructions. It takes in a systemPrompt instead, I noticed this while running npx create-browser-app and seeing the error appear. Updated the V3 docs and mcp.ts to account for this --- packages/core/examples/mcp.ts | 2 +- .../docs/v3/best-practices/agent-fallbacks.mdx | 2 +- .../docs/v3/best-practices/mcp-integrations.mdx | 16 ++++++++-------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/core/examples/mcp.ts b/packages/core/examples/mcp.ts index 652260859..2081d2978 100644 --- a/packages/core/examples/mcp.ts +++ b/packages/core/examples/mcp.ts @@ -31,7 +31,7 @@ // provider: "anthropic", // // For Anthropic, use claude-sonnet-4-20250514 or claude-3-7-sonnet-latest // model: "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. // You are currently on the following page: ${page.url()}. // Do not ask follow up questions, the user will trust your judgement. // You have access to the Notion MCP.`, diff --git a/packages/docs/v3/best-practices/agent-fallbacks.mdx b/packages/docs/v3/best-practices/agent-fallbacks.mdx index ca51a8c2f..ec51a26b9 100644 --- a/packages/docs/v3/best-practices/agent-fallbacks.mdx +++ b/packages/docs/v3/best-practices/agent-fallbacks.mdx @@ -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({ diff --git a/packages/docs/v3/best-practices/mcp-integrations.mdx b/packages/docs/v3/best-practices/mcp-integrations.mdx index 69c5f93ff..5f8d9dce3 100644 --- a/packages/docs/v3/best-practices/mcp-integrations.mdx +++ b/packages/docs/v3/best-practices/mcp-integrations.mdx @@ -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, }, @@ -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, }, @@ -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.` }); ``` @@ -144,7 +144,7 @@ Provide clear instructions about available tools: ```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 @@ -156,7 +156,7 @@ Store important data for later reference.` ```typescript -instructions: "You can search and save data." +systemPrompt: "You can search and save data." ``` @@ -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"); @@ -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"); @@ -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"); From 1da0d3bcf157346c634b3655924d1237b6db5fba Mon Sep 17 00:00:00 2001 From: bennycortese Date: Fri, 31 Oct 2025 00:08:07 -0700 Subject: [PATCH 2/3] Changeset added --- .changeset/clean-spiders-sell.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/clean-spiders-sell.md diff --git a/.changeset/clean-spiders-sell.md b/.changeset/clean-spiders-sell.md new file mode 100644 index 000000000..fd1ddeb52 --- /dev/null +++ b/.changeset/clean-spiders-sell.md @@ -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 From b987a74326e814e1c03bf2108ac17024758ce756 Mon Sep 17 00:00:00 2001 From: Miguel <36487034+miguelg719@users.noreply.github.com> Date: Sun, 2 Nov 2025 19:09:55 -0800 Subject: [PATCH 3/3] Update packages/core/examples/mcp.ts --- packages/core/examples/mcp.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core/examples/mcp.ts b/packages/core/examples/mcp.ts index 2081d2978..652260859 100644 --- a/packages/core/examples/mcp.ts +++ b/packages/core/examples/mcp.ts @@ -31,7 +31,7 @@ // provider: "anthropic", // // For Anthropic, use claude-sonnet-4-20250514 or claude-3-7-sonnet-latest // model: "claude-sonnet-4-20250514", -// systemPrompt: `You are a helpful assistant that can use a web browser. +// instructions: `You are a helpful assistant that can use a web browser. // You are currently on the following page: ${page.url()}. // Do not ask follow up questions, the user will trust your judgement. // You have access to the Notion MCP.`,