From 886ef3358c227b426d5c7f9272fe50c060233977 Mon Sep 17 00:00:00 2001 From: Benny Cortese Date: Sun, 2 Nov 2025 19:16:23 -0800 Subject: [PATCH 1/2] [fix] Stagehand Agent param is instructions instead of systemPrompt (#1212) 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 Fixed this only in the v3 documentation here, but if we are breaking backwards compatibility (I assume probably not), then the following v2 doc files should also be updated: agent.mdx agent-fallbacks.mdx computer-use.mdx mcp-integrations.mdx ai-rules.mdx quickstart.mdx --------- Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com> --- .changeset/clean-spiders-sell.md | 6 ++++++ .../docs/v3/best-practices/agent-fallbacks.mdx | 2 +- .../docs/v3/best-practices/mcp-integrations.mdx | 16 ++++++++-------- 3 files changed, 15 insertions(+), 9 deletions(-) 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 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 9324b82983281a863687c74b1c58abc4c94d513e Mon Sep 17 00:00:00 2001 From: miguel Date: Sun, 2 Nov 2025 19:17:03 -0800 Subject: [PATCH 2/2] remove docs changeset --- .changeset/clean-spiders-sell.md | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 .changeset/clean-spiders-sell.md diff --git a/.changeset/clean-spiders-sell.md b/.changeset/clean-spiders-sell.md deleted file mode 100644 index fd1ddeb52..000000000 --- a/.changeset/clean-spiders-sell.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -"@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