langchain-stagehand 0.0.1__tar.gz

langchain_stagehand-0.0.1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: langchain-stagehand
+Version: 0.0.1
+Summary: Browserbase and Stagehand browser middleware for LangChain agents
+License-Expression: MIT
+Requires-Dist: langchain>=1.4.7,<2
+Requires-Dist: stagehand>=4.3.0,<5
+Requires-Dist: stagehand-middleware>=0.1.1,<0.2
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/langchain-ai/langchain-browserbase
+Description-Content-Type: text/markdown
+
+# LangChain Stagehand
+
+Add a persistent browser to a LangChain or Deep Agents agent with `StagehandMiddleware`. The middleware exposes Stagehand's shared `run`, `snapshot`, and `screenshot` tools, includes browser usage guidance in their descriptions, and returns screenshots as model-visible images. The agent’s system prompt is left untouched. No MCP server is needed.
+
+## Install
+
+```bash
+pip install langchain-stagehand
+```
+
+Python 3.11+ is required. Set your model provider's API key in your environment, and `BROWSERBASE_API_KEY` to use Browserbase. Never put credentials in browser tool inputs.
+
+## Use with LangChain
+
+```python
+import asyncio
+
+from langchain.agents import create_agent
+from langchain_stagehand import StagehandMiddleware
+from stagehand import Stagehand, browserbase
+
+
+async def main():
+    import os
+
+    browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
+    stagehand = await Stagehand.create(browser=browser)
+    middleware = StagehandMiddleware(stagehand=stagehand)
+    agent = create_agent("anthropic:claude-sonnet-4-6", middleware=[middleware])
+    try:
+        result = await agent.ainvoke({
+            "messages": [{"role": "user", "content": "Open example.com and summarize the page."}]
+        })
+        print(result["messages"][-1].content)
+    finally:
+        await browser.close()
+
+
+asyncio.run(main())
+```
+
+Install the model integration separately, such as `pip install langchain-anthropic`, and set `ANTHROPIC_API_KEY` for this example. Browser tool calls use Stagehand's Playwright-shaped facade; they do not require a separate Stagehand model for these operations.
+
+## Use with Deep Agents
+
+Use the same Stagehand client setup and replace `create_agent` with:
+
+```python
+from deepagents import create_deep_agent
+
+agent = create_deep_agent("anthropic:claude-sonnet-4-6", middleware=[StagehandMiddleware(stagehand=stagehand)])
+```
+
+Install `deepagents` separately. Use `ainvoke` or `astream`: browser tools and middleware are asynchronous.
+
+## Browser lifecycle
+
+Pass a configured Stagehand client attached to local Chrome or Browserbase:
+
+```python
+from stagehand import Stagehand, local_browser
+
+browser = await local_browser.launch(headless=True)
+stagehand = await Stagehand.create(browser=browser)
+middleware = StagehandMiddleware(stagehand=stagehand)
+```
+
+Your application configures and owns the Stagehand client and browser. All SDK settings remain available through `Stagehand.create(...)`, including API URL, model, caching, telemetry, and logging. The middleware reuses that exact client across runs, preserving tabs, logins, and snapshot IDs. Close the browser when finished; that also closes the client. The middleware never closes or recreates the client, and `browser.close()` in run code leaves both open. After a disconnection, the application supplies a new configured client. Give concurrent agents separate clients/browsers. Take a new snapshot after navigation before using snapshot IDs.
+
+The screenshot tool returns images to the model. Screenshots that run code saves with a `path` are written under the current working directory, not to a Deep Agents backend; backend support is not implemented yet.
+
+## Security and limitations
+
+- Browser tools can navigate, submit forms, and interact with authenticated websites; use LangChain's human-in-the-loop middleware for sensitive actions
+- Web page content is untrusted input, not instructions for your agent
+- The Playwright-shaped API is not a general-purpose security sandbox or a substitute for network isolation
+- Agent execution is asynchronous only; browser state lives in the browser and is not checkpointed
+
+## Development
+
+```bash
+make install
+make format
+make check
+RUN_BROWSER_TESTS=1 uv run pytest tests/test_browser.py --color=no
+make build
+```
+
+`make check` enforces Ruff formatting and lint rules (including bug-prone patterns, async misuse, and accidental prints), ty checking of the package and public API examples with all diagnostics treated as errors, and focused middleware tests. The distribution includes `py.typed` so downstream type checkers can validate usage. Astral's ty is pinned in the Makefile and runs through `uvx`; no extra runtime dependency is needed.
+
+The live browser test covers local Chrome and Browserbase; the remote case is skipped without `BROWSERBASE_API_KEY`. Set `CHROME_PATH` if Chrome is not in its usual install location. The Python distribution is `langchain-stagehand`, and the import is `langchain_stagehand`; this repository does not publish the separate upstream `stagehand-deepagents` package.

langchain_stagehand-0.0.1/README.md

