@browserbasehq/orca 3.2.0-preview.1 → 3.2.0-preview.3

package/dist/cjs/lib/v3/agent/prompts/agentSystemPrompt.d.ts

@@ -10,5 +10,7 @@ export interface AgentSystemPromptOptions {
     excludeTools?: string[];
     /** Variables available to the agent for use in act/type tools */
     variables?: Variables;
+    /** Whether the search tool is enabled for this execution */
+    useSearch?: boolean;
 }
 export declare function buildAgentSystemPrompt(options: AgentSystemPromptOptions): string;

package/dist/cjs/lib/v3/agent/prompts/agentSystemPrompt.js

@@ -74,12 +74,12 @@ function buildToolsSection(isHybridMode, hasSearch, excludeTools) {
     return `<tools>\n${toolLines}\n  </tools>`;
 }
 function buildAgentSystemPrompt(options) {
-    const { url, executionInstruction, mode, systemInstructions, isBrowserbase = false, excludeTools, variables, } = options;
+    const { url, executionInstruction, mode, systemInstructions, isBrowserbase = false, excludeTools, variables, useSearch = false, } = options;
     const localeDate = new Date().toLocaleDateString();
     const isoDate = new Date().toISOString();
     const cdata = (text) => `<![CDATA[${text}]]>`;
     const isHybridMode = mode === "hybrid";
-    const hasSearch = Boolean(process.env.BRAVE_API_KEY);
+    const hasSearch = useSearch || Boolean(process.env.BRAVE_API_KEY);
     // Tools section differs based on mode and excluded tools
     const toolsSection = buildToolsSection(isHybridMode, hasSearch, excludeTools);
     // Strategy differs based on mode

package/dist/cjs/lib/v3/agent/prompts/agentSystemPrompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentSystemPrompt.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/prompts/agentSystemPrompt.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentToolMode, Variables } from \"../../types/public/agent.js\";\n\nexport interface AgentSystemPromptOptions {\n  url: string;\n  executionInstruction: string;\n  mode: AgentToolMode;\n  systemInstructions?: string;\n  /** Whether running on Browserbase (enables captcha solver messaging) */\n  isBrowserbase?: boolean;\n  /** Tools to exclude from the system prompt */\n  excludeTools?: string[];\n  /** Variables available to the agent for use in act/type tools */\n  variables?: Variables;\n}\n\n/**\n * Builds the system prompt for the agent based on the tool mode.\n *\n * @param options - The prompt configuration options\n * @returns The formatted system prompt string\n */\ninterface ToolDefinition {\n  name: string;\n  description: string;\n}\n\nfunction buildToolsSection(\n  isHybridMode: boolean,\n  hasSearch: boolean,\n  excludeTools?: string[],\n): string {\n  const excludeSet = new Set(excludeTools ?? []);\n\n  const hybridTools: ToolDefinition[] = [\n    {\n      name: \"screenshot\",\n      description: \"Take a compressed JPEG screenshot for quick visual context\",\n    },\n    {\n      name: \"ariaTree\",\n      description:\n        \"Get an accessibility (ARIA) hybrid tree for full page context\",\n    },\n    {\n      name: \"click\",\n      description:\n        \"Click on an element (PREFERRED - more reliable when element is visible in viewport)\",\n    },\n    {\n      name: \"type\",\n      description:\n        \"Type text into an element (PREFERRED - more reliable when element is visible in viewport)\",\n    },\n    {\n      name: \"act\",\n      description:\n        \"Perform a specific atomic action (click, type, etc.) - ONLY use when element is in ariaTree but NOT visible in screenshot. Less reliable but can interact with out-of-viewport elements.\",\n    },\n    { name: \"dragAndDrop\", description: \"Drag and drop an element\" },\n    { name: \"clickAndHold\", description: \"Click and hold on an element\" },\n    { name: \"keys\", description: \"Press a keyboard key\" },\n    {\n      name: \"fillFormVision\",\n      description: \"Fill out a form using coordinates\",\n    },\n    { name: \"think\", description: \"Think about the task\" },\n    { name: \"extract\", description: \"Extract structured data\" },\n    { name: \"goto\", description: \"Navigate to a URL\" },\n    { name: \"wait\", description: \"Wait for a specified time\" },\n    { name: \"navback\", description: \"Navigate back in browser history\" },\n    { name: \"scroll\", description: \"Scroll the page x pixels up or down\" },\n  ];\n\n  const domTools: ToolDefinition[] = [\n    {\n      name: \"screenshot\",\n      description: \"Take a compressed JPEG screenshot for quick visual context\",\n    },\n    {\n      name: \"ariaTree\",\n      description:\n        \"Get an accessibility (ARIA) hybrid tree for full page context\",\n    },\n    {\n      name: \"act\",\n      description: \"Perform a specific atomic action (click, type)\",\n    },\n    { name: \"keys\", description: \"Press a keyboard key\" },\n    { name: \"fillForm\", description: \"Fill out a form\" },\n    { name: \"think\", description: \"Think about the task\" },\n    { name: \"extract\", description: \"Extract structured data\" },\n    { name: \"goto\", description: \"Navigate to a URL\" },\n    { name: \"wait\", description: \"Wait for a specified time\" },\n    { name: \"navback\", description: \"Navigate back in browser history\" },\n    { name: \"scroll\", description: \"Scroll the page x pixels up or down\" },\n  ];\n\n  const baseTools = isHybridMode ? hybridTools : domTools;\n\n  if (hasSearch) {\n    baseTools.push({\n      name: \"search\",\n      description:\n        \"Perform a web search and return results. Prefer this over navigating to Google and searching within the page for reliability and efficiency.\",\n    });\n  }\n\n  const filteredTools = baseTools.filter((tool) => !excludeSet.has(tool.name));\n\n  const toolLines = filteredTools\n    .map((tool) => `    <tool name=\"${tool.name}\">${tool.description}</tool>`)\n    .join(\"\\n\");\n\n  return `<tools>\\n${toolLines}\\n  </tools>`;\n}\n\nexport function buildAgentSystemPrompt(\n  options: AgentSystemPromptOptions,\n): string {\n  const {\n    url,\n    executionInstruction,\n    mode,\n    systemInstructions,\n    isBrowserbase = false,\n    excludeTools,\n    variables,\n  } = options;\n  const localeDate = new Date().toLocaleDateString();\n  const isoDate = new Date().toISOString();\n  const cdata = (text: string) => `<![CDATA[${text}]]>`;\n\n  const isHybridMode = mode === \"hybrid\";\n  const hasSearch = Boolean(process.env.BRAVE_API_KEY);\n\n  // Tools section differs based on mode and excluded tools\n  const toolsSection = buildToolsSection(isHybridMode, hasSearch, excludeTools);\n\n  // Strategy differs based on mode\n  const strategyItems = isHybridMode\n    ? [\n        `<item>Tool selection priority: Use specific tools (click, type) when elements are visible in viewport for maximum reliability.</item>`,\n        `<item>Always use screenshot to get proper grounding of the coordinates you want to type/click into.</item>`,\n        `<item>When interacting with an input, always use the type tool to type into the input, over clicking and then typing into it.</item>`,\n        `<item>Use ariaTree as a secondary tool when elements aren't visible in screenshot or to get full page context.</item>`,\n        `<item>Only use act when element is in ariaTree but NOT visible in screenshot.</item>`,\n      ]\n    : [\n        `<item>Tool selection priority: Use act tool for all clicking and typing on a page.</item>`,\n        `<item>Always check ariaTree first to understand full page content without scrolling - it shows all elements including those below the fold.</item>`,\n        `<item>When interacting with an input, always use the act tool to type into the input, over clicking and then typing.</item>`,\n        `<item>If an element is present in the ariaTree, use act to interact with it directly - this eliminates the need to scroll.</item>`,\n        `<item>Use screenshot for visual confirmation when needed, but rely primarily on ariaTree for element detection.</item>`,\n      ];\n\n  const strategySection = strategyItems.join(\"\\n    \");\n\n  const commonStrategyItems = `\n    <item>CRITICAL: Use extract ONLY when the task explicitly requires structured data output (e.g., \"get job listings\", \"extract product details\"). For reading page content or understanding elements, always use ${isHybridMode ? \"screenshot or ariaTree\" : \"ariaTree\"} instead - it's faster and more reliable.</item>\n    <item>Keep actions atomic and verify outcomes before proceeding.</item>\n    <item>For each action, provide clear reasoning about why you're taking that step.</item>\n    <item>When you need to input text that could be entered character-by-character or through multiple separate inputs, prefer using the keys tool to type the entire sequence at once. This is more efficient for scenarios like verification codes split across multiple fields, or when virtual keyboards are present but direct typing would be faster.</item>\n    `;\n\n  // Page understanding protocol differs based on mode\n  const pageUnderstandingProtocol = isHybridMode\n    ? `<page_understanding_protocol>\n    <step_1>\n      <title>UNDERSTAND THE PAGE</title>\n      <primary_tool>\n        <name>screenshot</name>\n        <usage>Visual confirmation when needed. Ideally after navigating to a new page.</usage>\n        </primary_tool>\n      <secondary_tool>\n        <name>ariaTree</name>\n        <usage>Get complete page context before taking actions</usage>\n        <benefit>Eliminates the need to scroll and provides full accessible content</benefit>\n      </secondary_tool>\n    </step_1>\n  </page_understanding_protocol>`\n    : `<page_understanding_protocol>\n    <step_1>\n      <title>UNDERSTAND THE PAGE</title>\n      <primary_tool>\n        <name>ariaTree</name>\n        <usage>Get complete page context before taking actions</usage>\n        <benefit>Eliminates the need to scroll and provides full accessible content</benefit>\n        </primary_tool>\n      <secondary_tool>\n        <name>screenshot</name>\n        <usage>Visual confirmation when needed. Ideally after navigating to a new page.</usage>\n      </secondary_tool>\n    </step_1>\n  </page_understanding_protocol>`;\n\n  // Roadblocks section only shown when running on Browserbase (has captcha solver)\n  const roadblocksSection = isBrowserbase\n    ? `<roadblocks>\n    <note>captchas, popups, etc.</note>\n    <captcha>If you see a captcha, use the wait tool. It will automatically be solved by our internal solver.</captcha>\n  </roadblocks>`\n    : \"\";\n\n  // Build customInstructions block only if provided\n  const customInstructionsBlock = systemInstructions\n    ? `<customInstructions>${cdata(systemInstructions)}</customInstructions>\\n  `\n    : \"\";\n\n  // Build variables section only if variables are provided\n  const hasVariables = variables && Object.keys(variables).length > 0;\n  const variableToolsNote = isHybridMode\n    ? \"Use %variableName% syntax in the type, fillFormVision, or act tool's value/text/action fields.\"\n    : \"Use %variableName% syntax in the act or fillForm tool's value/action fields.\";\n  const variablesSection = hasVariables\n    ? `<variables>\n    <note>You have access to the following variables. Use %variableName% syntax to substitute variable values. This is especially important for sensitive data like passwords.</note>\n    <usage>${variableToolsNote}</usage>\n    <example>To type a password, use: type %password% into the password field</example>\n    ${Object.entries(variables)\n      .map(([name, v]) => {\n        const description =\n          typeof v === \"object\" && v !== null && \"value\" in v\n            ? v.description\n            : undefined;\n        return description\n          ? `<variable name=\"${name}\">${description}</variable>`\n          : `<variable name=\"${name}\" />`;\n      })\n      .join(\"\\n    \")}\n  </variables>`\n    : \"\";\n\n  return `<system>\n  <identity>You are a web automation assistant using browser automation tools to accomplish the user's goal.</identity>\n  ${customInstructionsBlock}<task>\n    <goal>${cdata(executionInstruction)}</goal>\n    <date display=\"local\" iso=\"${isoDate}\">${localeDate}</date>\n    <note>You may think the date is different due to knowledge cutoff, but this is the actual date.</note>\n  </task>\n  <page>\n    <startingUrl>you are starting your task on this url: ${url}</startingUrl>\n  </page>\n  <mindset>\n    <note>Be very intentional about your action. The initial instruction is very important, and slight variations of the actual goal can lead to failures.</note>\n    <importantNote>If something fails to meet a single condition of the task, move on from it rather than seeing if it meets other criteria. We only care that it meets all of it</importantNote>\n    <note>When the task is complete, do not seek more information; you have completed the task.</note>\n  </mindset>\n  <guidelines>\n    <item>Always start by understanding the current page state</item>\n    <item>Use the screenshot tool to verify page state when needed</item>\n    <item>Use appropriate tools for each action</item>\n  </guidelines>\n  ${pageUnderstandingProtocol}\n  <navigation>\n    <rule>If you are confident in the URL, navigate directly to it.</rule>\n    ${hasSearch ? `<rule>If you are not confident in the URL, use the search tool to find it.</rule>` : ``}\n  </navigation>\n  ${toolsSection}\n  <strategy>\n    ${strategySection}\n    ${commonStrategyItems}\n  </strategy>\n  ${roadblocksSection}\n  ${variablesSection}\n  <completion>\n    <note>When you complete the task, explain any information that was found that was relevant to the original task.</note>\n    <examples>\n      <example>If you were asked for specific flights, list the flights you found.</example>\n      <example>If you were asked for information about a product, list the product information you were asked for.</example>\n    </examples>\n  </completion>\n</system>`;\n}\n"]}
+{"version":3,"file":"agentSystemPrompt.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/prompts/agentSystemPrompt.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentToolMode, Variables } from \"../../types/public/agent.js\";\n\nexport interface AgentSystemPromptOptions {\n  url: string;\n  executionInstruction: string;\n  mode: AgentToolMode;\n  systemInstructions?: string;\n  /** Whether running on Browserbase (enables captcha solver messaging) */\n  isBrowserbase?: boolean;\n  /** Tools to exclude from the system prompt */\n  excludeTools?: string[];\n  /** Variables available to the agent for use in act/type tools */\n  variables?: Variables;\n  /** Whether the search tool is enabled for this execution */\n  useSearch?: boolean;\n}\n\n/**\n * Builds the system prompt for the agent based on the tool mode.\n *\n * @param options - The prompt configuration options\n * @returns The formatted system prompt string\n */\ninterface ToolDefinition {\n  name: string;\n  description: string;\n}\n\nfunction buildToolsSection(\n  isHybridMode: boolean,\n  hasSearch: boolean,\n  excludeTools?: string[],\n): string {\n  const excludeSet = new Set(excludeTools ?? []);\n\n  const hybridTools: ToolDefinition[] = [\n    {\n      name: \"screenshot\",\n      description: \"Take a compressed JPEG screenshot for quick visual context\",\n    },\n    {\n      name: \"ariaTree\",\n      description:\n        \"Get an accessibility (ARIA) hybrid tree for full page context\",\n    },\n    {\n      name: \"click\",\n      description:\n        \"Click on an element (PREFERRED - more reliable when element is visible in viewport)\",\n    },\n    {\n      name: \"type\",\n      description:\n        \"Type text into an element (PREFERRED - more reliable when element is visible in viewport)\",\n    },\n    {\n      name: \"act\",\n      description:\n        \"Perform a specific atomic action (click, type, etc.) - ONLY use when element is in ariaTree but NOT visible in screenshot. Less reliable but can interact with out-of-viewport elements.\",\n    },\n    { name: \"dragAndDrop\", description: \"Drag and drop an element\" },\n    { name: \"clickAndHold\", description: \"Click and hold on an element\" },\n    { name: \"keys\", description: \"Press a keyboard key\" },\n    {\n      name: \"fillFormVision\",\n      description: \"Fill out a form using coordinates\",\n    },\n    { name: \"think\", description: \"Think about the task\" },\n    { name: \"extract\", description: \"Extract structured data\" },\n    { name: \"goto\", description: \"Navigate to a URL\" },\n    { name: \"wait\", description: \"Wait for a specified time\" },\n    { name: \"navback\", description: \"Navigate back in browser history\" },\n    { name: \"scroll\", description: \"Scroll the page x pixels up or down\" },\n  ];\n\n  const domTools: ToolDefinition[] = [\n    {\n      name: \"screenshot\",\n      description: \"Take a compressed JPEG screenshot for quick visual context\",\n    },\n    {\n      name: \"ariaTree\",\n      description:\n        \"Get an accessibility (ARIA) hybrid tree for full page context\",\n    },\n    {\n      name: \"act\",\n      description: \"Perform a specific atomic action (click, type)\",\n    },\n    { name: \"keys\", description: \"Press a keyboard key\" },\n    { name: \"fillForm\", description: \"Fill out a form\" },\n    { name: \"think\", description: \"Think about the task\" },\n    { name: \"extract\", description: \"Extract structured data\" },\n    { name: \"goto\", description: \"Navigate to a URL\" },\n    { name: \"wait\", description: \"Wait for a specified time\" },\n    { name: \"navback\", description: \"Navigate back in browser history\" },\n    { name: \"scroll\", description: \"Scroll the page x pixels up or down\" },\n  ];\n\n  const baseTools = isHybridMode ? hybridTools : domTools;\n\n  if (hasSearch) {\n    baseTools.push({\n      name: \"search\",\n      description:\n        \"Perform a web search and return results. Prefer this over navigating to Google and searching within the page for reliability and efficiency.\",\n    });\n  }\n\n  const filteredTools = baseTools.filter((tool) => !excludeSet.has(tool.name));\n\n  const toolLines = filteredTools\n    .map((tool) => `    <tool name=\"${tool.name}\">${tool.description}</tool>`)\n    .join(\"\\n\");\n\n  return `<tools>\\n${toolLines}\\n  </tools>`;\n}\n\nexport function buildAgentSystemPrompt(\n  options: AgentSystemPromptOptions,\n): string {\n  const {\n    url,\n    executionInstruction,\n    mode,\n    systemInstructions,\n    isBrowserbase = false,\n    excludeTools,\n    variables,\n    useSearch = false,\n  } = options;\n  const localeDate = new Date().toLocaleDateString();\n  const isoDate = new Date().toISOString();\n  const cdata = (text: string) => `<![CDATA[${text}]]>`;\n\n  const isHybridMode = mode === \"hybrid\";\n  const hasSearch = useSearch || Boolean(process.env.BRAVE_API_KEY);\n\n  // Tools section differs based on mode and excluded tools\n  const toolsSection = buildToolsSection(isHybridMode, hasSearch, excludeTools);\n\n  // Strategy differs based on mode\n  const strategyItems = isHybridMode\n    ? [\n        `<item>Tool selection priority: Use specific tools (click, type) when elements are visible in viewport for maximum reliability.</item>`,\n        `<item>Always use screenshot to get proper grounding of the coordinates you want to type/click into.</item>`,\n        `<item>When interacting with an input, always use the type tool to type into the input, over clicking and then typing into it.</item>`,\n        `<item>Use ariaTree as a secondary tool when elements aren't visible in screenshot or to get full page context.</item>`,\n        `<item>Only use act when element is in ariaTree but NOT visible in screenshot.</item>`,\n      ]\n    : [\n        `<item>Tool selection priority: Use act tool for all clicking and typing on a page.</item>`,\n        `<item>Always check ariaTree first to understand full page content without scrolling - it shows all elements including those below the fold.</item>`,\n        `<item>When interacting with an input, always use the act tool to type into the input, over clicking and then typing.</item>`,\n        `<item>If an element is present in the ariaTree, use act to interact with it directly - this eliminates the need to scroll.</item>`,\n        `<item>Use screenshot for visual confirmation when needed, but rely primarily on ariaTree for element detection.</item>`,\n      ];\n\n  const strategySection = strategyItems.join(\"\\n    \");\n\n  const commonStrategyItems = `\n    <item>CRITICAL: Use extract ONLY when the task explicitly requires structured data output (e.g., \"get job listings\", \"extract product details\"). For reading page content or understanding elements, always use ${isHybridMode ? \"screenshot or ariaTree\" : \"ariaTree\"} instead - it's faster and more reliable.</item>\n    <item>Keep actions atomic and verify outcomes before proceeding.</item>\n    <item>For each action, provide clear reasoning about why you're taking that step.</item>\n    <item>When you need to input text that could be entered character-by-character or through multiple separate inputs, prefer using the keys tool to type the entire sequence at once. This is more efficient for scenarios like verification codes split across multiple fields, or when virtual keyboards are present but direct typing would be faster.</item>\n    `;\n\n  // Page understanding protocol differs based on mode\n  const pageUnderstandingProtocol = isHybridMode\n    ? `<page_understanding_protocol>\n    <step_1>\n      <title>UNDERSTAND THE PAGE</title>\n      <primary_tool>\n        <name>screenshot</name>\n        <usage>Visual confirmation when needed. Ideally after navigating to a new page.</usage>\n        </primary_tool>\n      <secondary_tool>\n        <name>ariaTree</name>\n        <usage>Get complete page context before taking actions</usage>\n        <benefit>Eliminates the need to scroll and provides full accessible content</benefit>\n      </secondary_tool>\n    </step_1>\n  </page_understanding_protocol>`\n    : `<page_understanding_protocol>\n    <step_1>\n      <title>UNDERSTAND THE PAGE</title>\n      <primary_tool>\n        <name>ariaTree</name>\n        <usage>Get complete page context before taking actions</usage>\n        <benefit>Eliminates the need to scroll and provides full accessible content</benefit>\n        </primary_tool>\n      <secondary_tool>\n        <name>screenshot</name>\n        <usage>Visual confirmation when needed. Ideally after navigating to a new page.</usage>\n      </secondary_tool>\n    </step_1>\n  </page_understanding_protocol>`;\n\n  // Roadblocks section only shown when running on Browserbase (has captcha solver)\n  const roadblocksSection = isBrowserbase\n    ? `<roadblocks>\n    <note>captchas, popups, etc.</note>\n    <captcha>If you see a captcha, use the wait tool. It will automatically be solved by our internal solver.</captcha>\n  </roadblocks>`\n    : \"\";\n\n  // Build customInstructions block only if provided\n  const customInstructionsBlock = systemInstructions\n    ? `<customInstructions>${cdata(systemInstructions)}</customInstructions>\\n  `\n    : \"\";\n\n  // Build variables section only if variables are provided\n  const hasVariables = variables && Object.keys(variables).length > 0;\n  const variableToolsNote = isHybridMode\n    ? \"Use %variableName% syntax in the type, fillFormVision, or act tool's value/text/action fields.\"\n    : \"Use %variableName% syntax in the act or fillForm tool's value/action fields.\";\n  const variablesSection = hasVariables\n    ? `<variables>\n    <note>You have access to the following variables. Use %variableName% syntax to substitute variable values. This is especially important for sensitive data like passwords.</note>\n    <usage>${variableToolsNote}</usage>\n    <example>To type a password, use: type %password% into the password field</example>\n    ${Object.entries(variables)\n      .map(([name, v]) => {\n        const description =\n          typeof v === \"object\" && v !== null && \"value\" in v\n            ? v.description\n            : undefined;\n        return description\n          ? `<variable name=\"${name}\">${description}</variable>`\n          : `<variable name=\"${name}\" />`;\n      })\n      .join(\"\\n    \")}\n  </variables>`\n    : \"\";\n\n  return `<system>\n  <identity>You are a web automation assistant using browser automation tools to accomplish the user's goal.</identity>\n  ${customInstructionsBlock}<task>\n    <goal>${cdata(executionInstruction)}</goal>\n    <date display=\"local\" iso=\"${isoDate}\">${localeDate}</date>\n    <note>You may think the date is different due to knowledge cutoff, but this is the actual date.</note>\n  </task>\n  <page>\n    <startingUrl>you are starting your task on this url: ${url}</startingUrl>\n  </page>\n  <mindset>\n    <note>Be very intentional about your action. The initial instruction is very important, and slight variations of the actual goal can lead to failures.</note>\n    <importantNote>If something fails to meet a single condition of the task, move on from it rather than seeing if it meets other criteria. We only care that it meets all of it</importantNote>\n    <note>When the task is complete, do not seek more information; you have completed the task.</note>\n  </mindset>\n  <guidelines>\n    <item>Always start by understanding the current page state</item>\n    <item>Use the screenshot tool to verify page state when needed</item>\n    <item>Use appropriate tools for each action</item>\n  </guidelines>\n  ${pageUnderstandingProtocol}\n  <navigation>\n    <rule>If you are confident in the URL, navigate directly to it.</rule>\n    ${hasSearch ? `<rule>If you are not confident in the URL, use the search tool to find it.</rule>` : ``}\n  </navigation>\n  ${toolsSection}\n  <strategy>\n    ${strategySection}\n    ${commonStrategyItems}\n  </strategy>\n  ${roadblocksSection}\n  ${variablesSection}\n  <completion>\n    <note>When you complete the task, explain any information that was found that was relevant to the original task.</note>\n    <examples>\n      <example>If you were asked for specific flights, list the flights you found.</example>\n      <example>If you were asked for information about a product, list the product information you were asked for.</example>\n    </examples>\n  </completion>\n</system>`;\n}\n"]}

