Skip to content

Commit 85309e4

Browse files
Kylejeong2cubic-dev-ai[bot]
authored and
antonvishal
committed
docs: add claude toolset integration guide (#3122)
# Summary Add a Claude Toolset integration guide to the Stagehand v4 docs. # Why Developers need setup instructions for connecting Claude to local Chrome or Browserbase through the published Stagehand Claude SDK packages. # What changed - Add TypeScript and Python installation, browser-task examples, session cleanup, Browserbase configuration, and domain-filtering limitations. - Link the guide from navigation and integration overviews, distinguishing its native toolset from the shared MCP tool contract. # Testing (if applicable) - `npx --yes mint@4.2.788 validate`: passed. - `npx --yes mint@4.2.788 broken-links --check-anchors --check-redirects --check-snippets`: passed. - `npx --yes mint@4.2.788 a11y --skip-contrast`: passed. - Python snippet syntax and `git diff --check`: passed. - Live Claude execution and published package exports have not been verified; the registry releases were placeholders when checked. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Adds a Claude Toolset integration guide to the Stagehand v4 docs, covering setup for the published `stagehand-claude-sdk` packages in TypeScript and Python. - Documents installation, local Chrome and Browserbase launch modes, domain restrictions, and session cleanup. - Links the guide from navigation and both integration overviews, clarifying that Claude Toolset uses a native browser toolset rather than the shared MCP tool contract. <sup>Written for commit 82243b2. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/3122?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <a href="https://www.cubic.dev/action/auto-fix/pr/browserbase/stagehand/3122?returnTo=https%3A%2F%2Fgithub.com%2Fbrowserbase%2Fstagehand%2Fpull%2F3122&source=description" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/turn-on-auto-fix-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/turn-on-auto-fix-light.svg"><img alt="Turn on auto-fix" src="https://www.cubic.dev/buttons/turn-on-auto-fix-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> --------- Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
1 parent 579354a commit 85309e4

4 files changed

Lines changed: 201 additions & 3 deletions

File tree

‎packages/docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
"group": "Agent Frameworks",
5858
"pages": [
5959
"v4/integrations/agent-frameworks/overview",
60+
"v4/integrations/agent-frameworks/claude-cua-toolset-quickstart",
6061
"v4/integrations/agent-frameworks/eve",
6162
"v4/integrations/agent-frameworks/deep-agents",
6263
"v4/integrations/agent-frameworks/crewai",

‎packages/docs/v4/integrations/agent-frameworks/claude-cua-toolset-quickstart.mdx‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: "Claude Toolset"
3+
sidebarTitle: "Claude Toolset"
4+
description: "Give Claude browser tools through the Anthropic SDK, with Stagehand driving local Chrome or a Browserbase session."
5+
---
6+
7+
Connect Claude to a browser with `StagehandBrowser`. The Anthropic SDK runs the model's tool loop, and Stagehand handles browser interactions such as navigation, screenshots, and form input.
8+
9+
## Prerequisites
10+
11+
- An Anthropic API key and access to a model that supports the browser toolset.
12+
- Google Chrome for the local example, or a Browserbase API key for a hosted session.
13+
- Node.js 22.18 or later and pnpm for TypeScript, or Python 3.11 or later and uv for Python.
14+
15+
## Install the integration
16+
17+
Clone the [Claude Toolset repository](https://github.com/browserbase/claude-cua-toolset):
18+
19+
```bash
20+
git clone https://github.com/browserbase/claude-cua-toolset.git
21+
cd claude-cua-toolset
22+
```
23+
24+
<Tabs>
25+
<Tab title="TypeScript">
26+
Install the Anthropic SDK and Stagehand from npm:
27+
28+
```bash
29+
cd typescript
30+
pnpm add @anthropic-ai/sdk stagehand-claude-sdk
31+
```
32+
33+
Import the driver from the [`stagehand-claude-sdk` npm package](https://www.npmjs.com/package/stagehand-claude-sdk).
34+
</Tab>
35+
<Tab title="Python">
36+
Create an environment and install the Anthropic SDK and Stagehand from PyPI:
37+
38+
```bash
39+
cd python
40+
uv venv --python 3.11 .venv
41+
uv pip install --python .venv/bin/python anthropic stagehand-claude-sdk
42+
```
43+
44+
Import the driver as `stagehand_claude_sdk` from the [`stagehand-claude-sdk` Python package](https://pypi.org/project/stagehand-claude-sdk/).
45+
</Tab>
46+
</Tabs>
47+
48+
## Run a browser task
49+
50+
Export your Anthropic API key:
51+
52+
```bash
53+
export ANTHROPIC_API_KEY="your-anthropic-api-key"
54+
```
55+
56+
Replace the repository's `example.ts` or `example.py` with the matching example below. Both launch headless Chrome, ask Claude to read the heading on `example.com`, and print the model's messages.
57+
58+
<Tabs>
59+
<Tab title="TypeScript">
60+
```typescript example.ts
61+
import Anthropic from "@anthropic-ai/sdk";
62+
import { StagehandBrowser } from "stagehand-claude-sdk";
63+
64+
const browser = await StagehandBrowser.launch({
65+
headless: true,
66+
allowedDomains: ["example.com", "iana.org"],
67+
});
68+
69+
try {
70+
const runner = new Anthropic().messages.toolRunner({
71+
model: "claude-sonnet-5-5",
72+
max_tokens: 1024,
73+
tools: [browser],
74+
messages: [
75+
{ role: "user", content: "Open example.com and tell me the page heading." },
76+
],
77+
});
78+
79+
for await (const message of runner) {
80+
console.log(JSON.stringify(message, null, 2));
81+
}
82+
} finally {
83+
await browser.close();
84+
}
85+
```
86+
87+
Run from the repository's `typescript` directory:
88+
89+
```bash
90+
pnpm example
91+
```
92+
</Tab>
93+
<Tab title="Python">
94+
```python example.py
95+
import asyncio
96+
import os
97+
98+
from anthropic import AsyncAnthropic
99+
from stagehand_claude_sdk import StagehandBrowser
100+
101+
102+
async def main() -> None:
103+
browser = await StagehandBrowser.launch(
104+
headless=True,
105+
allowed_domains=["example.com", "iana.org"],
106+
)
107+
108+
async with browser:
109+
async with AsyncAnthropic() as client:
110+
runner = client.messages.tool_runner(
111+
model="claude-sonnet-5-5",
112+
max_tokens=1024,
113+
tools=[browser],
114+
messages=[
115+
{
116+
"role": "user",
117+
"content": "Open example.com and tell me the page heading.",
118+
}
119+
],
120+
)
121+
122+
async for message in runner:
123+
print(message)
124+
125+
126+
if __name__ == "__main__":
127+
asyncio.run(main())
128+
```
129+
130+
Run from the repository's `python` directory:
131+
132+
```bash
133+
.venv/bin/python example.py
134+
```
135+
</Tab>
136+
</Tabs>
137+
138+
Look for a response identifying the heading as **Example Domain**. Register the browser instance directly in `tools`; the Anthropic SDK dispatches its browser tool calls. Keep the same instance throughout the loop so tabs and page state remain available.
139+
140+
The tool runner doesn't close the browser. Use `finally` in TypeScript or `async with browser` in Python to close it when the task finishes or fails.
141+
142+
## Use Browserbase
143+
144+
Export your Browserbase API key:
145+
146+
```bash
147+
export BROWSERBASE_API_KEY="your-browserbase-api-key"
148+
```
149+
150+
Replace the `StagehandBrowser.launch` call with the matching factory below. Keep the tool loop and cleanup code from the previous example.
151+
152+
<Tabs>
153+
<Tab title="TypeScript">
154+
```typescript
155+
const apiKey = process.env.BROWSERBASE_API_KEY;
156+
if (!apiKey) throw new Error("Set BROWSERBASE_API_KEY before running this example.");
157+
158+
const browser = await StagehandBrowser.browserbase({
159+
apiKey,
160+
allowedDomains: ["example.com", "iana.org"],
161+
});
162+
```
163+
</Tab>
164+
<Tab title="Python">
165+
```python
166+
browser = await StagehandBrowser.browserbase(
167+
api_key=os.environ["BROWSERBASE_API_KEY"],
168+
allowed_domains=["example.com", "iana.org"],
169+
)
170+
```
171+
</Tab>
172+
</Tabs>
173+
174+
This creates a Browserbase session, so you don't need local Chrome. The toolset doesn't support downloads in Browserbase sessions.
175+
176+
## Domain restrictions
177+
178+
Set `allowedDomains` and `blockedDomains` in TypeScript, or `allowed_domains` and `blocked_domains` in Python, to restrict HTTP and HTTPS requests. Entries match exact hosts by default; use a leading `*.` pattern such as `*.example.com` for subdomains. Blocked entries take precedence.
179+
180+
<Warning>
181+
Domain restrictions don't cover WebSocket handshakes. A page on an allowed host can open a WebSocket connection to another host. Don't treat these lists as complete network isolation.
182+
</Warning>
183+
184+
## Troubleshooting
185+
186+
| Symptom | What to check |
187+
| --- | --- |
188+
| Missing browser toolset exports | Install an Anthropic SDK version that supports the browser toolset. |
189+
| Local Chrome doesn't launch | Install Google Chrome, or pass `chromePath` in TypeScript or `chrome_path` in Python to `launch`. |
190+
| Navigation is blocked | Add the task's required domains to the allow list and check the block list. |
191+
| The browser is no longer running | Close the toolset and create a new browser instance. |
192+
193+
For additional configuration and examples, see the [Claude Toolset repository](https://github.com/browserbase/claude-cua-toolset).

‎packages/docs/v4/integrations/agent-frameworks/overview.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,22 @@ Choose an integration based on your framework and how it connects tools:
1010

1111
| Framework | Connection | Guide |
1212
| --- | --- | --- |
13+
| Anthropic SDK | Native browser toolset in TypeScript or Python. | [Claude Toolset](/v4/integrations/agent-frameworks/claude-cua-toolset-quickstart) |
1314
| Eve | Native TypeScript tools in the Eve process. | [Eve](/v4/integrations/agent-frameworks/eve) |
1415
| Deep Agents | MCP over stdio locally, or native Python tools in Managed Deep Agents. | [Deep Agents](/v4/integrations/agent-frameworks/deep-agents) |
1516
| CrewAI | Python agent connected to the TypeScript MCP server over stdio. | [CrewAI](/v4/integrations/agent-frameworks/crewai) |
1617
| Mastra | MCP tools in a Mastra agent. | [Mastra](/v4/integrations/agent-frameworks/mastra) |
1718
| Vercel AI SDK | MCP tools in an AI SDK tool loop. | [Vercel AI SDK](/v4/integrations/agent-frameworks/vercel-ai-sdk) |
1819

19-
Each integration provides `run`, `snapshot`, and `screenshot`. To connect an existing coding agent instead, see [CLI Agents](/v4/integrations/cli-agents/overview).
20+
The repository integrations provide `run`, `snapshot`, and `screenshot`. Claude Toolset exposes the Anthropic SDK's browser toolset. To connect an existing coding agent instead, see [CLI agents](/v4/integrations/cli-agents/overview).
2021

2122
<Info>
22-
These integrations are experimental and run from the Stagehand repository. The adapters and shared integration package are not published as standalone packages.
23+
These integrations are experimental. Claude Toolset runs from its own repository; the other integrations run from the Stagehand repository.
2324
</Info>
2425

2526
## Tool contract
2627

27-
The agent framework integrations expose the same browser capabilities.
28+
The repository integrations share the tool contract below. For Claude Toolset's tool registration and session lifecycle, see the [Claude Toolset](/v4/integrations/agent-frameworks/claude-cua-toolset-quickstart).
2829

2930
<AccordionGroup>
3031
<Accordion title="snapshot">

‎packages/docs/v4/integrations/overview.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ The guides below cover setup, configuration, and working examples. Choose an int
1313
Build browser capabilities into your own agent using the framework of your choice. The [Agent Frameworks overview](/v4/integrations/agent-frameworks/overview) explains the shared tools and how to connect them to your framework's agent loop.
1414

1515
<CardGroup cols={2}>
16+
<Card title="Claude Toolset" icon="/images/integrations/claude-code.svg" href="/v4/integrations/agent-frameworks/claude-cua-toolset-quickstart">
17+
Give Claude browser tools through the Anthropic SDK with the Stagehand driver.
18+
</Card>
1619
<Card title="Eve by Vercel" icon="/images/integrations/eve.svg" href="/v4/integrations/agent-frameworks/eve">
1720
Give Vercel's framework for building durable agents native Stagehand tools.
1821
</Card>

0 commit comments

Comments
 (0)