@@ -0,0 +1,91 @@
+# LangChain Stagehand
+
+Add a persistent browser to a LangChain or Deep Agents agent with `StagehandMiddleware`. The middleware exposes Stagehand's shared `run`, `snapshot`, and `screenshot` tools, includes browser usage guidance in their descriptions, and returns screenshots as model-visible images. The agent’s system prompt is left untouched. No MCP server is needed.
+
+## Install
+
+```bash
+pip install langchain-stagehand
+```
+
+Python 3.11+ is required. Set your model provider's API key in your environment, and `BROWSERBASE_API_KEY` to use Browserbase. Never put credentials in browser tool inputs.
+
+## Use with LangChain
+
+```python
+import asyncio
+
+from langchain.agents import create_agent
+from langchain_stagehand import StagehandMiddleware
+from stagehand import Stagehand, browserbase
+
+
+async def main():
+    import os
+
+    browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
+    stagehand = await Stagehand.create(browser=browser)
+    middleware = StagehandMiddleware(stagehand=stagehand)
+    agent = create_agent("anthropic:claude-sonnet-4-6", middleware=[middleware])
+    try:
+        result = await agent.ainvoke({
+            "messages": [{"role": "user", "content": "Open example.com and summarize the page."}]
+        })
+        print(result["messages"][-1].content)
+    finally:
+        await browser.close()
+
+
+asyncio.run(main())
+```
+
+Install the model integration separately, such as `pip install langchain-anthropic`, and set `ANTHROPIC_API_KEY` for this example. Browser tool calls use Stagehand's Playwright-shaped facade; they do not require a separate Stagehand model for these operations.
+
+## Use with Deep Agents
+
+Use the same Stagehand client setup and replace `create_agent` with:
+
+```python
+from deepagents import create_deep_agent
+
+agent = create_deep_agent("anthropic:claude-sonnet-4-6", middleware=[StagehandMiddleware(stagehand=stagehand)])
+```
+
+Install `deepagents` separately. Use `ainvoke` or `astream`: browser tools and middleware are asynchronous.
+
+## Browser lifecycle
+
+Pass a configured Stagehand client attached to local Chrome or Browserbase:
+
+```python
+from stagehand import Stagehand, local_browser
+
+browser = await local_browser.launch(headless=True)
+stagehand = await Stagehand.create(browser=browser)
+middleware = StagehandMiddleware(stagehand=stagehand)
+```
+
+Your application configures and owns the Stagehand client and browser. All SDK settings remain available through `Stagehand.create(...)`, including API URL, model, caching, telemetry, and logging. The middleware reuses that exact client across runs, preserving tabs, logins, and snapshot IDs. Close the browser when finished; that also closes the client. The middleware never closes or recreates the client, and `browser.close()` in run code leaves both open. After a disconnection, the application supplies a new configured client. Give concurrent agents separate clients/browsers. Take a new snapshot after navigation before using snapshot IDs.
+
+The screenshot tool returns images to the model. Screenshots that run code saves with a `path` are written under the current working directory, not to a Deep Agents backend; backend support is not implemented yet.
+
+## Security and limitations
+
+- Browser tools can navigate, submit forms, and interact with authenticated websites; use LangChain's human-in-the-loop middleware for sensitive actions
+- Web page content is untrusted input, not instructions for your agent
+- The Playwright-shaped API is not a general-purpose security sandbox or a substitute for network isolation
+- Agent execution is asynchronous only; browser state lives in the browser and is not checkpointed
+
+## Development
+
+```bash
+make install
+make format
+make check
+RUN_BROWSER_TESTS=1 uv run pytest tests/test_browser.py --color=no
+make build
+```
+
+`make check` enforces Ruff formatting and lint rules (including bug-prone patterns, async misuse, and accidental prints), ty checking of the package and public API examples with all diagnostics treated as errors, and focused middleware tests. The distribution includes `py.typed` so downstream type checkers can validate usage. Astral's ty is pinned in the Makefile and runs through `uvx`; no extra runtime dependency is needed.
+
+The live browser test covers local Chrome and Browserbase; the remote case is skipped without `BROWSERBASE_API_KEY`. Set `CHROME_PATH` if Chrome is not in its usual install location. The Python distribution is `langchain-stagehand`, and the import is `langchain_stagehand`; this repository does not publish the separate upstream `stagehand-deepagents` package.

langchain_stagehand-0.0.1/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "langchain-stagehand"
+version = "0.0.1"
+description = "Browserbase and Stagehand browser middleware for LangChain agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "langchain>=1.4.7,<2",
+    "stagehand>=4.3.0,<5",
+    "stagehand-middleware>=0.1.1,<0.2",
+]
+
+[project.urls]
+Repository = "https://github.com/langchain-ai/langchain-browserbase"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.10"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8,<10",
+    "pytest-asyncio>=1,<2",
+    "ruff>=0.15,<0.16",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "ASYNC",
+    "RUF",
+    "T20",
+]
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.rules]
+all = "error"