package/dist/cjs/lib/v3/agent/tools/{search.js → braveSearch.js}

@@ -74,4 +74,4 @@ const searchTool = (v3) => (0, ai_1.tool)({
     },
 });
 exports.searchTool = searchTool;
-//# sourceMappingURL=search.js.map
+//# sourceMappingURL=braveSearch.js.map

package/dist/cjs/lib/v3/agent/tools/braveSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"braveSearch.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/braveSearch.ts"],"names":[],"mappings":"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","sourcesContent":["import { tool } from \"ai\";\nimport { z } from \"zod\";\nimport type { V3 } from \"../../v3.js\";\n\nexport interface BraveSearchResult {\n  title: string;\n  url: string;\n  description?: string;\n}\n\ninterface SearchResponse {\n  data?: {\n    results: BraveSearchResult[];\n  };\n  error?: string;\n}\n\ninterface BraveWebResult {\n  title?: string;\n  url?: string;\n  description?: string;\n  age?: string;\n  meta_url?: {\n    favicon?: string;\n  };\n}\n\ninterface BraveApiResponse {\n  web?: {\n    results?: BraveWebResult[];\n  };\n}\n\nasync function performBraveSearch(query: string): Promise<SearchResponse> {\n  try {\n    const encodedQuery = encodeURIComponent(query);\n    const response = await fetch(\n      `https://api.search.brave.com/res/v1/web/search?q=${encodedQuery}`,\n      {\n        method: \"GET\",\n        headers: {\n          Accept: \"application/json\",\n          \"Accept-Encoding\": \"gzip\",\n          \"X-Subscription-Token\": process.env.BRAVE_API_KEY!,\n        },\n      },\n    );\n\n    if (!response.ok) {\n      return {\n        error: `Brave API error: ${response.status} ${response.statusText}`,\n        data: { results: [] },\n      };\n    }\n\n    const data = (await response.json()) as BraveApiResponse;\n    const results: BraveSearchResult[] = [];\n\n    if (data?.web?.results && Array.isArray(data.web.results)) {\n      for (const item of data.web.results.slice(0, 5)) {\n        if (item.title && item.url) {\n          results.push({\n            title: item.title,\n            url: item.url,\n            description: item.description,\n          });\n        }\n      }\n    }\n\n    return { data: { results } };\n  } catch (error) {\n    console.error(\"Search error\", error);\n    return {\n      error: `Error performing search: ${(error as Error).message}`,\n      data: { results: [] },\n    };\n  }\n}\n\nexport const searchTool = (v3: V3) =>\n  tool({\n    description:\n      \"Perform a web search and returns results. Use this tool when you need information from the web or when you are unsure of the exact URL you want to navigate to. This can be used to find the ideal entry point, resulting in a task that is easier to complete due to starting further in the process.\",\n    inputSchema: z.object({\n      query: z.string().describe(\"The search query to look for on the web\"),\n    }),\n    execute: async ({ query }) => {\n      v3.logger({\n        category: \"agent\",\n        message: `Agent calling tool: search`,\n        level: 1,\n        auxiliary: {\n          arguments: {\n            value: JSON.stringify({ query }),\n            type: \"object\",\n          },\n        },\n      });\n\n      const result = await performBraveSearch(query);\n\n      v3.recordAgentReplayStep({\n        type: \"search\",\n        instruction: query,\n        playwrightArguments: { query },\n        message:\n          result.error ?? `Found ${result.data?.results.length ?? 0} results`,\n      });\n\n      return {\n        ...result,\n        timestamp: Date.now(),\n      };\n    },\n  });\n"]}

