[Feature] exclude tools from agent #1440

tkattkat · 2025-12-19T00:13:39Z

why

Allow users to exclude specific tools from agent

what changed

Added excludeTools option to agent.execute() that accepts an array of tool names to exclude
Excluded tools are filtered from both the toolset and system prompt
Feature is experimental and not supported in CUA mode

test plan

const stagehand = new Stagehand({
  env: "LOCAL",
  experimental: true,
});
await stagehand.init();

const agent = stagehand.agent();
const result = await agent.execute({
  instruction: "click the submit button",
  excludeTools: ["screenshot", "extract"],
});

Summary by cubic

Adds an excludeTools option to agent.execute so you can disable specific tools per run. Excluded tools are removed from both the available toolset and the system prompt to reduce unwanted calls.

New Features
- agent.execute({ excludeTools: string[] }) to skip tools; experimental and not supported in CUA mode
- createAgentTools now applies mode-based and explicit exclusions
- System prompt builds the tools list dynamically and omits excluded tools
- Validation enforces no excludeTools in CUA and requires experimental; handler passes the option to tools and prompt

^{Written for commit c041b45. Summary will update automatically on new commits.}

changeset-bot · 2025-12-19T00:13:43Z

🦋 Changeset detected

Latest commit: c041b45

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cubic-dev-ai

No issues found across 6 files

greptile-apps · 2025-12-19T00:16:54Z

Greptile Summary

This PR adds support for excluding specific tools from agent execution via the excludeTools option. The implementation filters tools from both the actual toolset and the system prompt to prevent the agent from using excluded tools.

Key changes:

Refactored system prompt generation to extract tool definitions into a buildToolsSection function that supports filtering by tool name
Updated filterTools function to apply both mode-based filtering (dom/hybrid) and explicit exclusions
Added experimental feature validation to ensure excludeTools requires experimental mode and is not used in CUA mode
Threaded the excludeTools parameter through the agent handler to both tools creation and system prompt generation
Added comprehensive documentation with examples and available tools by mode

Issues found:

The close tool is missing from both hybridTools and domTools arrays in the new buildToolsSection function, even though it exists in the actual toolset and is referenced in the guidelines section of the system prompt

Confidence Score: 4/5

This PR is mostly safe to merge with one logical issue that needs fixing
The implementation is clean and well-structured with proper validation and documentation. However, the missing close tool from the system prompt's tools list is a critical omission that could confuse the agent since the guidelines instruct it to use the close tool, but it won't be listed in the available tools section. This was working in the old implementation because the tool was never listed (existing issue), but the refactoring should have included it.
Pay close attention to packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts - the close tool must be added to both tool arrays

Important Files Changed

Filename	Overview
.changeset/tiny-carrots-learn.md	Added changeset entry for the excludeTools feature - no issues
packages/core/lib/v3/types/public/agent.ts	Added comprehensive documentation for excludeTools option with examples and tool lists - well documented
packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts	Added validation logic to ensure excludeTools is experimental and not used in CUA mode - correctly implemented
packages/core/lib/v3/agent/tools/index.ts	Refactored tool filtering to support excludeTools parameter - clean implementation with proper filtering logic
packages/core/lib/v3/handlers/v3AgentHandler.ts	Threaded excludeTools parameter through handler to tools and system prompt - properly integrated
packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts	Refactored tools section into buildToolsSection function with excludeTools support - well structured but missing close tool in tools list

Sequence Diagram

sequenceDiagram
    participant User
    participant AgentHandler as V3AgentHandler
    participant Validator as validateExperimentalFeatures
    participant PromptBuilder as buildAgentSystemPrompt
    participant ToolsFactory as createAgentTools
    participant FilterTools as filterTools
    participant LLM as Language Model

    User->>AgentHandler: execute({instruction, excludeTools: ["screenshot", "extract"]})
    AgentHandler->>Validator: validateExperimentalFeatures(excludeTools)
    alt CUA Mode
        Validator-->>AgentHandler: Error: excludeTools not supported in CUA
    else Experimental disabled
        Validator-->>AgentHandler: Error: requires experimental: true
    else Valid
        Validator-->>AgentHandler: ✓ Validation passed
    end
    
    AgentHandler->>PromptBuilder: buildAgentSystemPrompt({excludeTools})
    PromptBuilder->>PromptBuilder: buildToolsSection(mode, hasSearch, excludeTools)
    Note over PromptBuilder: Filter tools from<br/>system prompt description
    PromptBuilder-->>AgentHandler: System prompt (without excluded tools)
    
    AgentHandler->>ToolsFactory: createTools(excludeTools)
    ToolsFactory->>ToolsFactory: Create all tools
    ToolsFactory->>FilterTools: filterTools(allTools, mode, excludeTools)
    Note over FilterTools: 1. Filter by mode (dom/hybrid)<br/>2. Delete excluded tools
    FilterTools-->>ToolsFactory: Filtered toolset
    ToolsFactory-->>AgentHandler: Available tools
    
    AgentHandler->>LLM: generateText({tools, systemPrompt})
    Note over LLM: Agent only sees and can use<br/>non-excluded tools
    LLM-->>AgentHandler: Result
    AgentHandler-->>User: AgentResult