langchain_stagehand-0.0.1/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "langchain-stagehand"
+version = "0.0.1"
+description = "Browserbase and Stagehand browser middleware for LangChain agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+  "langchain>=1.4.7,<2",
+  "stagehand>=4.3.0,<5",
+  "stagehand-middleware>=0.1.1,<0.2",
+]
+
+[project.urls]
+Repository = "https://github.com/langchain-ai/langchain-browserbase"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.10"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "pytest-asyncio>=1,<2", "ruff>=0.15,<0.16"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "RUF", "T20"]
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.rules]
+all = "error"

langchain_stagehand-0.0.1/src/langchain_stagehand/__init__.py

@@ -0,0 +1,5 @@
+"""Stagehand middleware for LangChain and Deep Agents."""
+
+from .middleware import StagehandMiddleware
+
+__all__ = ["StagehandMiddleware"]

langchain_stagehand-0.0.1/src/langchain_stagehand/actions.py

@@ -0,0 +1,38 @@
+"""Typed snapshot actions accepted by Stagehand's browser facade."""
+
+from typing import Literal, NotRequired
+
+from typing_extensions import TypedDict
+
+
+class ClickAction(TypedDict):
+    op: Literal["click", "hover"]
+    id: str
+
+
+class FillAction(TypedDict):
+    op: Literal["fill"]
+    id: str
+    value: str
+
+
+class TypeAction(TypedDict):
+    op: Literal["type"]
+    id: str
+    text: str
+    delay: NotRequired[float]
+
+
+class PressAction(TypedDict):
+    op: Literal["press"]
+    id: str
+    key: str
+
+
+class SelectAction(TypedDict):
+    op: Literal["select"]
+    id: str
+    values: str | list[str]
+
+
+SnapshotAction = ClickAction | FillAction | TypeAction | PressAction | SelectAction

langchain_stagehand-0.0.1/src/langchain_stagehand/middleware.py

@@ -0,0 +1,88 @@
+"""Native LangChain middleware over Stagehand's shared browser facade."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Annotated, Literal, TypeVar
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.tools import ToolException, tool
+from pydantic import Field
+from stagehand import Stagehand
+from stagehand_middleware.facade import (
+    StagehandFacadeExecutionError,
+    StagehandFacadeInputError,
+    StagehandFacadeTools,
+    facade_tools,
+)
+
+from .actions import SnapshotAction
+
+T = TypeVar("T")
+
+
+class StagehandMiddleware(AgentMiddleware):
+    """Add browser tools with `middleware=[StagehandMiddleware(stagehand=client)]`."""
+
+    def __init__(self, *, stagehand: Stagehand) -> None:
+        self._stagehand = stagehand
+        self._facade = self._open_facade()
+        descriptions = {spec["name"]: spec["description"] for spec in facade_tools()}
+
+        @tool(
+            description=descriptions["run"]
+            + (
+                " Reuse the initialized browser; do not launch another browser or browser process."
+                " Capture a new snapshot after navigation or stale IDs."
+            )
+        )
+        async def run(
+            *, code: str | None = None, actions: list[SnapshotAction] | None = None
+        ) -> str:
+            result = await self._call(lambda facade: facade.run(code=code, actions=actions))
+            return result if isinstance(result, str) else json.dumps(result, ensure_ascii=False)
+
+        @tool(
+            description=descriptions["snapshot"]
+            + (" Capture a new snapshot after navigation or stale IDs before taking actions.")
+        )
+        async def snapshot(*, includeIframes: bool = True) -> str:
+            return await self._call(lambda facade: facade.snapshot(include_iframes=includeIframes))
+
+        @tool(description=descriptions["screenshot"])
+        async def screenshot(
+            *,
+            fullPage: bool | None = None,
+            type: Literal["png", "jpeg"] = "png",
+            quality: Annotated[float | None, Field(ge=0, le=100)] = None,
+        ) -> list[dict[str, str]]:
+            image = await self._call(
+                lambda facade: facade.screenshot(
+                    full_page=fullPage,
+                    type=type,
+                    quality=quality,
+                )
+            )
+            return [{"type": "image", "base64": image["data"], "mime_type": image["mimeType"]}]
+
+        self.tools = [run, snapshot, screenshot]
+        for browser_tool in self.tools:
+            browser_tool.handle_tool_error = True
+            browser_tool.handle_validation_error = True
+
+    def _open_facade(self) -> StagehandFacadeTools:
+        # The application owns the client and browser: `browser.close()` in run code
+        # leaves both open and swaps in a fresh facade, so later calls still work.
+        async def reopen() -> None:
+            self._facade = self._open_facade()
+
+        return StagehandFacadeTools(self._stagehand, on_close_requested=reopen)
+
+    async def _call(self, operation: Callable[[StagehandFacadeTools], Awaitable[T]]) -> T:
+        try:
+            return await operation(self._facade)
+        except (StagehandFacadeInputError, StagehandFacadeExecutionError) as error:
+            raise ToolException(str(error)) from None
+        except Exception as error:
+            raise ToolException(f"{type(error).__name__}: {error}") from None