Metadata-Version: 2.4
Name: agent-browser-agent
Version: 0.1.1
Summary: Agent-ready tools and LangGraph integrations for vercel-agent-browser
Keywords: agent-browser,browser-automation,langchain,langgraph
Author: John Ades
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Dist: langchain-core>=1.2,<2
Requires-Dist: pydantic>=2.7,<3
Requires-Dist: vercel-agent-browser>=0.1.3,<0.2
Requires-Dist: deepagents>=0.4,<1 ; python_full_version >= '3.11' and extra == 'deepagents'
Requires-Dist: langchain>=1.2,<2 ; extra == 'deepagents'
Requires-Dist: langgraph>=1.0,<2 ; extra == 'deepagents'
Requires-Dist: langchain>=1.2,<2 ; extra == 'langgraph'
Requires-Dist: langgraph>=1.0,<2 ; extra == 'langgraph'
Requires-Dist: langchain-openai>=1.1,<2 ; extra == 'openai'
Requires-Python: >=3.10
Provides-Extra: deepagents
Provides-Extra: langgraph
Provides-Extra: openai
Description-Content-Type: text/markdown

# agent-browser-agent

[![PyPI](https://img.shields.io/pypi/v/agent-browser-agent)](https://pypi.org/project/agent-browser-agent/)

An agent-facing layer over [`vercel-agent-browser`](https://pypi.org/project/vercel-agent-browser/),
the typed Python wrapper for Vercel's `agent-browser` CLI.

It turns the wrapper's complete, versioned CLI inventory into LLM-friendly
`StructuredTool` objects and adds composed workflows that reduce browser tasks
to fewer model turns. Tools can be used directly, passed to LangChain, placed
in a LangGraph `ToolNode`, or assembled into a Deep Agent.

## What is exposed

The default maximum-control profile provides 167 tools:

- all 151 commands in the `agent-browser` 0.31.1 inventory;
- the runtime `addinitscript` command and Python `navigate` alias;
- JSON, text, and typed-method escape hatches for forward compatibility;
- 11 composed workflows for inspection, forms, resilient clicks, diagnostics,
  downloads, screenshots, login, and isolated sessions.

Every tool has a generated JSON schema based on the native Python method
signature, synchronous and asynchronous execution, structured recoverable
errors, output limiting, and stable `agent_browser_*` names.

## Install

Install the Vercel CLI and Chrome runtime once:

```bash
npm install -g agent-browser
agent-browser install
```

Install [`agent-browser-agent`](https://pypi.org/project/agent-browser-agent/) from PyPI:

```bash
pip install agent-browser-agent
```

Add the integration you need:

```bash
pip install "agent-browser-agent[langgraph,openai]"
# or
pip install "agent-browser-agent[deepagents,openai]"
```

## Use the tools directly

```python
from agent_browser_agent import AgentBrowserToolkit

toolkit = AgentBrowserToolkit()

result = toolkit.get_tool("agent_browser_open_and_inspect").invoke(
    {"url": "https://example.com"}
)
print(result)

# All tools also support ainvoke().
snapshot = await toolkit.get_tool("agent_browser_snapshot").ainvoke(
    {"interactive": True, "include_urls": True}
)
```

The underlying browser daemon persists between calls. Use one toolkit per
agent/session, or create an isolated clone:

```python
research = toolkit.for_session("research", namespace="my-app")
```

## LangGraph agent

```python
from agent_browser import AgentBrowser, ClientConfig, GlobalOptions
from agent_browser_agent import (
    AgentBrowserToolkit,
    AgentBrowserToolkitConfig,
    create_agent_browser_langgraph_agent,
)

browser = AgentBrowser(
    ClientConfig(
        timeout=60,
        options=GlobalOptions(
            session="research",
            namespace="my-app",
            headed=False,
            allowed_domains=("example.com", "*.example.com"),
        ),
    )
)

toolkit = AgentBrowserToolkit(
    browser,
    AgentBrowserToolkitConfig(access="browser", include_raw_commands=False),
)

agent = create_agent_browser_langgraph_agent(
    "openai:gpt-5.2",
    toolkit=toolkit,
    confirm_dangerous=True,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Inspect example.com."}]},
    config={"configurable": {"thread_id": "browser-1"}},
)
```

For a custom Graph API workflow:

```python
from agent_browser_agent import create_agent_browser_tool_node

tool_node = create_agent_browser_tool_node(toolkit=toolkit)
```

## Deep Agent

```python
from agent_browser_agent import create_agent_browser_deep_agent

agent = create_agent_browser_deep_agent(
    model="openai:gpt-5.2",
    toolkit=toolkit,
    confirm_dangerous=True,
)
```

Additional options such as `checkpointer`, `store`, `backend`, `subagents`,
`skills`, `memory`, and `response_format` are forwarded to
`deepagents.create_deep_agent`.

## Access control

Maximum control is the default:

```python
AgentBrowserToolkitConfig(access="all")
```

This includes install, upgrade, plugin mutation, saved-state mutation, and raw
command tools. For normal web automation use:

```python
AgentBrowserToolkitConfig(
    access="browser",
    include_raw_commands=False,
)
```

Fine-grained policy is available with `allowed_tools` and `denied_tools`.
`recommended_interrupts()` returns the host-mutating tools that should require
human approval in agent runtimes.

## Composed tools

- `agent_browser_open_and_inspect`
- `agent_browser_call_and_inspect`
- `agent_browser_run_workflow`
- `agent_browser_page_context`
- `agent_browser_fill_form`
- `agent_browser_smart_click`
- `agent_browser_screenshot_and_snapshot`
- `agent_browser_download_and_verify`
- `agent_browser_login_and_inspect`
- `agent_browser_diagnose`
- `agent_browser_session_workflow`

Use primitive tools when the model must inspect an intermediate result. Use a
composed tool for deterministic steps that should happen together.

## Safety notes

- No tool invokes a shell. Raw commands accept argument arrays and optional
  stdin.
- Prefer `access="browser"` and `allowed_domains` for untrusted tasks.
- Snapshot refs become stale after navigation or large DOM changes; take a new
  snapshot before retrying.
- Credentials passed as LLM tool arguments may appear in model traces. Prefer
  saved `agent-browser` auth profiles.
- Host paths returned for downloads, screenshots, PDFs, traces, or recordings
  refer to the machine running `agent-browser`.