package/dist/cjs/lib/v3/agent/tools/browserbaseSearch.d.ts

@@ -0,0 +1,13 @@
+import type { V3 } from "../../v3.js";
+export interface SearchResult {
+    title: string;
+    url: string;
+    publishedDate?: string;
+}
+export declare const searchTool: (v3: V3, apiKey: string) => import("ai").Tool<{
+    query: string;
+}, {
+    timestamp: number;
+    results: SearchResult[];
+    error?: string;
+}>;

package/dist/cjs/lib/v3/agent/tools/browserbaseSearch.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchTool = void 0;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+async function performBrowserbaseSearch(v3, query, apiKey, numResults = 5) {
+    try {
+        const response = await fetch("https://api.browserbase.com/v1/search", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-bb-api-key": apiKey,
+            },
+            body: JSON.stringify({ query, numResults }),
+        });
+        if (!response.ok) {
+            return {
+                results: [],
+                error: `Browserbase Search API error: ${response.status} ${response.statusText}`,
+            };
+        }
+        const data = (await response.json());
+        const results = (data?.results ?? []).map(({ title, url, publishedDate }) => ({
+            title: title,
+            url: url,
+            ...(publishedDate && { publishedDate }),
+        }));
+        return { results };
+    }
+    catch (error) {
+        v3.logger({
+            category: "agent",
+            message: `Search error: ${error.message}`,
+            level: 0,
+        });
+        return {
+            results: [],
+            error: `Error performing search: ${error.message}`,
+        };
+    }
+}
+const searchTool = (v3, apiKey) => (0, ai_1.tool)({
+    description: "Perform a web search and returns results. Use this tool when you need information from the web or when you are unsure of the exact URL you want to navigate to. This can be used to find the ideal entry point, resulting in a task that is easier to complete due to starting further in the process.",
+    inputSchema: zod_1.z.object({
+        query: zod_1.z.string().describe("The search query to look for on the web"),
+    }),
+    execute: async ({ query }) => {
+        v3.logger({
+            category: "agent",
+            message: `Agent calling tool: search`,
+            level: 1,
+            auxiliary: {
+                arguments: {
+                    value: JSON.stringify({ query }),
+                    type: "object",
+                },
+            },
+        });
+        const result = await performBrowserbaseSearch(v3, query, apiKey);
+        v3.recordAgentReplayStep({
+            type: "search",
+            instruction: query,
+            playwrightArguments: { query },
+            message: result.error ?? `Found ${result.results.length} results`,
+        });
+        return { ...result, timestamp: Date.now() };
+    },
+});
+exports.searchTool = searchTool;
+//# sourceMappingURL=browserbaseSearch.js.map

package/dist/cjs/lib/v3/agent/tools/browserbaseSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserbaseSearch.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/browserbaseSearch.ts"],"names":[],"mappings":";;;AAAA,2BAA0B;AAC1B,6BAAwB;AAmBxB,KAAK,UAAU,wBAAwB,CACrC,EAAM,EACN,KAAa,EACb,MAAc,EACd,aAAqB,CAAC;IAEtB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,uCAAuC,EAAE;YACpE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,cAAc,EAAE,MAAM;aACvB;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;SAC5C,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO;gBACL,OAAO,EAAE,EAAE;gBACX,KAAK,EAAE,iCAAiC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE;aACjF,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAC;QAC/D,MAAM,OAAO,GAAmB,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CACvD,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC;YAClC,KAAK,EAAE,KAAK;YACZ,GAAG,EAAE,GAAG;YACR,GAAG,CAAC,aAAa,IAAI,EAAE,aAAa,EAAE,CAAC;SACxC,CAAC,CACH,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC;YACR,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,iBAAkB,KAAe,CAAC,OAAO,EAAE;YACpD,KAAK,EAAE,CAAC;SACT,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,4BAA6B,KAAe,CAAC,OAAO,EAAE;SAC9D,CAAC;IACJ,CAAC;AACH,CAAC;AAEM,MAAM,UAAU,GAAG,CAAC,EAAM,EAAE,MAAc,EAAE,EAAE,CACnD,IAAA,SAAI,EAAC;IACH,WAAW,EACT,wSAAwS;IAC1S,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC;QACpB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;KACtE,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,EAAE,CAAC,MAAM,CAAC;YACR,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,4BAA4B;YACrC,KAAK,EAAE,CAAC;YACR,SAAS,EAAE;gBACT,SAAS,EAAE;oBACT,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;oBAChC,IAAI,EAAE,QAAQ;iBACf;aACF;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAEjE,EAAE,CAAC,qBAAqB,CAAC;YACvB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,KAAK;YAClB,mBAAmB,EAAE,EAAE,KAAK,EAAE;YAC9B,OAAO,EAAE,MAAM,CAAC,KAAK,IAAI,SAAS,MAAM,CAAC,OAAO,CAAC,MAAM,UAAU;SAClE,CAAC,CAAC;QAEH,OAAO,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC9C,CAAC;CACF,CAAC,CAAC;AA/BQ,QAAA,UAAU,cA+BlB","sourcesContent":["import { tool } from \"ai\";\nimport { z } from \"zod\";\nimport type { V3 } from \"../../v3.js\";\n\nexport interface SearchResult {\n  title: string;\n  url: string;\n  publishedDate?: string;\n}\n\ninterface BrowserbaseRawResult {\n  title?: string;\n  url?: string;\n  publishedDate?: string;\n}\n\ninterface BrowserbaseApiResponse {\n  results?: BrowserbaseRawResult[];\n}\n\nasync function performBrowserbaseSearch(\n  v3: V3,\n  query: string,\n  apiKey: string,\n  numResults: number = 5,\n): Promise<{ results: SearchResult[]; error?: string }> {\n  try {\n    const response = await fetch(\"https://api.browserbase.com/v1/search\", {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        \"x-bb-api-key\": apiKey,\n      },\n      body: JSON.stringify({ query, numResults }),\n    });\n\n    if (!response.ok) {\n      return {\n        results: [],\n        error: `Browserbase Search API error: ${response.status} ${response.statusText}`,\n      };\n    }\n\n    const data = (await response.json()) as BrowserbaseApiResponse;\n    const results: SearchResult[] = (data?.results ?? []).map(\n      ({ title, url, publishedDate }) => ({\n        title: title,\n        url: url,\n        ...(publishedDate && { publishedDate }),\n      }),\n    );\n\n    return { results };\n  } catch (error) {\n    v3.logger({\n      category: \"agent\",\n      message: `Search error: ${(error as Error).message}`,\n      level: 0,\n    });\n    return {\n      results: [],\n      error: `Error performing search: ${(error as Error).message}`,\n    };\n  }\n}\n\nexport const searchTool = (v3: V3, apiKey: string) =>\n  tool({\n    description:\n      \"Perform a web search and returns results. Use this tool when you need information from the web or when you are unsure of the exact URL you want to navigate to. This can be used to find the ideal entry point, resulting in a task that is easier to complete due to starting further in the process.\",\n    inputSchema: z.object({\n      query: z.string().describe(\"The search query to look for on the web\"),\n    }),\n    execute: async ({ query }) => {\n      v3.logger({\n        category: \"agent\",\n        message: `Agent calling tool: search`,\n        level: 1,\n        auxiliary: {\n          arguments: {\n            value: JSON.stringify({ query }),\n            type: \"object\",\n          },\n        },\n      });\n\n      const result = await performBrowserbaseSearch(v3, query, apiKey);\n\n      v3.recordAgentReplayStep({\n        type: \"search\",\n        instruction: query,\n        playwrightArguments: { query },\n        message: result.error ?? `Found ${result.results.length} results`,\n      });\n\n      return { ...result, timestamp: Date.now() };\n    },\n  });\n"]}

package/dist/cjs/lib/v3/agent/tools/index.d.ts

@@ -14,7 +14,8 @@ import { clickAndHoldTool } from "./clickAndHold.js";
 import { keysTool } from "./keys.js";
 import { fillFormVisionTool } from "./fillFormVision.js";
 import { thinkTool } from "./think.js";
-import { searchTool } from "./search.js";
+import { searchTool as browserbaseSearchTool } from "./browserbaseSearch.js";
+import { searchTool as braveSearchTool } from "./braveSearch.js";
 import type { ToolSet, InferUITools } from "ai";
 import type { V3 } from "../../v3.js";
 import type { LogLine } from "../../types/public/logs.js";
