Skip to content

Conversation

@miguelg719
Copy link
Collaborator

why

We didn't have docs for passing custom tools to stagehand agent or examples, only MCP integrations. Under the hood, stagehand treats both the same, and passing custom tools directly is (most times) more convenient and performant.

what changed

Added an example agent-custom-tools.ts as well as docs under the basics > agent section

test plan

@changeset-bot
Copy link

changeset-bot bot commented Oct 31, 2025

🦋 Changeset detected

Latest commit: 727a759

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

This PR includes changesets to release 2 packages
Name Type
@browserbasehq/stagehand Patch
@browserbasehq/stagehand-evals 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

Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Greptile Overview

Greptile Summary

Added documentation and examples for passing custom tools directly to Stagehand agents, providing a more performant alternative to MCP integrations.

Key Changes:

  • Added agent-custom-tools.ts example demonstrating weather tool integration
  • Updated v3.ts to validate experimental: true flag for custom tools (matching MCP integration behavior)
  • Added comprehensive documentation section with multiple code examples and comparison table
  • Minor README formatting improvements

Issues Found:

  • Example code has experimental: true commented out, which will cause runtime error when custom tools are used
  • Documentation examples don't show the required experimental: true flag in Stagehand constructor

Confidence Score: 3/5

  • Safe to merge after fixing experimental flag in example and documentation
  • The logic changes properly enforce experimental mode for custom tools, and documentation is comprehensive. However, the example will fail at runtime because experimental: true is commented out, and documentation examples don't mention this requirement. These are critical issues that will cause user confusion and runtime errors.
  • Pay close attention to packages/core/examples/agent-custom-tools.ts (experimental flag commented) and packages/docs/v3/basics/agent.mdx (missing experimental flag requirement)

Important Files Changed

File Analysis

Filename Score Overview
packages/core/examples/agent-custom-tools.ts 4/5 Added new example demonstrating custom tool usage with agent; includes commented out experimental flag which must be enabled for custom tools to work
packages/core/lib/v3/v3.ts 5/5 Added experimental mode validation for custom tools alongside existing MCP integration checks; improved logging to include options in debug output
packages/docs/v3/basics/agent.mdx 5/5 Added comprehensive documentation section for custom tools with multiple examples and comparison table to MCP integrations

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant Agent
    participant CustomTool
    participant Browser

    User->>Stagehand: new Stagehand({experimental: true})
    User->>Stagehand: agent({tools: {getWeather}})
    Stagehand->>Stagehand: Check experimental flag
    alt experimental mode disabled
        Stagehand-->>User: Error: Enable experimental: true
    end
    Stagehand->>Agent: Create agent instance
    Agent-->>User: Return agent object
    
    User->>Agent: execute("What's the weather in SF?")
    Agent->>Agent: Parse instruction
    Agent->>CustomTool: Call getWeather("San Francisco")
    CustomTool->>CustomTool: fetchWeatherAPI()
    CustomTool-->>Agent: Return weather data
    Agent->>Browser: Optional browser interactions
    Browser-->>Agent: Page data
    Agent-->>User: AgentResult with weather info
Loading

4 files reviewed, 3 comments

Edit Code Review Agent Settings | Greptile

const stagehand = new Stagehand({
env: "LOCAL",
verbose: 2,
// experimental: true, // You must enable experimental mode to use custom tools / MCP integrations
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: experimental: true must be uncommented for custom tools to work (the example will throw an error without it)

Suggested change
// experimental: true, // You must enable experimental mode to use custom tools / MCP integrations
experimental: true, // You must enable experimental mode to use custom tools / MCP integrations
Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/core/examples/agent-custom-tools.ts
Line: 43:43

Comment:
**logic:** `experimental: true` must be uncommented for custom tools to work (the example will throw an error without it)

```suggestion
    experimental: true, // You must enable experimental mode to use custom tools / MCP integrations
```

How can I resolve this? If you propose a fix, please make it concise.

@miguelg719 miguelg719 merged commit 98e212b into main Oct 31, 2025
15 checks passed
@github-actions github-actions bot mentioned this pull request Oct 31, 2025
miguelg719 pushed a commit that referenced this pull request Oct 31, 2025
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/stagehand@3.0.1

### Patch Changes

- [#1207](#1207)
[`55da8c6`](55da8c6)
Thanks [@miguelg719](https://github.com/miguelg719)! - Fix broken links
to quickstart docs

- [#1200](#1200)
[`0a5ee63`](0a5ee63)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - log info
when scope narrowing selector fails

- [#1205](#1205)
[`ee76881`](ee76881)
Thanks [@miguelg719](https://github.com/miguelg719)! - Update README.md,
add Changelog for v3

- [#1209](#1209)
[`9e95add`](9e95add)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix
circular import in exported aisdk example client

- [#1211](#1211)
[`98e212b`](98e212b)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add an example
for passing custom tools to agent

- [#1206](#1206)
[`d5ecbfc`](d5ecbfc)
Thanks [@miguelg719](https://github.com/miguelg719)! - Export example
AISdkClient properly from the stagehand package

## @browserbasehq/stagehand-evals@1.1.1

### Patch Changes

- Updated dependencies
\[[`55da8c6`](55da8c6),
[`0a5ee63`](0a5ee63),
[`ee76881`](ee76881),
[`9e95add`](9e95add),
[`98e212b`](98e212b),
[`d5ecbfc`](d5ecbfc)]:
    -   @browserbasehq/stagehand@3.0.1

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants