diff --git a/packages/integrations/README.md b/packages/integrations/README.md index 2f732561db..00665ba3d0 100644 --- a/packages/integrations/README.md +++ b/packages/integrations/README.md @@ -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. -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. | +| `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. diff --git a/packages/integrations/claude-code/README.md b/packages/integrations/claude-code/README.md index e8e631a2fb..24844712de 100644 --- a/packages/integrations/claude-code/README.md +++ b/packages/integrations/claude-code/README.md @@ -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 @@ -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). | diff --git a/packages/integrations/codex/README.md b/packages/integrations/codex/README.md index e087ddcdda..8b1dfc4721 100644 --- a/packages/integrations/codex/README.md +++ b/packages/integrations/codex/README.md @@ -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 @@ -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. | +| `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. diff --git a/packages/integrations/crewai/README.md b/packages/integrations/crewai/README.md index 8ded014a4e..9474578102 100644 --- a/packages/integrations/crewai/README.md +++ b/packages/integrations/crewai/README.md @@ -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). | diff --git a/packages/integrations/eve/README.md b/packages/integrations/eve/README.md index fe8d49c183..50a35634e8 100644 --- a/packages/integrations/eve/README.md +++ b/packages/integrations/eve/README.md @@ -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. | diff --git a/packages/integrations/mastra/README.md b/packages/integrations/mastra/README.md index 64586847b6..8b2e03da8f 100644 --- a/packages/integrations/mastra/README.md +++ b/packages/integrations/mastra/README.md @@ -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`. | diff --git a/packages/integrations/pi/README.md b/packages/integrations/pi/README.md index e4124a2843..3f98bfb900 100644 --- a/packages/integrations/pi/README.md +++ b/packages/integrations/pi/README.md @@ -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 ``` diff --git a/packages/integrations/vercel-ai/README.md b/packages/integrations/vercel-ai/README.md index f5166b1779..cddecbd05a 100644 --- a/packages/integrations/vercel-ai/README.md +++ b/packages/integrations/vercel-ai/README.md @@ -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`. |