greptile-apps

_{5 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts

miguelg719 · 2025-12-19T21:45:54Z

packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts

+    { name: "close", description: "Mark the task as complete or failed" },
+  ];
+
+  const baseTools = isHybridMode ? hybridTools : domTools;


nice rearrangement, we could also centralize some of the commonly shared tools (goto, close..) to extend with the custom hybrid/dom ones

miguelg719

lgtm we should add a couple unit tests. Also should there be tools that cannot be disabled (i.e close)?

DLillard0 · 2025-12-24T03:05:46Z

@tkattkat When will this feature be merged?

@tkattkat

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @browserbasehq/[email protected] ### Patch Changes - [#1461](#1461) [`0f3991e`](0f3991e) Thanks [@tkattkat](https://github.com/tkattkat)! - Move hybrid mode out of experimental - [#1433](#1433) [`e0e22e0`](e0e22e0) Thanks [@tkattkat](https://github.com/tkattkat)! - Put hybrid mode behind experimental - [#1456](#1456) [`f261051`](f261051) Thanks [@shrey150](https://github.com/shrey150)! - Invoke page.hover for agent move action - [#1473](#1473) [`e021674`](e021674) Thanks [@shrey150](https://github.com/shrey150)! - Add safety confirmation support for OpenAI + Google CUA - [#1399](#1399) [`6a5496f`](6a5496f) Thanks [@tkattkat](https://github.com/tkattkat)! - Ensure cua agent is killed when stagehand.close is called - [#1436](#1436) [`fea1700`](fea1700) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix auto-load key for act/extract/observe parametrized models on api - [#1439](#1439) [`5b288d9`](5b288d9) Thanks [@tkattkat](https://github.com/tkattkat)! - Remove base64 from agent actions array ( still present in messages object ) - [#1408](#1408) [`e822f5a`](e822f5a) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - allow for act() cache hit when variable values change - [#1472](#1472) [`638efc7`](638efc7) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: agent cache not refreshed on action failure - [#1424](#1424) [`a890f16`](a890f16) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: "Error: -32000 Failed to convert response to JSON: CBOR: stack limit exceeded" - [#1418](#1418) [`934f492`](934f492) Thanks [@miguelg719](https://github.com/miguelg719)! - Cleanup handlers and bus listeners on close - [#1430](#1430) [`bd2db92`](bd2db92) Thanks [@shrey150](https://github.com/shrey150)! - Fix CUA model coordinate translation - [#1465](#1465) [`51e0170`](51e0170) Thanks [@miguelg719](https://github.com/miguelg719)! - Add media resolution high provider option to gemini 3 hybrid agent - [#1431](#1431) [`05f5580`](05f5580) Thanks [@tkattkat](https://github.com/tkattkat)! - Update the cache handling for agent - [#1432](#1432) [`f56a9c2`](f56a9c2) Thanks [@tkattkat](https://github.com/tkattkat)! - Deprecate cua: true in favor of mode: "cua" - [#1406](#1406) [`b40ae11`](b40ae11) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for hovering with coordinates ( page.hover ) - [#1407](#1407) [`0d2b398`](0d2b398) Thanks [@tkattkat](https://github.com/tkattkat)! - Clean up page methods - [#1412](#1412) [`cd01f29`](cd01f29) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: load GOOGLE_API_KEY from .env - [#1462](#1462) [`a734fca`](a734fca) Thanks [@shrey150](https://github.com/shrey150)! - fix: correctly pass userDataDir to chrome launcher - [#1466](#1466) [`b342acf`](b342acf) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - move playwright to optional dependencies - [#1440](#1440) [`2987cd1`](2987cd1) Thanks [@tkattkat](https://github.com/tkattkat)! - [Feature] support excluding tools from agent - [#1455](#1455) [`dfab1d5`](dfab1d5) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - update aisdk client to better enforce structured output with deepseek models - [#1428](#1428) [`4d71162`](4d71162) Thanks [@tkattkat](https://github.com/tkattkat)! - Add "hybrid" mode to stagehand agent ## @browserbasehq/[email protected] ### Minor Changes - [#1459](#1459) [`abb3469`](abb3469) Thanks [@monadoid](https://github.com/monadoid)! - Added building of binaries - [#1457](#1457) [`5fc1281`](5fc1281) Thanks [@monadoid](https://github.com/monadoid)! - First changeset for stagehand-server - [#1469](#1469) [`d634d45`](d634d45) Thanks [@monadoid](https://github.com/monadoid)! - Bump to test binary builds ### Patch Changes - Updated dependencies \[[`0f3991e`](0f3991e), [`e0e22e0`](e0e22e0), [`f261051`](f261051), [`e021674`](e021674), [`6a5496f`](6a5496f), [`fea1700`](fea1700), [`5b288d9`](5b288d9), [`e822f5a`](e822f5a), [`638efc7`](638efc7), [`a890f16`](a890f16), [`934f492`](934f492), [`bd2db92`](bd2db92), [`51e0170`](51e0170), [`05f5580`](05f5580), [`f56a9c2`](f56a9c2), [`b40ae11`](b40ae11), [`0d2b398`](0d2b398), [`cd01f29`](cd01f29), [`a734fca`](a734fca), [`b342acf`](b342acf), [`2987cd1`](2987cd1), [`dfab1d5`](dfab1d5), [`4d71162`](4d71162)]: - @browserbasehq/[email protected] ## @browserbasehq/[email protected] ### Patch Changes - [#1373](#1373) [`cadd192`](cadd192) Thanks [@tkattkat](https://github.com/tkattkat)! - Update screenshot collector in agent evals cli - Updated dependencies \[[`0f3991e`](0f3991e), [`e0e22e0`](e0e22e0), [`f261051`](f261051), [`e021674`](e021674), [`6a5496f`](6a5496f), [`fea1700`](fea1700), [`5b288d9`](5b288d9), [`e822f5a`](e822f5a), [`638efc7`](638efc7), [`a890f16`](a890f16), [`934f492`](934f492), [`bd2db92`](bd2db92), [`51e0170`](51e0170), [`05f5580`](05f5580), [`f56a9c2`](f56a9c2), [`b40ae11`](b40ae11), [`0d2b398`](0d2b398), [`cd01f29`](cd01f29), [`a734fca`](a734fca), [`b342acf`](b342acf), [`2987cd1`](2987cd1), [`dfab1d5`](dfab1d5), [`4d71162`](4d71162)]: - @browserbasehq/[email protected] Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