@@ -47,12 +48,22 @@ export interface V3AgentToolOptions {
      * Forwarded to the underlying v3 call's `timeout` option.
      */
     toolTimeout?: number;
+    /**
+     * Whether to enable the Browserbase-powered web search tool.
+     * Requires a valid Browserbase API key.
+     */
+    useSearch?: boolean;
+    /**
+     * The Browserbase API key used for the search tool.
+     * Resolved from BROWSERBASE_API_KEY env var or the Stagehand constructor.
+     */
+    browserbaseApiKey?: string;
 }
 export declare function createAgentTools(v3: V3, options?: V3AgentToolOptions): ToolSet;
 export type AgentTools = ReturnType<typeof createAgentTools>;
 /**
  * Type map of all agent tools for strong typing of tool calls and results.
- * Note: `search` is optional as it's only available when BRAVE_API_KEY is configured.
+ * Note: `search` is optional — enabled via useSearch: true (Browserbase) or BRAVE_API_KEY env var (legacy).
  */
 export type AgentToolTypesMap = {
     act: ReturnType<typeof actTool>;
@@ -68,7 +79,7 @@ export type AgentToolTypesMap = {
     navback: ReturnType<typeof navBackTool>;
     screenshot: ReturnType<typeof screenshotTool>;
     scroll: ReturnType<typeof scrollTool> | ReturnType<typeof scrollVisionTool>;
-    search?: ReturnType<typeof searchTool>;
+    search?: ReturnType<typeof browserbaseSearchTool> | ReturnType<typeof braveSearchTool>;
     think: ReturnType<typeof thinkTool>;
     type: ReturnType<typeof typeTool>;
     wait: ReturnType<typeof waitTool>;

package/dist/cjs/lib/v3/agent/tools/index.js

@@ -17,7 +17,8 @@ const clickAndHold_js_1 = require("./clickAndHold.js");
 const keys_js_1 = require("./keys.js");
 const fillFormVision_js_1 = require("./fillFormVision.js");
 const think_js_1 = require("./think.js");
-const search_js_1 = require("./search.js");
+const browserbaseSearch_js_1 = require("./browserbaseSearch.js");
+const braveSearch_js_1 = require("./braveSearch.js");
 /**
  * Filters tools based on mode and explicit exclusions.
  * - 'dom' mode: Removes coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)
@@ -70,8 +71,11 @@ function createAgentTools(v3, options) {
         type: (0, type_js_1.typeTool)(v3, provider, variables),
         wait: (0, wait_js_1.waitTool)(v3, mode),
     };
-    if (process.env.BRAVE_API_KEY) {
-        allTools.search = (0, search_js_1.searchTool)(v3);
+    if (options?.useSearch && options.browserbaseApiKey) {
+        allTools.search = (0, browserbaseSearch_js_1.searchTool)(v3, options.browserbaseApiKey);
+    }
+    else if (process.env.BRAVE_API_KEY) {
+        allTools.search = (0, braveSearch_js_1.searchTool)(v3);
     }
     return filterTools(allTools, mode, excludeTools);
 }

package/dist/cjs/lib/v3/agent/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/index.ts"],"names":[],"mappings":";;AA2FA,4CAgCC;AA3HD,uCAAqC;AACrC,qCAAmC;AACnC,mDAAiD;AACjD,uCAAqC;AACrC,6CAA2C;AAC3C,+CAA6C;AAC7C,+CAA6C;AAC7C,2CAA2D;AAC3D,6CAA2C;AAC3C,yCAAuC;AACvC,uCAAqC;AACrC,qDAAmD;AACnD,uDAAqD;AACrD,uCAAqC;AACrC,2DAAyD;AACzD,yCAAuC;AACvC,2CAAyC;AAyCzC;;;;;GAKG;AACH,SAAS,WAAW,CAClB,KAAc,EACd,IAAmB,EACnB,YAAuB;IAEvB,MAAM,QAAQ,GAAY,EAAE,GAAG,KAAK,EAAE,CAAC;IAEvC,uBAAuB;IACvB,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC,QAAQ,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,qBAAqB;QACrB,OAAO,QAAQ,CAAC,KAAK,CAAC;QACtB,OAAO,QAAQ,CAAC,IAAI,CAAC;QACrB,OAAO,QAAQ,CAAC,WAAW,CAAC;QAC5B,OAAO,QAAQ,CAAC,YAAY,CAAC;QAC7B,OAAO,QAAQ,CAAC,cAAc,CAAC;IACjC,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;YACpC,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAgB,gBAAgB,CAAC,EAAM,EAAE,OAA4B;IACnE,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,CAAC;IAC/C,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,KAAK,CAAC;IACpC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC;IACnC,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;IAC3C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;IACrC,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;IAEzC,MAAM,QAAQ,GAAY;QACxB,GAAG,EAAE,IAAA,gBAAO,EAAC,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,CAAC;QACxD,QAAQ,EAAE,IAAA,0BAAY,EAAC,EAAE,EAAE,WAAW,CAAC;QACvC,KAAK,EAAE,IAAA,oBAAS,EAAC,EAAE,EAAE,QAAQ,CAAC;QAC9B,YAAY,EAAE,IAAA,kCAAgB,EAAC,EAAE,EAAE,QAAQ,CAAC;QAC5C,WAAW,EAAE,IAAA,gCAAe,EAAC,EAAE,EAAE,QAAQ,CAAC;QAC1C,OAAO,EAAE,IAAA,wBAAW,EAAC,EAAE,EAAE,cAAc,EAAE,WAAW,CAAC;QACrD,QAAQ,EAAE,IAAA,0BAAY,EAAC,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,CAAC;QAClE,cAAc,EAAE,IAAA,sCAAkB,EAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC;QAC3D,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,CAAC;QAClB,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,CAAC;QAClB,OAAO,EAAE,IAAA,wBAAW,EAAC,EAAE,CAAC;QACxB,UAAU,EAAE,IAAA,8BAAc,EAAC,EAAE,CAAC;QAC9B,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAA,4BAAgB,EAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAA,sBAAU,EAAC,EAAE,CAAC;QAC3E,KAAK,EAAE,IAAA,oBAAS,GAAE;QAClB,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC;QACvC,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,EAAE,IAAI,CAAC;KACzB,CAAC;IAEF,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QAC9B,QAAQ,CAAC,MAAM,GAAG,IAAA,sBAAU,EAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC","sourcesContent":["import { gotoTool } from \"./goto.js\";\nimport { actTool } from \"./act.js\";\nimport { screenshotTool } from \"./screenshot.js\";\nimport { waitTool } from \"./wait.js\";\nimport { navBackTool } from \"./navback.js\";\nimport { ariaTreeTool } from \"./ariaTree.js\";\nimport { fillFormTool } from \"./fillform.js\";\nimport { scrollTool, scrollVisionTool } from \"./scroll.js\";\nimport { extractTool } from \"./extract.js\";\nimport { clickTool } from \"./click.js\";\nimport { typeTool } from \"./type.js\";\nimport { dragAndDropTool } from \"./dragAndDrop.js\";\nimport { clickAndHoldTool } from \"./clickAndHold.js\";\nimport { keysTool } from \"./keys.js\";\nimport { fillFormVisionTool } from \"./fillFormVision.js\";\nimport { thinkTool } from \"./think.js\";\nimport { searchTool } from \"./search.js\";\n\nimport type { ToolSet, InferUITools } from \"ai\";\nimport type { V3 } from \"../../v3.js\";\nimport type { LogLine } from \"../../types/public/logs.js\";\nimport type {\n  AgentToolMode,\n  AgentModelConfig,\n  Variables,\n} from \"../../types/public/agent.js\";\n\nexport interface V3AgentToolOptions {\n  executionModel?: string | AgentModelConfig;\n  logger?: (message: LogLine) => void;\n  /**\n   * Tool mode determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) - removes coordinate-based tools\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - removes fillForm\n   */\n  mode?: AgentToolMode;\n  /**\n   * The model provider. Used for model-specific coordinate handling\n   */\n  provider?: string;\n  /**\n   * Tools to exclude from the available toolset.\n   * These tools will be filtered out after mode-based filtering.\n   */\n  excludeTools?: string[];\n  /**\n   * Variables available to the agent for use in act/type tools.\n   * When provided, these tools will have an optional useVariable field.\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for tool calls that invoke v3 methods (act, extract, fillForm, ariaTree).\n   * Forwarded to the underlying v3 call's `timeout` option.\n   */\n  toolTimeout?: number;\n}\n\n/**\n * Filters tools based on mode and explicit exclusions.\n * - 'dom' mode: Removes coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n * - 'hybrid' mode: Removes DOM-based form tool (fillForm) in favor of coordinate-based fillFormVision\n * - excludeTools: Additional tools to remove from the toolset\n */\nfunction filterTools(\n  tools: ToolSet,\n  mode: AgentToolMode,\n  excludeTools?: string[],\n): ToolSet {\n  const filtered: ToolSet = { ...tools };\n\n  // Mode-based filtering\n  if (mode === \"hybrid\") {\n    delete filtered.fillForm;\n  } else {\n    // DOM mode (default)\n    delete filtered.click;\n    delete filtered.type;\n    delete filtered.dragAndDrop;\n    delete filtered.clickAndHold;\n    delete filtered.fillFormVision;\n  }\n\n  if (excludeTools) {\n    for (const toolName of excludeTools) {\n      delete filtered[toolName];\n    }\n  }\n\n  return filtered;\n}\n\nexport function createAgentTools(v3: V3, options?: V3AgentToolOptions) {\n  const executionModel = options?.executionModel;\n  const mode = options?.mode ?? \"dom\";\n  const provider = options?.provider;\n  const excludeTools = options?.excludeTools;\n  const variables = options?.variables;\n  const toolTimeout = options?.toolTimeout;\n\n  const allTools: ToolSet = {\n    act: actTool(v3, executionModel, variables, toolTimeout),\n    ariaTree: ariaTreeTool(v3, toolTimeout),\n    click: clickTool(v3, provider),\n    clickAndHold: clickAndHoldTool(v3, provider),\n    dragAndDrop: dragAndDropTool(v3, provider),\n    extract: extractTool(v3, executionModel, toolTimeout),\n    fillForm: fillFormTool(v3, executionModel, variables, toolTimeout),\n    fillFormVision: fillFormVisionTool(v3, provider, variables),\n    goto: gotoTool(v3),\n    keys: keysTool(v3),\n    navback: navBackTool(v3),\n    screenshot: screenshotTool(v3),\n    scroll: mode === \"hybrid\" ? scrollVisionTool(v3, provider) : scrollTool(v3),\n    think: thinkTool(),\n    type: typeTool(v3, provider, variables),\n    wait: waitTool(v3, mode),\n  };\n\n  if (process.env.BRAVE_API_KEY) {\n    allTools.search = searchTool(v3);\n  }\n\n  return filterTools(allTools, mode, excludeTools);\n}\n\nexport type AgentTools = ReturnType<typeof createAgentTools>;\n\n/**\n * Type map of all agent tools for strong typing of tool calls and results.\n * Note: `search` is optional as it's only available when BRAVE_API_KEY is configured.\n */\nexport type AgentToolTypesMap = {\n  act: ReturnType<typeof actTool>;\n  ariaTree: ReturnType<typeof ariaTreeTool>;\n  click: ReturnType<typeof clickTool>;\n  clickAndHold: ReturnType<typeof clickAndHoldTool>;\n  dragAndDrop: ReturnType<typeof dragAndDropTool>;\n  extract: ReturnType<typeof extractTool>;\n  fillForm: ReturnType<typeof fillFormTool>;\n  fillFormVision: ReturnType<typeof fillFormVisionTool>;\n  goto: ReturnType<typeof gotoTool>;\n  keys: ReturnType<typeof keysTool>;\n  navback: ReturnType<typeof navBackTool>;\n  screenshot: ReturnType<typeof screenshotTool>;\n  scroll: ReturnType<typeof scrollTool> | ReturnType<typeof scrollVisionTool>;\n  search?: ReturnType<typeof searchTool>;\n  think: ReturnType<typeof thinkTool>;\n  type: ReturnType<typeof typeTool>;\n  wait: ReturnType<typeof waitTool>;\n};\n\n/**\n * Inferred UI tools type for type-safe tool inputs and outputs.\n * Use with UIMessage for full type safety in UI contexts.\n */\nexport type AgentUITools = InferUITools<AgentToolTypesMap>;\n\n/**\n * Union type for all possible agent tool calls.\n * Provides type-safe access to tool call arguments.\n */\nexport type AgentToolCall = {\n  [K in keyof AgentToolTypesMap]: {\n    toolName: K;\n    toolCallId: string;\n    args: AgentUITools[K][\"input\"];\n  };\n}[keyof AgentToolTypesMap];\n\n/**\n * Union type for all possible agent tool results.\n * Provides type-safe access to tool result values.\n */\nexport type AgentToolResult = {\n  [K in keyof AgentToolTypesMap]: {\n    toolName: K;\n    toolCallId: string;\n    result: AgentUITools[K][\"output\"];\n  };\n}[keyof AgentToolTypesMap];\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/index.ts"],"names":[],"mappings":";;AAsGA,4CAkCC;AAxID,uCAAqC;AACrC,qCAAmC;AACnC,mDAAiD;AACjD,uCAAqC;AACrC,6CAA2C;AAC3C,+CAA6C;AAC7C,+CAA6C;AAC7C,2CAA2D;AAC3D,6CAA2C;AAC3C,yCAAuC;AACvC,uCAAqC;AACrC,qDAAmD;AACnD,uDAAqD;AACrD,uCAAqC;AACrC,2DAAyD;AACzD,yCAAuC;AACvC,iEAA6E;AAC7E,qDAAiE;AAmDjE;;;;;GAKG;AACH,SAAS,WAAW,CAClB,KAAc,EACd,IAAmB,EACnB,YAAuB;IAEvB,MAAM,QAAQ,GAAY,EAAE,GAAG,KAAK,EAAE,CAAC;IAEvC,uBAAuB;IACvB,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC,QAAQ,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,qBAAqB;QACrB,OAAO,QAAQ,CAAC,KAAK,CAAC;QACtB,OAAO,QAAQ,CAAC,IAAI,CAAC;QACrB,OAAO,QAAQ,CAAC,WAAW,CAAC;QAC5B,OAAO,QAAQ,CAAC,YAAY,CAAC;QAC7B,OAAO,QAAQ,CAAC,cAAc,CAAC;IACjC,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;YACpC,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAgB,gBAAgB,CAAC,EAAM,EAAE,OAA4B;IACnE,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,CAAC;IAC/C,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,KAAK,CAAC;IACpC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC;IACnC,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;IAC3C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;IACrC,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;IAEzC,MAAM,QAAQ,GAAY;QACxB,GAAG,EAAE,IAAA,gBAAO,EAAC,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,CAAC;QACxD,QAAQ,EAAE,IAAA,0BAAY,EAAC,EAAE,EAAE,WAAW,CAAC;QACvC,KAAK,EAAE,IAAA,oBAAS,EAAC,EAAE,EAAE,QAAQ,CAAC;QAC9B,YAAY,EAAE,IAAA,kCAAgB,EAAC,EAAE,EAAE,QAAQ,CAAC;QAC5C,WAAW,EAAE,IAAA,gCAAe,EAAC,EAAE,EAAE,QAAQ,CAAC;QAC1C,OAAO,EAAE,IAAA,wBAAW,EAAC,EAAE,EAAE,cAAc,EAAE,WAAW,CAAC;QACrD,QAAQ,EAAE,IAAA,0BAAY,EAAC,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,CAAC;QAClE,cAAc,EAAE,IAAA,sCAAkB,EAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC;QAC3D,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,CAAC;QAClB,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,CAAC;QAClB,OAAO,EAAE,IAAA,wBAAW,EAAC,EAAE,CAAC;QACxB,UAAU,EAAE,IAAA,8BAAc,EAAC,EAAE,CAAC;QAC9B,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAA,4BAAgB,EAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAA,sBAAU,EAAC,EAAE,CAAC;QAC3E,KAAK,EAAE,IAAA,oBAAS,GAAE;QAClB,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC;QACvC,IAAI,EAAE,IAAA,kBAAQ,EAAC,EAAE,EAAE,IAAI,CAAC;KACzB,CAAC;IAEF,IAAI,OAAO,EAAE,SAAS,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;QACpD,QAAQ,CAAC,MAAM,GAAG,IAAA,iCAAqB,EAAC,EAAE,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzE,CAAC;SAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QACrC,QAAQ,CAAC,MAAM,GAAG,IAAA,2BAAe,EAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC","sourcesContent":["import { gotoTool } from \"./goto.js\";\nimport { actTool } from \"./act.js\";\nimport { screenshotTool } from \"./screenshot.js\";\nimport { waitTool } from \"./wait.js\";\nimport { navBackTool } from \"./navback.js\";\nimport { ariaTreeTool } from \"./ariaTree.js\";\nimport { fillFormTool } from \"./fillform.js\";\nimport { scrollTool, scrollVisionTool } from \"./scroll.js\";\nimport { extractTool } from \"./extract.js\";\nimport { clickTool } from \"./click.js\";\nimport { typeTool } from \"./type.js\";\nimport { dragAndDropTool } from \"./dragAndDrop.js\";\nimport { clickAndHoldTool } from \"./clickAndHold.js\";\nimport { keysTool } from \"./keys.js\";\nimport { fillFormVisionTool } from \"./fillFormVision.js\";\nimport { thinkTool } from \"./think.js\";\nimport { searchTool as browserbaseSearchTool } from \"./browserbaseSearch.js\";\nimport { searchTool as braveSearchTool } from \"./braveSearch.js\";\n\nimport type { ToolSet, InferUITools } from \"ai\";\nimport type { V3 } from \"../../v3.js\";\nimport type { LogLine } from \"../../types/public/logs.js\";\nimport type {\n  AgentToolMode,\n  AgentModelConfig,\n  Variables,\n} from \"../../types/public/agent.js\";\n\nexport interface V3AgentToolOptions {\n  executionModel?: string | AgentModelConfig;\n  logger?: (message: LogLine) => void;\n  /**\n   * Tool mode determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) - removes coordinate-based tools\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - removes fillForm\n   */\n  mode?: AgentToolMode;\n  /**\n   * The model provider. Used for model-specific coordinate handling\n   */\n  provider?: string;\n  /**\n   * Tools to exclude from the available toolset.\n   * These tools will be filtered out after mode-based filtering.\n   */\n  excludeTools?: string[];\n  /**\n   * Variables available to the agent for use in act/type tools.\n   * When provided, these tools will have an optional useVariable field.\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for tool calls that invoke v3 methods (act, extract, fillForm, ariaTree).\n   * Forwarded to the underlying v3 call's `timeout` option.\n   */\n  toolTimeout?: number;\n  /**\n   * Whether to enable the Browserbase-powered web search tool.\n   * Requires a valid Browserbase API key.\n   */\n  useSearch?: boolean;\n  /**\n   * The Browserbase API key used for the search tool.\n   * Resolved from BROWSERBASE_API_KEY env var or the Stagehand constructor.\n   */\n  browserbaseApiKey?: string;\n}\n\n/**\n * Filters tools based on mode and explicit exclusions.\n * - 'dom' mode: Removes coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n * - 'hybrid' mode: Removes DOM-based form tool (fillForm) in favor of coordinate-based fillFormVision\n * - excludeTools: Additional tools to remove from the toolset\n */\nfunction filterTools(\n  tools: ToolSet,\n  mode: AgentToolMode,\n  excludeTools?: string[],\n): ToolSet {\n  const filtered: ToolSet = { ...tools };\n\n  // Mode-based filtering\n  if (mode === \"hybrid\") {\n    delete filtered.fillForm;\n  } else {\n    // DOM mode (default)\n    delete filtered.click;\n    delete filtered.type;\n    delete filtered.dragAndDrop;\n    delete filtered.clickAndHold;\n    delete filtered.fillFormVision;\n  }\n\n  if (excludeTools) {\n    for (const toolName of excludeTools) {\n      delete filtered[toolName];\n    }\n  }\n\n  return filtered;\n}\n\nexport function createAgentTools(v3: V3, options?: V3AgentToolOptions) {\n  const executionModel = options?.executionModel;\n  const mode = options?.mode ?? \"dom\";\n  const provider = options?.provider;\n  const excludeTools = options?.excludeTools;\n  const variables = options?.variables;\n  const toolTimeout = options?.toolTimeout;\n\n  const allTools: ToolSet = {\n    act: actTool(v3, executionModel, variables, toolTimeout),\n    ariaTree: ariaTreeTool(v3, toolTimeout),\n    click: clickTool(v3, provider),\n    clickAndHold: clickAndHoldTool(v3, provider),\n    dragAndDrop: dragAndDropTool(v3, provider),\n    extract: extractTool(v3, executionModel, toolTimeout),\n    fillForm: fillFormTool(v3, executionModel, variables, toolTimeout),\n    fillFormVision: fillFormVisionTool(v3, provider, variables),\n    goto: gotoTool(v3),\n    keys: keysTool(v3),\n    navback: navBackTool(v3),\n    screenshot: screenshotTool(v3),\n    scroll: mode === \"hybrid\" ? scrollVisionTool(v3, provider) : scrollTool(v3),\n    think: thinkTool(),\n    type: typeTool(v3, provider, variables),\n    wait: waitTool(v3, mode),\n  };\n\n  if (options?.useSearch && options.browserbaseApiKey) {\n    allTools.search = browserbaseSearchTool(v3, options.browserbaseApiKey);\n  } else if (process.env.BRAVE_API_KEY) {\n    allTools.search = braveSearchTool(v3);\n  }\n\n  return filterTools(allTools, mode, excludeTools);\n}\n\nexport type AgentTools = ReturnType<typeof createAgentTools>;\n\n/**\n * Type map of all agent tools for strong typing of tool calls and results.\n * Note: `search` is optional — enabled via useSearch: true (Browserbase) or BRAVE_API_KEY env var (legacy).\n */\nexport type AgentToolTypesMap = {\n  act: ReturnType<typeof actTool>;\n  ariaTree: ReturnType<typeof ariaTreeTool>;\n  click: ReturnType<typeof clickTool>;\n  clickAndHold: ReturnType<typeof clickAndHoldTool>;\n  dragAndDrop: ReturnType<typeof dragAndDropTool>;\n  extract: ReturnType<typeof extractTool>;\n  fillForm: ReturnType<typeof fillFormTool>;\n  fillFormVision: ReturnType<typeof fillFormVisionTool>;\n  goto: ReturnType<typeof gotoTool>;\n  keys: ReturnType<typeof keysTool>;\n  navback: ReturnType<typeof navBackTool>;\n  screenshot: ReturnType<typeof screenshotTool>;\n  scroll: ReturnType<typeof scrollTool> | ReturnType<typeof scrollVisionTool>;\n  search?:\n    | ReturnType<typeof browserbaseSearchTool>\n    | ReturnType<typeof braveSearchTool>;\n  think: ReturnType<typeof thinkTool>;\n  type: ReturnType<typeof typeTool>;\n  wait: ReturnType<typeof waitTool>;\n};\n\n/**\n * Inferred UI tools type for type-safe tool inputs and outputs.\n * Use with UIMessage for full type safety in UI contexts.\n */\nexport type AgentUITools = InferUITools<AgentToolTypesMap>;\n\n/**\n * Union type for all possible agent tool calls.\n * Provides type-safe access to tool call arguments.\n */\nexport type AgentToolCall = {\n  [K in keyof AgentToolTypesMap]: {\n    toolName: K;\n    toolCallId: string;\n    args: AgentUITools[K][\"input\"];\n  };\n}[keyof AgentToolTypesMap];\n\n/**\n * Union type for all possible agent tool results.\n * Provides type-safe access to tool result values.\n */\nexport type AgentToolResult = {\n  [K in keyof AgentToolTypesMap]: {\n    toolName: K;\n    toolCallId: string;\n    result: AgentUITools[K][\"output\"];\n  };\n}[keyof AgentToolTypesMap];\n"]}

package/dist/cjs/lib/v3/handlers/v3AgentHandler.js

@@ -65,8 +65,15 @@ class V3AgentHandler {
                 isBrowserbase: this.v3.isBrowserbase,
                 excludeTools: options.excludeTools,
                 variables: options.variables,
+                useSearch: options.useSearch,
             });
-            const tools = this.createTools(options.excludeTools, options.variables, options.toolTimeout);
+            if (options.useSearch) {
+                const bbApiKey = this.v3.browserbaseApiKey;
+                if (!bbApiKey) {
+                    throw new sdkErrors_js_1.MissingEnvironmentVariableError("BROWSERBASE_API_KEY", "agent search (useSearch: true)");
+                }
+            }
+            const tools = this.createTools(options.excludeTools, options.variables, options.toolTimeout, options.useSearch);
             const allTools = { ...tools, ...this.mcpTools };
             // Use provided messages for continuation, or start fresh with the instruction
             const messages = options.messages?.length
@@ -239,7 +246,8 @@ class V3AgentHandler {
         }
         catch (error) {
             // Re-throw validation errors that should propagate to the caller
-            if (error instanceof sdkErrors_js_1.StreamingCallbacksInNonStreamingModeError) {
+            if (error instanceof sdkErrors_js_1.StreamingCallbacksInNonStreamingModeError ||
+                error instanceof sdkErrors_js_1.MissingEnvironmentVariableError) {
                 throw error;
             }
             // Re-throw abort errors wrapped in AgentAbortError for consistent error typing
@@ -382,7 +390,7 @@ class V3AgentHandler {
             messages: inputMessages,
         };
     }
-    createTools(excludeTools, variables, toolTimeout) {
+    createTools(excludeTools, variables, toolTimeout, useSearch) {
         const provider = this.llmClient?.getLanguageModel?.()?.provider;
         return (0, index_js_1.createAgentTools)(this.v3, {
             executionModel: this.executionModel,
@@ -392,6 +400,8 @@ class V3AgentHandler {
             excludeTools,
             variables,
             toolTimeout,
+            useSearch,
+            browserbaseApiKey: useSearch ? this.v3.browserbaseApiKey : undefined,
         });
     }
     handleStop(result, maxSteps) {

package/dist/cjs/lib/v3/handlers/v3AgentHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"v3AgentHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/v3AgentHandler.ts"],"names":[],"mappings":"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","sourcesContent":["import { createAgentTools } from \"../agent/tools/index.js\";\nimport { buildAgentSystemPrompt } from \"../agent/prompts/agentSystemPrompt.js\";\nimport { LogLine } from \"../types/public/logs.js\";\nimport { V3 } from \"../v3.js\";\nimport {\n  ModelMessage,\n  ToolSet,\n  wrapLanguageModel,\n  stepCountIs,\n  LanguageModel,\n  type LanguageModelUsage,\n  type StepResult,\n  type GenerateTextOnStepFinishCallback,\n  type StreamTextOnStepFinishCallback,\n  type PrepareStepFunction,\n} from \"ai\";\nimport { StagehandZodObject } from \"../zodCompat.js\";\nimport { processMessages } from \"../agent/utils/messageProcessing.js\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport { SessionFileLogger } from \"../flowLogger.js\";\nimport {\n  AgentExecuteOptions,\n  AgentStreamExecuteOptions,\n  AgentExecuteOptionsBase,\n  AgentResult,\n  AgentContext,\n  AgentState,\n  AgentStreamResult,\n  AgentStreamCallbacks,\n  AgentToolMode,\n  AgentModelConfig,\n  Variables,\n} from \"../types/public/agent.js\";\nimport { V3FunctionName } from \"../types/public/methods.js\";\nimport { mapToolResultToActions } from \"../agent/utils/actionMapping.js\";\nimport {\n  MissingLLMConfigurationError,\n  StreamingCallbacksInNonStreamingModeError,\n  AgentAbortError,\n} from \"../types/public/sdkErrors.js\";\nimport { handleDoneToolCall } from \"../agent/utils/handleDoneToolCall.js\";\n\nfunction getErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/**\n * Prepends a system message with cache control to the messages array.\n * The cache control providerOptions are used by Anthropic and ignored by other providers.\n */\nfunction prependSystemMessage(\n  systemPrompt: string,\n  messages: ModelMessage[],\n): ModelMessage[] {\n  return [\n    {\n      role: \"system\",\n      content: systemPrompt,\n      providerOptions: {\n        anthropic: {\n          cacheControl: { type: \"ephemeral\" },\n        },\n      },\n    },\n    ...messages,\n  ];\n}\n\nexport class V3AgentHandler {\n  private v3: V3;\n  private logger: (message: LogLine) => void;\n  private llmClient: LLMClient;\n  private executionModel?: string | AgentModelConfig;\n  private systemInstructions?: string;\n  private mcpTools?: ToolSet;\n  private mode: AgentToolMode;\n\n  constructor(\n    v3: V3,\n    logger: (message: LogLine) => void,\n    llmClient: LLMClient,\n    executionModel?: string | AgentModelConfig,\n    systemInstructions?: string,\n    mcpTools?: ToolSet,\n    mode?: AgentToolMode,\n  ) {\n    this.v3 = v3;\n    this.logger = logger;\n    this.llmClient = llmClient;\n    this.executionModel = executionModel;\n    this.systemInstructions = systemInstructions;\n    this.mcpTools = mcpTools;\n    this.mode = mode ?? \"dom\";\n  }\n\n  private async prepareAgent(\n    instructionOrOptions: string | AgentExecuteOptionsBase,\n  ): Promise<AgentContext> {\n    try {\n      const options =\n        typeof instructionOrOptions === \"string\"\n          ? { instruction: instructionOrOptions }\n          : instructionOrOptions;\n\n      const maxSteps = options.maxSteps || 20;\n\n      // Get the initial page URL first (needed for the system prompt)\n      const initialPageUrl = (await this.v3.context.awaitActivePage()).url();\n\n      // Build the system prompt with mode-aware tool guidance\n      const systemPrompt = buildAgentSystemPrompt({\n        url: initialPageUrl,\n        executionInstruction: options.instruction,\n        mode: this.mode,\n        systemInstructions: this.systemInstructions,\n        isBrowserbase: this.v3.isBrowserbase,\n        excludeTools: options.excludeTools,\n        variables: options.variables,\n      });\n\n      const tools = this.createTools(\n        options.excludeTools,\n        options.variables,\n        options.toolTimeout,\n      );\n      const allTools: ToolSet = { ...tools, ...this.mcpTools };\n\n      // Use provided messages for continuation, or start fresh with the instruction\n      const messages: ModelMessage[] = options.messages?.length\n        ? [...options.messages, { role: \"user\", content: options.instruction }]\n        : [{ role: \"user\", content: options.instruction }];\n\n      if (!this.llmClient?.getLanguageModel) {\n        throw new MissingLLMConfigurationError();\n      }\n      const baseModel = this.llmClient.getLanguageModel();\n      //to do - we likely do not need middleware anymore\n      const wrappedModel = wrapLanguageModel({\n        model: baseModel,\n        middleware: {\n          ...SessionFileLogger.createLlmLoggingMiddleware(baseModel.modelId),\n        },\n      });\n\n      if (\n        this.mode === \"hybrid\" &&\n        !baseModel.modelId.includes(\"gemini-3-flash\") &&\n        !baseModel.modelId.includes(\"claude\")\n      ) {\n        this.logger({\n          category: \"agent\",\n          message: `Warning: \"${baseModel.modelId}\" may not perform well in hybrid mode. See recommended models: https://docs.stagehand.dev/v3/basics/agent#hybrid-mode`,\n          level: 0,\n        });\n      }\n\n      return {\n        options,\n        maxSteps,\n        systemPrompt,\n        allTools,\n        messages,\n        wrappedModel,\n        initialPageUrl,\n      };\n    } catch (error) {\n      this.logger({\n        category: \"agent\",\n        message: `failed to prepare agent: ${error}`,\n        level: 0,\n      });\n      throw error;\n    }\n  }\n  private createPrepareStep(\n    userCallback?: PrepareStepFunction<ToolSet>,\n  ): PrepareStepFunction<ToolSet> {\n    return async (options) => {\n      processMessages(options.messages);\n      if (userCallback) {\n        return userCallback(options);\n      }\n      return options;\n    };\n  }\n\n  private createStepHandler(\n    state: AgentState,\n    userCallback?:\n      | GenerateTextOnStepFinishCallback<ToolSet>\n      | StreamTextOnStepFinishCallback<ToolSet>,\n  ) {\n    return async (event: StepResult<ToolSet>) => {\n      this.logger({\n        category: \"agent\",\n        message: `Step finished: ${event.finishReason}`,\n        level: 2,\n      });\n\n      if (event.toolCalls && event.toolCalls.length > 0) {\n        for (let i = 0; i < event.toolCalls.length; i++) {\n          const toolCall = event.toolCalls[i];\n          const args = toolCall.input;\n          const toolResult = event.toolResults?.[i];\n\n          if (event.text && event.text.length > 0) {\n            state.collectedReasoning.push(event.text);\n            this.logger({\n              category: \"agent\",\n              message: `reasoning: ${event.text}`,\n              level: 1,\n            });\n          }\n\n          if (toolCall.toolName === \"done\") {\n            state.completed = true;\n            if (args?.taskComplete) {\n              const doneReasoning = args.reasoning;\n              const allReasoning = state.collectedReasoning.join(\" \");\n              state.finalMessage = doneReasoning\n                ? `${allReasoning} ${doneReasoning}`.trim()\n                : allReasoning || \"Task completed successfully\";\n            }\n          }\n          const mappedActions = mapToolResultToActions({\n            toolCallName: toolCall.toolName,\n            toolResult,\n            args,\n            reasoning: event.text || undefined,\n          });\n\n          for (const action of mappedActions) {\n            action.pageUrl = state.currentPageUrl;\n            action.timestamp = Date.now();\n            state.actions.push(action);\n          }\n        }\n        state.currentPageUrl = (await this.v3.context.awaitActivePage()).url();\n\n        // Capture screenshot after tool execution (only for evals)\n        if (process.env.EVALS === \"true\") {\n          try {\n            await this.captureAndEmitScreenshot();\n          } catch (e) {\n            this.logger({\n              category: \"agent\",\n              message: `Warning: Failed to capture screenshot: ${getErrorMessage(e)}`,\n              level: 1,\n            });\n          }\n        }\n      }\n\n      if (userCallback) {\n        await userCallback(event);\n      }\n    };\n  }\n\n  public async execute(\n    instructionOrOptions: string | AgentExecuteOptions,\n  ): Promise<AgentResult> {\n    const startTime = Date.now();\n    const options =\n      typeof instructionOrOptions === \"object\" ? instructionOrOptions : null;\n    const signal = options?.signal;\n\n    // Highlight cursor defaults to true for hybrid mode, can be overridden\n    const shouldHighlightCursor =\n      options?.highlightCursor ?? this.mode === \"hybrid\";\n\n    const state: AgentState = {\n      collectedReasoning: [],\n      actions: [],\n      finalMessage: \"\",\n      completed: false,\n      currentPageUrl: \"\",\n    };\n\n    let messages: ModelMessage[] = [];\n\n    try {\n      const {\n        options: preparedOptions,\n        maxSteps,\n        systemPrompt,\n        allTools,\n        messages: preparedMessages,\n        wrappedModel,\n        initialPageUrl,\n      } = await this.prepareAgent(instructionOrOptions);\n\n      // Enable cursor overlay for hybrid mode (coordinate-based interactions)\n      if (shouldHighlightCursor && this.mode === \"hybrid\") {\n        const page = await this.v3.context.awaitActivePage();\n        await page.enableCursorOverlay().catch(() => {});\n      }\n\n      messages = preparedMessages;\n      state.currentPageUrl = initialPageUrl;\n\n      const callbacks = (instructionOrOptions as AgentExecuteOptions).callbacks;\n\n      if (callbacks) {\n        const streamingOnlyCallbacks = [\n          \"onChunk\",\n          \"onFinish\",\n          \"onError\",\n          \"onAbort\",\n        ];\n        const invalidCallbacks = streamingOnlyCallbacks.filter(\n          (name) => callbacks[name as keyof typeof callbacks] != null,\n        );\n        if (invalidCallbacks.length > 0) {\n          throw new StreamingCallbacksInNonStreamingModeError(invalidCallbacks);\n        }\n      }\n\n      const result = await this.llmClient.generateText({\n        model: wrappedModel,\n        messages: prependSystemMessage(systemPrompt, messages),\n        tools: allTools,\n        stopWhen: (result) => this.handleStop(result, maxSteps),\n        temperature: 1,\n        toolChoice: \"auto\",\n\n        prepareStep: this.createPrepareStep(callbacks?.prepareStep),\n        onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),\n        abortSignal: preparedOptions.signal,\n        providerOptions: {\n          google: { mediaResolution: \"MEDIA_RESOLUTION_HIGH\" },\n          openai: { store: false },\n        },\n      });\n\n      const allMessages = [...messages, ...(result.response?.messages || [])];\n      const doneResult = await this.ensureDone(\n        state,\n        wrappedModel,\n        allMessages,\n        preparedOptions.instruction,\n        preparedOptions.output,\n        this.logger,\n      );\n\n      return this.consolidateMetricsAndResult(\n        startTime,\n        state,\n        doneResult.messages,\n        result,\n        maxSteps,\n        doneResult.output,\n      );\n    } catch (error) {\n      // Re-throw validation errors that should propagate to the caller\n      if (error instanceof StreamingCallbacksInNonStreamingModeError) {\n        throw error;\n      }\n\n      // Re-throw abort errors wrapped in AgentAbortError for consistent error typing\n      if (signal?.aborted) {\n        const reason = signal.reason ? String(signal.reason) : \"aborted\";\n        throw new AgentAbortError(reason);\n      }\n\n      const errorMessage = getErrorMessage(error);\n      this.logger({\n        category: \"agent\",\n        message: `Error executing agent task: ${errorMessage}`,\n        level: 0,\n      });\n\n      // For non-abort errors, return a failure result instead of throwing\n      return {\n        success: false,\n        actions: state.actions,\n        message: `Failed to execute task: ${errorMessage}`,\n        completed: false,\n        messages,\n      };\n    }\n  }\n\n  public async stream(\n    instructionOrOptions: string | AgentStreamExecuteOptions,\n  ): Promise<AgentStreamResult> {\n    const streamOptions =\n      typeof instructionOrOptions === \"object\" ? instructionOrOptions : null;\n\n    // Highlight cursor defaults to true for hybrid mode, can be overridden\n    const shouldHighlightCursor =\n      streamOptions?.highlightCursor ?? this.mode === \"hybrid\";\n\n    const {\n      options,\n      maxSteps,\n      systemPrompt,\n      allTools,\n      messages,\n      wrappedModel,\n      initialPageUrl,\n    } = await this.prepareAgent(instructionOrOptions);\n\n    // Enable cursor overlay for hybrid mode (coordinate-based interactions)\n    if (shouldHighlightCursor && this.mode === \"hybrid\") {\n      const page = await this.v3.context.awaitActivePage();\n      await page.enableCursorOverlay().catch(() => {});\n    }\n\n    const callbacks = (instructionOrOptions as AgentStreamExecuteOptions)\n      .callbacks as AgentStreamCallbacks | undefined;\n\n    const state: AgentState = {\n      collectedReasoning: [],\n      actions: [],\n      finalMessage: \"\",\n      completed: false,\n      currentPageUrl: initialPageUrl,\n    };\n    const startTime = Date.now();\n\n    let resolveResult: (value: AgentResult | PromiseLike<AgentResult>) => void;\n    let rejectResult: (reason: unknown) => void;\n    const resultPromise = new Promise<AgentResult>((resolve, reject) => {\n      resolveResult = resolve;\n      rejectResult = reject;\n    });\n\n    const handleError = (error: unknown) => {\n      const errorMessage =\n        error instanceof Error ? error.message : String(error);\n      this.logger({\n        category: \"agent\",\n        message: `Error during streaming: ${errorMessage}`,\n        level: 0,\n      });\n      rejectResult(error);\n    };\n\n    const streamResult = this.llmClient.streamText({\n      model: wrappedModel,\n      messages: prependSystemMessage(systemPrompt, messages),\n      tools: allTools,\n      stopWhen: (result) => this.handleStop(result, maxSteps),\n      temperature: 1,\n      toolChoice: \"auto\",\n      prepareStep: this.createPrepareStep(callbacks?.prepareStep),\n      onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),\n      onError: (event) => {\n        if (callbacks?.onError) {\n          callbacks.onError(event);\n        }\n        handleError(event.error);\n      },\n      onChunk: callbacks?.onChunk,\n      onFinish: (event) => {\n        if (callbacks?.onFinish) {\n          callbacks.onFinish(event);\n        }\n\n        const allMessages = [...messages, ...(event.response?.messages || [])];\n        this.ensureDone(\n          state,\n          wrappedModel,\n          allMessages,\n          options.instruction,\n          options.output,\n          this.logger,\n        ).then((doneResult) => {\n          const result = this.consolidateMetricsAndResult(\n            startTime,\n            state,\n            doneResult.messages,\n            event,\n            maxSteps,\n            doneResult.output,\n          );\n          resolveResult(result);\n        });\n      },\n      onAbort: (event) => {\n        if (callbacks?.onAbort) {\n          callbacks.onAbort(event);\n        }\n        // Reject the result promise with AgentAbortError when stream is aborted\n        const reason = options.signal?.reason\n          ? String(options.signal.reason)\n          : \"Stream was aborted\";\n        rejectResult(new AgentAbortError(reason));\n      },\n      abortSignal: options.signal,\n      providerOptions: {\n        google: { mediaResolution: \"MEDIA_RESOLUTION_HIGH\" },\n        openai: { store: false },\n      },\n    });\n\n    const agentStreamResult = streamResult as AgentStreamResult;\n    agentStreamResult.result = resultPromise;\n    return agentStreamResult;\n  }\n\n  private consolidateMetricsAndResult(\n    startTime: number,\n    state: AgentState,\n    inputMessages: ModelMessage[],\n    result: {\n      text?: string;\n      totalUsage?: LanguageModelUsage;\n      response?: { messages?: ModelMessage[] };\n      steps?: StepResult<ToolSet>[];\n    },\n    maxSteps?: number,\n    output?: Record<string, unknown>,\n  ): AgentResult {\n    if (!state.finalMessage) {\n      const allReasoning = state.collectedReasoning.join(\" \").trim();\n\n      if (!state.completed && maxSteps && result.steps?.length >= maxSteps) {\n        this.logger({\n          category: \"agent\",\n          message: `Agent stopped: reached maximum steps (${maxSteps})`,\n          level: 1,\n        });\n        state.finalMessage = `Agent stopped: reached maximum steps (${maxSteps})`;\n      } else {\n        state.finalMessage = allReasoning || result.text || \"\";\n      }\n    }\n\n    const endTime = Date.now();\n    const inferenceTimeMs = endTime - startTime;\n    if (result.totalUsage) {\n      this.v3.updateMetrics(\n        V3FunctionName.AGENT,\n        result.totalUsage.inputTokens || 0,\n        result.totalUsage.outputTokens || 0,\n        result.totalUsage.reasoningTokens || 0,\n        result.totalUsage.cachedInputTokens || 0,\n        inferenceTimeMs,\n      );\n    }\n\n    return {\n      success: state.completed,\n      message: state.finalMessage || \"Task execution completed\",\n      actions: state.actions,\n      completed: state.completed,\n      output,\n      usage: result.totalUsage\n        ? {\n            input_tokens: result.totalUsage.inputTokens || 0,\n            output_tokens: result.totalUsage.outputTokens || 0,\n            reasoning_tokens: result.totalUsage.reasoningTokens || 0,\n            cached_input_tokens: result.totalUsage.cachedInputTokens || 0,\n            inference_time_ms: inferenceTimeMs,\n          }\n        : undefined,\n      messages: inputMessages,\n    };\n  }\n\n  private createTools(\n    excludeTools?: string[],\n    variables?: Variables,\n    toolTimeout?: number,\n  ) {\n    const provider = this.llmClient?.getLanguageModel?.()?.provider;\n    return createAgentTools(this.v3, {\n      executionModel: this.executionModel,\n      logger: this.logger,\n      mode: this.mode,\n      provider,\n      excludeTools,\n      variables,\n      toolTimeout,\n    });\n  }\n\n  private handleStop(\n    result: Parameters<ReturnType<typeof stepCountIs>>[0],\n    maxSteps: number,\n  ): boolean | PromiseLike<boolean> {\n    const lastStep = result.steps[result.steps.length - 1];\n    if (lastStep?.toolCalls?.some((tc) => tc.toolName === \"done\")) {\n      return true;\n    }\n    return stepCountIs(maxSteps)(result);\n  }\n\n  /**\n   * Ensures the done tool is called at the end of agent execution.\n   * Returns the messages and any extracted output from the done call.\n   */\n  private async ensureDone(\n    state: AgentState,\n    model: LanguageModel,\n    messages: ModelMessage[],\n    instruction: string,\n    outputSchema?: StagehandZodObject,\n    logger?: (message: LogLine) => void,\n  ): Promise<{ messages: ModelMessage[]; output?: Record<string, unknown> }> {\n    if (state.completed) return { messages };\n\n    const doneResult = await handleDoneToolCall({\n      model,\n      inputMessages: messages,\n      instruction,\n      outputSchema,\n      logger,\n    });\n\n    state.completed = doneResult.taskComplete;\n    state.finalMessage = doneResult.reasoning;\n\n    const doneAction = mapToolResultToActions({\n      toolCallName: \"done\",\n      toolResult: {\n        success: true,\n        reasoning: doneResult.reasoning,\n        taskComplete: doneResult.taskComplete,\n      },\n      args: {\n        reasoning: doneResult.reasoning,\n        taskComplete: doneResult.taskComplete,\n      },\n      reasoning: doneResult.reasoning,\n    });\n\n    for (const action of doneAction) {\n      action.pageUrl = state.currentPageUrl;\n      action.timestamp = Date.now();\n      state.actions.push(action);\n    }\n\n    return {\n      messages: [...messages, ...doneResult.messages],\n      output: doneResult.output,\n    };\n  }\n\n  /**\n   * Capture a screenshot and emit it via the event bus\n   */\n  private async captureAndEmitScreenshot(): Promise<void> {\n    try {\n      const page = await this.v3.context.awaitActivePage();\n      const screenshot = await page.screenshot({ fullPage: false });\n      this.v3.bus.emit(\"agent_screenshot_taken_event\", screenshot);\n    } catch (error) {\n      this.logger({\n        category: \"agent\",\n        message: `Error capturing screenshot: ${getErrorMessage(error)}`,\n        level: 0,\n      });\n    }\n  }\n}\n"]}
+{"version":3,"file":"v3AgentHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/v3AgentHandler.ts"],"names":[],"mappings":"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","sourcesContent":["import { createAgentTools } from \"../agent/tools/index.js\";\nimport { buildAgentSystemPrompt } from \"../agent/prompts/agentSystemPrompt.js\";\nimport { LogLine } from \"../types/public/logs.js\";\nimport { V3 } from \"../v3.js\";\nimport {\n  ModelMessage,\n  ToolSet,\n  wrapLanguageModel,\n  stepCountIs,\n  LanguageModel,\n  type LanguageModelUsage,\n  type StepResult,\n  type GenerateTextOnStepFinishCallback,\n  type StreamTextOnStepFinishCallback,\n  type PrepareStepFunction,\n} from \"ai\";\nimport { StagehandZodObject } from \"../zodCompat.js\";\nimport { processMessages } from \"../agent/utils/messageProcessing.js\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport { SessionFileLogger } from \"../flowLogger.js\";\nimport {\n  AgentExecuteOptions,\n  AgentStreamExecuteOptions,\n  AgentExecuteOptionsBase,\n  AgentResult,\n  AgentContext,\n  AgentState,\n  AgentStreamResult,\n  AgentStreamCallbacks,\n  AgentToolMode,\n  AgentModelConfig,\n  Variables,\n} from \"../types/public/agent.js\";\nimport { V3FunctionName } from \"../types/public/methods.js\";\nimport { mapToolResultToActions } from \"../agent/utils/actionMapping.js\";\nimport {\n  MissingLLMConfigurationError,\n  MissingEnvironmentVariableError,\n  StreamingCallbacksInNonStreamingModeError,\n  AgentAbortError,\n} from \"../types/public/sdkErrors.js\";\nimport { handleDoneToolCall } from \"../agent/utils/handleDoneToolCall.js\";\n\nfunction getErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/**\n * Prepends a system message with cache control to the messages array.\n * The cache control providerOptions are used by Anthropic and ignored by other providers.\n */\nfunction prependSystemMessage(\n  systemPrompt: string,\n  messages: ModelMessage[],\n): ModelMessage[] {\n  return [\n    {\n      role: \"system\",\n      content: systemPrompt,\n      providerOptions: {\n        anthropic: {\n          cacheControl: { type: \"ephemeral\" },\n        },\n      },\n    },\n    ...messages,\n  ];\n}\n\nexport class V3AgentHandler {\n  private v3: V3;\n  private logger: (message: LogLine) => void;\n  private llmClient: LLMClient;\n  private executionModel?: string | AgentModelConfig;\n  private systemInstructions?: string;\n  private mcpTools?: ToolSet;\n  private mode: AgentToolMode;\n\n  constructor(\n    v3: V3,\n    logger: (message: LogLine) => void,\n    llmClient: LLMClient,\n    executionModel?: string | AgentModelConfig,\n    systemInstructions?: string,\n    mcpTools?: ToolSet,\n    mode?: AgentToolMode,\n  ) {\n    this.v3 = v3;\n    this.logger = logger;\n    this.llmClient = llmClient;\n    this.executionModel = executionModel;\n    this.systemInstructions = systemInstructions;\n    this.mcpTools = mcpTools;\n    this.mode = mode ?? \"dom\";\n  }\n\n  private async prepareAgent(\n    instructionOrOptions: string | AgentExecuteOptionsBase,\n  ): Promise<AgentContext> {\n    try {\n      const options =\n        typeof instructionOrOptions === \"string\"\n          ? { instruction: instructionOrOptions }\n          : instructionOrOptions;\n\n      const maxSteps = options.maxSteps || 20;\n\n      // Get the initial page URL first (needed for the system prompt)\n      const initialPageUrl = (await this.v3.context.awaitActivePage()).url();\n\n      // Build the system prompt with mode-aware tool guidance\n      const systemPrompt = buildAgentSystemPrompt({\n        url: initialPageUrl,\n        executionInstruction: options.instruction,\n        mode: this.mode,\n        systemInstructions: this.systemInstructions,\n        isBrowserbase: this.v3.isBrowserbase,\n        excludeTools: options.excludeTools,\n        variables: options.variables,\n        useSearch: options.useSearch,\n      });\n\n      if (options.useSearch) {\n        const bbApiKey = this.v3.browserbaseApiKey;\n        if (!bbApiKey) {\n          throw new MissingEnvironmentVariableError(\n            \"BROWSERBASE_API_KEY\",\n            \"agent search (useSearch: true)\",\n          );\n        }\n      }\n\n      const tools = this.createTools(\n        options.excludeTools,\n        options.variables,\n        options.toolTimeout,\n        options.useSearch,\n      );\n      const allTools: ToolSet = { ...tools, ...this.mcpTools };\n\n      // Use provided messages for continuation, or start fresh with the instruction\n      const messages: ModelMessage[] = options.messages?.length\n        ? [...options.messages, { role: \"user\", content: options.instruction }]\n        : [{ role: \"user\", content: options.instruction }];\n\n      if (!this.llmClient?.getLanguageModel) {\n        throw new MissingLLMConfigurationError();\n      }\n      const baseModel = this.llmClient.getLanguageModel();\n      //to do - we likely do not need middleware anymore\n      const wrappedModel = wrapLanguageModel({\n        model: baseModel,\n        middleware: {\n          ...SessionFileLogger.createLlmLoggingMiddleware(baseModel.modelId),\n        },\n      });\n\n      if (\n        this.mode === \"hybrid\" &&\n        !baseModel.modelId.includes(\"gemini-3-flash\") &&\n        !baseModel.modelId.includes(\"claude\")\n      ) {\n        this.logger({\n          category: \"agent\",\n          message: `Warning: \"${baseModel.modelId}\" may not perform well in hybrid mode. See recommended models: https://docs.stagehand.dev/v3/basics/agent#hybrid-mode`,\n          level: 0,\n        });\n      }\n\n      return {\n        options,\n        maxSteps,\n        systemPrompt,\n        allTools,\n        messages,\n        wrappedModel,\n        initialPageUrl,\n      };\n    } catch (error) {\n      this.logger({\n        category: \"agent\",\n        message: `failed to prepare agent: ${error}`,\n        level: 0,\n      });\n      throw error;\n    }\n  }\n  private createPrepareStep(\n    userCallback?: PrepareStepFunction<ToolSet>,\n  ): PrepareStepFunction<ToolSet> {\n    return async (options) => {\n      processMessages(options.messages);\n      if (userCallback) {\n        return userCallback(options);\n      }\n      return options;\n    };\n  }\n\n  private createStepHandler(\n    state: AgentState,\n    userCallback?:\n      | GenerateTextOnStepFinishCallback<ToolSet>\n      | StreamTextOnStepFinishCallback<ToolSet>,\n  ) {\n    return async (event: StepResult<ToolSet>) => {\n      this.logger({\n        category: \"agent\",\n        message: `Step finished: ${event.finishReason}`,\n        level: 2,\n      });\n\n      if (event.toolCalls && event.toolCalls.length > 0) {\n        for (let i = 0; i < event.toolCalls.length; i++) {\n          const toolCall = event.toolCalls[i];\n          const args = toolCall.input;\n          const toolResult = event.toolResults?.[i];\n\n          if (event.text && event.text.length > 0) {\n            state.collectedReasoning.push(event.text);\n            this.logger({\n              category: \"agent\",\n              message: `reasoning: ${event.text}`,\n              level: 1,\n            });\n          }\n\n          if (toolCall.toolName === \"done\") {\n            state.completed = true;\n            if (args?.taskComplete) {\n              const doneReasoning = args.reasoning;\n              const allReasoning = state.collectedReasoning.join(\" \");\n              state.finalMessage = doneReasoning\n                ? `${allReasoning} ${doneReasoning}`.trim()\n                : allReasoning || \"Task completed successfully\";\n            }\n          }\n          const mappedActions = mapToolResultToActions({\n            toolCallName: toolCall.toolName,\n            toolResult,\n            args,\n            reasoning: event.text || undefined,\n          });\n\n          for (const action of mappedActions) {\n            action.pageUrl = state.currentPageUrl;\n            action.timestamp = Date.now();\n            state.actions.push(action);\n          }\n        }\n        state.currentPageUrl = (await this.v3.context.awaitActivePage()).url();\n\n        // Capture screenshot after tool execution (only for evals)\n        if (process.env.EVALS === \"true\") {\n          try {\n            await this.captureAndEmitScreenshot();\n          } catch (e) {\n            this.logger({\n              category: \"agent\",\n              message: `Warning: Failed to capture screenshot: ${getErrorMessage(e)}`,\n              level: 1,\n            });\n          }\n        }\n      }\n\n      if (userCallback) {\n        await userCallback(event);\n      }\n    };\n  }\n\n  public async execute(\n    instructionOrOptions: string | AgentExecuteOptions,\n  ): Promise<AgentResult> {\n    const startTime = Date.now();\n    const options =\n      typeof instructionOrOptions === \"object\" ? instructionOrOptions : null;\n    const signal = options?.signal;\n\n    // Highlight cursor defaults to true for hybrid mode, can be overridden\n    const shouldHighlightCursor =\n      options?.highlightCursor ?? this.mode === \"hybrid\";\n\n    const state: AgentState = {\n      collectedReasoning: [],\n      actions: [],\n      finalMessage: \"\",\n      completed: false,\n      currentPageUrl: \"\",\n    };\n\n    let messages: ModelMessage[] = [];\n\n    try {\n      const {\n        options: preparedOptions,\n        maxSteps,\n        systemPrompt,\n        allTools,\n        messages: preparedMessages,\n        wrappedModel,\n        initialPageUrl,\n      } = await this.prepareAgent(instructionOrOptions);\n\n      // Enable cursor overlay for hybrid mode (coordinate-based interactions)\n      if (shouldHighlightCursor && this.mode === \"hybrid\") {\n        const page = await this.v3.context.awaitActivePage();\n        await page.enableCursorOverlay().catch(() => {});\n      }\n\n      messages = preparedMessages;\n      state.currentPageUrl = initialPageUrl;\n\n      const callbacks = (instructionOrOptions as AgentExecuteOptions).callbacks;\n\n      if (callbacks) {\n        const streamingOnlyCallbacks = [\n          \"onChunk\",\n          \"onFinish\",\n          \"onError\",\n          \"onAbort\",\n        ];\n        const invalidCallbacks = streamingOnlyCallbacks.filter(\n          (name) => callbacks[name as keyof typeof callbacks] != null,\n        );\n        if (invalidCallbacks.length > 0) {\n          throw new StreamingCallbacksInNonStreamingModeError(invalidCallbacks);\n        }\n      }\n\n      const result = await this.llmClient.generateText({\n        model: wrappedModel,\n        messages: prependSystemMessage(systemPrompt, messages),\n        tools: allTools,\n        stopWhen: (result) => this.handleStop(result, maxSteps),\n        temperature: 1,\n        toolChoice: \"auto\",\n\n        prepareStep: this.createPrepareStep(callbacks?.prepareStep),\n        onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),\n        abortSignal: preparedOptions.signal,\n        providerOptions: {\n          google: { mediaResolution: \"MEDIA_RESOLUTION_HIGH\" },\n          openai: { store: false },\n        },\n      });\n\n      const allMessages = [...messages, ...(result.response?.messages || [])];\n      const doneResult = await this.ensureDone(\n        state,\n        wrappedModel,\n        allMessages,\n        preparedOptions.instruction,\n        preparedOptions.output,\n        this.logger,\n      );\n\n      return this.consolidateMetricsAndResult(\n        startTime,\n        state,\n        doneResult.messages,\n        result,\n        maxSteps,\n        doneResult.output,\n      );\n    } catch (error) {\n      // Re-throw validation errors that should propagate to the caller\n      if (\n        error instanceof StreamingCallbacksInNonStreamingModeError ||\n        error instanceof MissingEnvironmentVariableError\n      ) {\n        throw error;\n      }\n\n      // Re-throw abort errors wrapped in AgentAbortError for consistent error typing\n      if (signal?.aborted) {\n        const reason = signal.reason ? String(signal.reason) : \"aborted\";\n        throw new AgentAbortError(reason);\n      }\n\n      const errorMessage = getErrorMessage(error);\n      this.logger({\n        category: \"agent\",\n        message: `Error executing agent task: ${errorMessage}`,\n        level: 0,\n      });\n\n      // For non-abort errors, return a failure result instead of throwing\n      return {\n        success: false,\n        actions: state.actions,\n        message: `Failed to execute task: ${errorMessage}`,\n        completed: false,\n        messages,\n      };\n    }\n  }\n\n  public async stream(\n    instructionOrOptions: string | AgentStreamExecuteOptions,\n  ): Promise<AgentStreamResult> {\n    const streamOptions =\n      typeof instructionOrOptions === \"object\" ? instructionOrOptions : null;\n\n    // Highlight cursor defaults to true for hybrid mode, can be overridden\n    const shouldHighlightCursor =\n      streamOptions?.highlightCursor ?? this.mode === \"hybrid\";\n\n    const {\n      options,\n      maxSteps,\n      systemPrompt,\n      allTools,\n      messages,\n      wrappedModel,\n      initialPageUrl,\n    } = await this.prepareAgent(instructionOrOptions);\n\n    // Enable cursor overlay for hybrid mode (coordinate-based interactions)\n    if (shouldHighlightCursor && this.mode === \"hybrid\") {\n      const page = await this.v3.context.awaitActivePage();\n      await page.enableCursorOverlay().catch(() => {});\n    }\n\n    const callbacks = (instructionOrOptions as AgentStreamExecuteOptions)\n      .callbacks as AgentStreamCallbacks | undefined;\n\n    const state: AgentState = {\n      collectedReasoning: [],\n      actions: [],\n      finalMessage: \"\",\n      completed: false,\n      currentPageUrl: initialPageUrl,\n    };\n    const startTime = Date.now();\n\n    let resolveResult: (value: AgentResult | PromiseLike<AgentResult>) => void;\n    let rejectResult: (reason: unknown) => void;\n    const resultPromise = new Promise<AgentResult>((resolve, reject) => {\n      resolveResult = resolve;\n      rejectResult = reject;\n    });\n\n    const handleError = (error: unknown) => {\n      const errorMessage =\n        error instanceof Error ? error.message : String(error);\n      this.logger({\n        category: \"agent\",\n        message: `Error during streaming: ${errorMessage}`,\n        level: 0,\n      });\n      rejectResult(error);\n    };\n\n    const streamResult = this.llmClient.streamText({\n      model: wrappedModel,\n      messages: prependSystemMessage(systemPrompt, messages),\n      tools: allTools,\n      stopWhen: (result) => this.handleStop(result, maxSteps),\n      temperature: 1,\n      toolChoice: \"auto\",\n      prepareStep: this.createPrepareStep(callbacks?.prepareStep),\n      onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),\n      onError: (event) => {\n        if (callbacks?.onError) {\n          callbacks.onError(event);\n        }\n        handleError(event.error);\n      },\n      onChunk: callbacks?.onChunk,\n      onFinish: (event) => {\n        if (callbacks?.onFinish) {\n          callbacks.onFinish(event);\n        }\n\n        const allMessages = [...messages, ...(event.response?.messages || [])];\n        this.ensureDone(\n          state,\n          wrappedModel,\n          allMessages,\n          options.instruction,\n          options.output,\n          this.logger,\n        ).then((doneResult) => {\n          const result = this.consolidateMetricsAndResult(\n            startTime,\n            state,\n            doneResult.messages,\n            event,\n            maxSteps,\n            doneResult.output,\n          );\n          resolveResult(result);\n        });\n      },\n      onAbort: (event) => {\n        if (callbacks?.onAbort) {\n          callbacks.onAbort(event);\n        }\n        // Reject the result promise with AgentAbortError when stream is aborted\n        const reason = options.signal?.reason\n          ? String(options.signal.reason)\n          : \"Stream was aborted\";\n        rejectResult(new AgentAbortError(reason));\n      },\n      abortSignal: options.signal,\n      providerOptions: {\n        google: { mediaResolution: \"MEDIA_RESOLUTION_HIGH\" },\n        openai: { store: false },\n      },\n    });\n\n    const agentStreamResult = streamResult as AgentStreamResult;\n    agentStreamResult.result = resultPromise;\n    return agentStreamResult;\n  }\n\n  private consolidateMetricsAndResult(\n    startTime: number,\n    state: AgentState,\n    inputMessages: ModelMessage[],\n    result: {\n      text?: string;\n      totalUsage?: LanguageModelUsage;\n      response?: { messages?: ModelMessage[] };\n      steps?: StepResult<ToolSet>[];\n    },\n    maxSteps?: number,\n    output?: Record<string, unknown>,\n  ): AgentResult {\n    if (!state.finalMessage) {\n      const allReasoning = state.collectedReasoning.join(\" \").trim();\n\n      if (!state.completed && maxSteps && result.steps?.length >= maxSteps) {\n        this.logger({\n          category: \"agent\",\n          message: `Agent stopped: reached maximum steps (${maxSteps})`,\n          level: 1,\n        });\n        state.finalMessage = `Agent stopped: reached maximum steps (${maxSteps})`;\n      } else {\n        state.finalMessage = allReasoning || result.text || \"\";\n      }\n    }\n\n    const endTime = Date.now();\n    const inferenceTimeMs = endTime - startTime;\n    if (result.totalUsage) {\n      this.v3.updateMetrics(\n        V3FunctionName.AGENT,\n        result.totalUsage.inputTokens || 0,\n        result.totalUsage.outputTokens || 0,\n        result.totalUsage.reasoningTokens || 0,\n        result.totalUsage.cachedInputTokens || 0,\n        inferenceTimeMs,\n      );\n    }\n\n    return {\n      success: state.completed,\n      message: state.finalMessage || \"Task execution completed\",\n      actions: state.actions,\n      completed: state.completed,\n      output,\n      usage: result.totalUsage\n        ? {\n            input_tokens: result.totalUsage.inputTokens || 0,\n            output_tokens: result.totalUsage.outputTokens || 0,\n            reasoning_tokens: result.totalUsage.reasoningTokens || 0,\n            cached_input_tokens: result.totalUsage.cachedInputTokens || 0,\n            inference_time_ms: inferenceTimeMs,\n          }\n        : undefined,\n      messages: inputMessages,\n    };\n  }\n\n  private createTools(\n    excludeTools?: string[],\n    variables?: Variables,\n    toolTimeout?: number,\n    useSearch?: boolean,\n  ) {\n    const provider = this.llmClient?.getLanguageModel?.()?.provider;\n    return createAgentTools(this.v3, {\n      executionModel: this.executionModel,\n      logger: this.logger,\n      mode: this.mode,\n      provider,\n      excludeTools,\n      variables,\n      toolTimeout,\n      useSearch,\n      browserbaseApiKey: useSearch ? this.v3.browserbaseApiKey : undefined,\n    });\n  }\n\n  private handleStop(\n    result: Parameters<ReturnType<typeof stepCountIs>>[0],\n    maxSteps: number,\n  ): boolean | PromiseLike<boolean> {\n    const lastStep = result.steps[result.steps.length - 1];\n    if (lastStep?.toolCalls?.some((tc) => tc.toolName === \"done\")) {\n      return true;\n    }\n    return stepCountIs(maxSteps)(result);\n  }\n\n  /**\n   * Ensures the done tool is called at the end of agent execution.\n   * Returns the messages and any extracted output from the done call.\n   */\n  private async ensureDone(\n    state: AgentState,\n    model: LanguageModel,\n    messages: ModelMessage[],\n    instruction: string,\n    outputSchema?: StagehandZodObject,\n    logger?: (message: LogLine) => void,\n  ): Promise<{ messages: ModelMessage[]; output?: Record<string, unknown> }> {\n    if (state.completed) return { messages };\n\n    const doneResult = await handleDoneToolCall({\n      model,\n      inputMessages: messages,\n      instruction,\n      outputSchema,\n      logger,\n    });\n\n    state.completed = doneResult.taskComplete;\n    state.finalMessage = doneResult.reasoning;\n\n    const doneAction = mapToolResultToActions({\n      toolCallName: \"done\",\n      toolResult: {\n        success: true,\n        reasoning: doneResult.reasoning,\n        taskComplete: doneResult.taskComplete,\n      },\n      args: {\n        reasoning: doneResult.reasoning,\n        taskComplete: doneResult.taskComplete,\n      },\n      reasoning: doneResult.reasoning,\n    });\n\n    for (const action of doneAction) {\n      action.pageUrl = state.currentPageUrl;\n      action.timestamp = Date.now();\n      state.actions.push(action);\n    }\n\n    return {\n      messages: [...messages, ...doneResult.messages],\n      output: doneResult.output,\n    };\n  }\n\n  /**\n   * Capture a screenshot and emit it via the event bus\n   */\n  private async captureAndEmitScreenshot(): Promise<void> {\n    try {\n      const page = await this.v3.context.awaitActivePage();\n      const screenshot = await page.screenshot({ fullPage: false });\n      this.v3.bus.emit(\"agent_screenshot_taken_event\", screenshot);\n    } catch (error) {\n      this.logger({\n        category: \"agent\",\n        message: `Error capturing screenshot: ${getErrorMessage(error)}`,\n        level: 0,\n      });\n    }\n  }\n}\n"]}

package/dist/cjs/lib/v3/types/public/agent.d.ts

@@ -275,7 +275,7 @@ export interface AgentExecuteOptionsBase {
      * - `think` - Agent reasoning/planning step
      * - `wait` - Wait for time or condition
      * - `done` - Mark task as complete
-     * - `search` - Web search (requires BRAVE_API_KEY)
+     * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)
      *
      * **Hybrid mode:**
      * - `click` - Click at specific coordinates
@@ -294,7 +294,7 @@ export interface AgentExecuteOptionsBase {
      * - `think` - Agent reasoning step
      * - `wait` - Wait for time/condition
      * - `done` - Mark task complete
-     * - `search` - Web search (requires BRAVE_API_KEY)
+     * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)
      *
      * @experimental
      * @example
@@ -359,6 +359,20 @@ export interface AgentExecuteOptionsBase {
      * @default 45000 (45 seconds)
      */
     toolTimeout?: number;
+    /**
+     * Enable the web search tool powered by Browserbase Search API.
+     * Requires a valid Browserbase API key (BROWSERBASE_API_KEY).
+     * When set to true, the agent gains access to a `search` tool for web searches.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.execute({
+     *   instruction: "Find the latest news about AI",
+     *   useSearch: true,
+     * });
+     * ```
+     */
+    useSearch?: boolean;
 }
 /**
  * Options for non-streaming agent execution.