> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stagehand.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrations
> Connect CrewAI, Deep Agents, Eve, Mastra, or the Vercel AI SDK to a persistent Stagehand browser.
Each integration gives your agent one persistent browser and three tools: `run`, `snapshot`, and `screenshot`. Your agent decides how to navigate and interact while Stagehand manages the browser session.
Stagehand ships these experimental integrations from the monorepo and does not publish the adapters or shared integration package as standalone packages.
## Choose an integration
Connect a Python CrewAI agent over MCP/stdio.
Run locally over MCP or deploy native tools with Managed Deep Agents.
Give Vercel's framework for building durable agents native Stagehand tools.
Connect a Mastra agent over MCP/stdio.
Use Stagehand tools in a Vercel AI SDK tool loop over MCP/stdio.
## Tool contract
Every integration exposes the same browser capabilities.
Read a compact accessibility tree for the active page. Pass the bracketed IDs on interactive elements to `run` actions.
IDs are valid only for the latest snapshot of the active page. Take another snapshot after navigation or when an ID becomes stale.
Execute JavaScript against Playwright-shaped `page`, `context`, and `browser` objects, or send a batch of actions that reference snapshot IDs.
`run` accepts exactly one of `code` or `actions`. Snapshot actions support `click`, `hover`, `fill`, `type`, `press`, and `select`.
```json JavaScript theme={null}
{
"code": "await page.goto('https://example.com'); return await page.title();"
}
```
```json Snapshot actions theme={null}
{
"actions": [{ "op": "click", "id": "1-42" }]
}
```
Capture the active page as a PNG or JPEG for visual inspection. Frameworks that support multimodal tool results receive the image directly; the CrewAI adapter writes it to a temporary file because its current tool loop is text-only.
## How sessions work
The tools share a browser for the lifetime of the integration's client session. A navigation performed by `run` is visible to the next `snapshot`, and authentication and page state remain available across calls.
The CrewAI, Mastra, Vercel AI SDK, and local Deep Agents examples keep one MCP client session open so the stdio server and browser stay alive. Eve and Managed Deep Agents bind equivalent tools in-process.
The private [`core/` workspace package](https://github.com/browserbase/stagehand/tree/main/packages/integrations/core) owns the shared TypeScript tool contract, browser runtime, native bindings, and stdio MCP server. The TypeScript integrations and CrewAI use this package.
Do not create a new MCP process for every tool call. Doing so starts a new browser and invalidates any snapshot IDs from the previous call.
## Run the integrations from source
CrewAI, Mastra, and the Vercel AI SDK use the shared TypeScript Stagehand facade MCP server. Eve uses native in-process bindings from the same package. These integrations require Node.js 24 or newer and pnpm 11.10.0. CrewAI also requires Python 3.11–3.13 and [uv](https://docs.astral.sh/uv/).
```bash theme={null}
git clone https://github.com/browserbase/stagehand.git
cd stagehand
corepack pnpm@11.10.0 install --frozen-lockfile
```
```bash theme={null}
corepack pnpm@11.10.0 exec turbo run build \
--filter @browserbasehq/stagehand-integrations
```
Follow the page for your framework to install its remaining dependencies, configure its agent model, and start a task. Deep Agents is a Python-native integration and has its own setup flow.
## Choose a browser
The examples use local Chrome when you leave `BROWSERBASE_API_KEY` unset. Local mode requires a current Google Chrome installation.
Set these variables to use a disposable Browserbase browser instead:
```bash theme={null}
export STAGEHAND_BROWSER="browserbase"
export BROWSERBASE_API_KEY="your-browserbase-api-key"
```
| Variable | Purpose |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `STAGEHAND_BROWSER` | Select `local` or `browserbase`. The TypeScript integrations infer Browserbase when `BROWSERBASE_API_KEY` is set; Deep Agents defaults to local. |
| `BROWSERBASE_API_KEY` | Required for Browserbase. |
| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID for the TypeScript integrations. |
| `STAGEHAND_MODEL_NAME` | Optional model for Stagehand AI methods called from TypeScript integration tools. |
| `STAGEHAND_MODEL_API_KEY` | Credential for `STAGEHAND_MODEL_NAME`. Eve can infer a supported provider key; the MCP examples require this variable. |
The framework's agent model and Stagehand's optional browser model are separate. The agent model decides which tool to call. Configure a Stagehand model only when JavaScript passed to `run` calls AI methods such as `act`, `extract`, or `observe`.
## Security boundary
`run` executes model-authored JavaScript inside the Stagehand browser extension's service worker, not in the agent host process. That code can control the browser and access anything available in its session.
Use Browserbase as the isolation boundary for untrusted tasks. Treat authenticated browser sessions and any data reachable from them as privileged.
The MCP examples forward only Stagehand and Browserbase configuration to the child process. Agent-model credentials remain in the framework process.
Browse the shared implementation and all framework examples on GitHub.