Skip to content

docs(integrations): project id optional everywhere; package overview README #2777

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miguelg719 merged 3 commits into from
Aug 20, 2026
Merged

docs(integrations): project id optional everywhere; package overview README #2777

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5dadc3f
docs(integrations): project id optional everywhere; package overview …
miguelg719 Aug 19, 2026
623ee20
docs(integrations): Pi casing in overview table
miguelg719 Aug 19, 2026
3e7c0c5
docs(integrations): drop project id from READMEs entirely
miguelg719 Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions packages/integrations/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,26 @@
# Stagehand integrations

Private workspace package for Stagehand integration adapters.
Agent-harness integrations for the Stagehand facade tool surface: three tools — `run`,
`snapshot`, and `screenshot` — backed by one persistent browser, consumable either as a stdio
MCP server or as native in-process tools. The contract (tool descriptions, schemas, runtime
validators, and the agent system prompt) is defined once in `core/` and imported everywhere
else, never restated.
Comment thread
miguelg719 marked this conversation as resolved.
Comment thread
miguelg719 marked this conversation as resolved.
Comment thread
miguelg719 marked this conversation as resolved.

The code-mode stdio entrypoint currently provides the MCP host and process lifecycle used by later code-mode capabilities. It intentionally advertises no tools yet.
## Structure

The `deepagents/` Python project provides local and managed LangChain Deep Agents integrations. Both
expose stateful `run`, `snapshot`, and `screenshot` browser tools using the Stagehand Python SDK.
| Directory | What it is |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core/` | The `@browserbasehq/stagehand-integrations` package: the facade contract, `StagehandFacadeTools`, the `stagehand-facade` stdio MCP bin, and the code-mode MCP host scaffold. |
| `claude-code/` | Claude Agent SDK example (programmatic MCP mount) plus a `.mcp.json` for connecting a running Claude Code CLI. |
| `codex/` | Codex SDK example (config-override MCP mount) plus a `config.toml` template for the codex CLI. |
| `crewai/` | Python CrewAI example over MCP/stdio (uv project). |
| `deepagents/` | Python LangChain Deep Agents integrations: a local stdio MCP server and a Managed Deep Agents project with native tools. |
| `eve/` | Eve example with the tools bound natively via `defineTool` (Eve has no external-process tool mounting). |
| `fx/` | fx configuration templates and skill — fx consumes the facade via its user-global MCP config. |
Comment thread
miguelg719 marked this conversation as resolved.
Comment thread
miguelg719 marked this conversation as resolved.
Comment thread
miguelg719 marked this conversation as resolved.
| `mastra/` | Mastra example over MCP/stdio via Mastra's `MCPClient`. |
| `pi/` | Pi extension registering the tools natively (Pi ships without built-in MCP). |
| `vercel-ai/` | Vercel AI SDK example over MCP/stdio via `createMCPClient`. |

Each example is a self-contained project: install, export `BROWSERBASE_API_KEY`, and run —
see the directory's README. TypeScript examples consume `core/` as a workspace dependency; the Python projects resolve the published
`stagehand` package.
Comment thread
miguelg719 marked this conversation as resolved.
2 changes: 0 additions & 2 deletions packages/integrations/claude-code/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ Export credentials (Browserbase is the default and recommended backend):
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export BROWSERBASE_API_KEY=bb_live_...
export BROWSERBASE_PROJECT_ID=...
```

## Run
Expand All @@ -31,7 +30,6 @@ pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade s
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. |
| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project. |
| `CLAUDE_STAGEHAND_MODEL` | Agent model; defaults to `claude-sonnet-5`. |
| `ANTHROPIC_API_KEY` | Claude Agent SDK credential (never forwarded to the browser). |

Expand Down
16 changes: 7 additions & 9 deletions packages/integrations/codex/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ Export credentials (Browserbase is the default and recommended backend). Codex a
```bash
export OPENAI_API_KEY=sk-...
export BROWSERBASE_API_KEY=bb_live_...
export BROWSERBASE_PROJECT_ID=...
```