[Feature] exclude tools from agent

80dfb2e

cubic-dev-ai bot reviewed Dec 19, 2025

View reviewed changes

greptile-apps bot reviewed Dec 19, 2025

View reviewed changes

packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts Show resolved Hide resolved

packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts Show resolved Hide resolved

tkattkat added 2 commits December 18, 2025 16:22

update public types

955b737

add close

dac5f80

miguelg719 reviewed Dec 19, 2025

View reviewed changes

pirate approved these changes Dec 20, 2025

View reviewed changes

Merge branch 'main' into exclude-tools-from-agent

c041b45

seanmcguire12 approved these changes Dec 24, 2025

View reviewed changes

pkiv approved these changes Dec 24, 2025

View reviewed changes

seanmcguire12 merged commit 2987cd1 into main Dec 24, 2025
19 checks passed

This was referenced Dec 24, 2025

Version Packages #1414

Merged

Version Packages CloudEngineHub/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Feature] exclude tools from agent #1440

[Feature] exclude tools from agent #1440

Uh oh!

tkattkat commented Dec 19, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 19, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

greptile-apps bot commented Dec 19, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Uh oh!

miguelg719 Dec 19, 2025

Uh oh!

miguelg719 left a comment

Uh oh!

DLillard0 commented Dec 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

[Feature] exclude tools from agent #1440

[Feature] exclude tools from agent #1440

Uh oh!

Conversation

tkattkat commented Dec 19, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot commented Dec 19, 2025

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

miguelg719 Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

miguelg719 left a comment

Choose a reason for hiding this comment

Uh oh!

DLillard0 commented Dec 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

tkattkat commented Dec 19, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 19, 2025 •

edited

Loading