## Run
Expand All @@ -30,14 +29,13 @@ export BROWSERBASE_PROJECT_ID=...
pnpm --filter @browserbasehq/stagehand-integrations-example-codex-facade start "Open https://example.com, snapshot it, and report the heading citing the snapshot ID."
```

| Variable | Purpose |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. |
| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project. |
| `CODEX_STAGEHAND_MODEL` | Optional model override; by default Codex uses its own harness-tuned model. |
| `OPENAI_API_KEY` | Codex SDK credential (never forwarded to the browser). |
| `CODEX_PATH_OVERRIDE` | Path to a locally installed `codex` binary if your package manager skips the SDK's vendored-binary postinstall (`export CODEX_PATH_OVERRIDE=$(which codex)`). |
| Variable | Purpose |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. |
Comment thread
miguelg719 marked this conversation as resolved.
| `CODEX_STAGEHAND_MODEL` | Optional model override; by default Codex uses its own harness-tuned model. |
| `OPENAI_API_KEY` | Codex SDK credential (never forwarded to the browser). |
| `CODEX_PATH_OVERRIDE` | Path to a locally installed `codex` binary if your package manager skips the SDK's vendored-binary postinstall (`export CODEX_PATH_OVERRIDE=$(which codex)`). |

The local sandbox stays `read-only` — all browser work happens inside the MCP server. Note
Codex has no native turn limit; long tasks run until the model finishes.
Expand Down
1 change: 0 additions & 1 deletion packages/integrations/crewai/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ uv sync
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase API key. |
| `BROWSERBASE_PROJECT_ID` | Browserbase project ID. |
| `STAGEHAND_MODEL_NAME` / `STAGEHAND_MODEL_API_KEY` | Model used by the facade server and its key. |
| `CREWAI_MODEL` | CrewAI agent model; defaults to `openai/gpt-5.6-luna`. |
| `OPENAI_API_KEY` | Used by the CrewAI agent model in the host process; NOT forwarded to the facade child process (the child env is an explicit `STAGEHAND_*`/`BROWSERBASE_*` allowlist). |
Expand Down
1 change: 0 additions & 1 deletion packages/integrations/eve/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ Configure the environment as needed:
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase API key; required when using the Browserbase backend. |
| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. |
| `STAGEHAND_MODEL_NAME` | Optional Stagehand model name, such as `openai/gpt-5.6-luna`. |
| `STAGEHAND_MODEL_API_KEY` | Optional explicit API key for `STAGEHAND_MODEL_NAME`; otherwise the matching provider key is inferred when supported. |
| `STAGEHAND_EVE_SESSION_FILE` | Optional path used to persist the Browserbase session ID; defaults to a file in the system temporary directory. |
Expand Down
1 change: 0 additions & 1 deletion packages/integrations/mastra/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ Configure the environment as needed:
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase API key. |
| `BROWSERBASE_PROJECT_ID` | Browserbase project ID. |
| `STAGEHAND_MODEL_NAME` | Model used by the facade server. |
| `STAGEHAND_MODEL_API_KEY` | API key for the facade server model. |
| `MASTRA_STAGEHAND_MODEL` | Mastra agent model; defaults to `gpt-5.6-luna`. |
Expand Down
1 change: 0 additions & 1 deletion packages/integrations/pi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ key pi supports:

```bash
export BROWSERBASE_API_KEY=bb_live_...
export BROWSERBASE_PROJECT_ID=...
export OPENAI_API_KEY=sk-... # or ANTHROPIC_API_KEY
```

Expand Down
1 change: 0 additions & 1 deletion packages/integrations/vercel-ai/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ Configure the environment as needed:
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
| `BROWSERBASE_API_KEY` | Browserbase API key. |
| `BROWSERBASE_PROJECT_ID` | Browserbase project ID. |
| `STAGEHAND_MODEL_NAME` | Model used by the facade server. |
| `STAGEHAND_MODEL_API_KEY` | API key for the facade server model. |
| `AI_SDK_STAGEHAND_MODEL` | AI SDK agent model; defaults to `gpt-5.6-luna`. |
Expand Down
Loading