agentic-browser

Agentic Browser

The web, as an LLM wants to see it

Stable refs · compact observations · outcome-verified actions · MCP for any agent host

Not another HTML scraper. A real Chromium browser controlled with semantic tools — so Claude, Cursor, LangGraph, or your own agent can see, click, type, and verify without drowning in 100k+ tokens of markup.

Repo: github.com/applejuice093/Agentic-browser · Branch: dev

---

Why this exists

Traditional stacks hand the model raw HTML or brittle CSS. Agents need:

1. Small, structured observations (roles, labels, refs)
2. Actions that mean success (URL/DOM outcomes, not “no exception”)
3. A way to plug into any host (MCP + OpenAI/Anthropic tool schemas)

Agentic Browser is built for that loop.

navigate → observe (~1–2k tokens) → click_text / type → outcome_verified?
         ↘ if page_gate = challenge → stop (don’t hallucinate)

---

Highlights — measured positives

Numbers from live benchmarks on public sites (approx. tokens ≈ chars/4). Reproduce with scripts under examples/.

Token efficiency (LLM feed)

Takeaway: Dumping HTML into an LLM is the wrong default. Observation mode is ~98–99% smaller on heavy modern pages.

Task quality

Product completeness

Positives at a glance

• ~98–99% token cut vs raw HTML on complex landings (Rockstar, GitHub)
• ~78–84% token cut vs HTML for structured extract tasks
• 100% structured field parity with best-case CSS scrapers on demo sites
• Outcome verification — ok only when post-conditions hold (e.g. /issues in URL)
• Scoped grounding — nav-first find so PR/commit text doesn’t steal “Issues”
• Page gates — js_challenge / captcha / login wall detected and reported
• MCP-ready — Claude Desktop, Cursor, any MCP host
• OpenAI + Anthropic tool schemas — tools_as_openai() / tools_as_anthropic()
• Cookie/CMP dismiss, SPA settle budgets, stale-ref recovery, network intelligence
• Privacy defaults: mask Authorization / cookies in network logs

---

Bottlenecks & negatives (no sugarcoating)

We measure these so you don’t ship blind.

Honest product line:
Best as an LLM action + compact perception layer.
Not a replacement for bulk HTTP scraping, and not a captcha solver.

---

Architecture

┌──────────────────────────────────────────────────────┐
│  Claude · Cursor · LangGraph · OpenAI tool loop      │
└──────────────────────────┬───────────────────────────┘
                           │ MCP stdio  or  function tools
                           ▼
┌──────────────────────────────────────────────────────┐
│  agent-browser MCP  ·  tools_as_openai()             │
│  AgentSession: observe · click_text · wait · network │
└──────────────────────────┬───────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────┐
│  Semantic DOM · scoped grounding · outcomes · gates  │
│  Network monitor · memory · settle · overlay dismiss │
└──────────────────────────┬───────────────────────────┘
                           ▼
                 Playwright · Chromium

---

Installation

Requirements

• Python 3.11+
• Git
• ~Windows / macOS / Linux

Library + dev

git clone https://github.com/applejuice093/Agentic-browser.git
cd Agentic-browser
git checkout dev

python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate

pip install -e ".[dev]"
playwright install chromium
pytest -q

With MCP (Claude / Cursor)

pip install -e ".[mcp,dev]"
playwright install chromium

Optional vision (local OCR)

pip install -e ".[vision]"
# Install system Tesseract; set TESSERACT_CMD on Windows

Extras summary

---

Add to your agent (3 ways)

A) MCP — Claude Desktop / Cursor (recommended)

python -m agent_browser.mcp
# or
agent-browser-mcp

Cursor — .cursor/mcp.json (use your venv Python path):

{
  "mcpServers": {
    "agent-browser": {
      "command": "C:\\A\\PROJECT\\Agentic Browser\\.venv\\Scripts\\python.exe",
      "args": ["-m", "agent_browser.mcp"],
      "env": {
        "AGENT_BROWSER_HEADLESS": "true",
        "AGENT_BROWSER_MAX_TOKENS": "2000",
        "AGENT_BROWSER_ALLOWED_HOSTS": "github.com,example.com,quotes.toscrape.com"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "agent-browser": {
      "command": "C:\\A\\PROJECT\\Agentic Browser\\.venv\\Scripts\\python.exe",
      "args": ["-m", "agent_browser.mcp"],
      "env": { "AGENT_BROWSER_HEADLESS": "true" }
    }
  }
}

Full guide (env vars, system prompt, troubleshooting): docs/mcp.md

B) Python library

import asyncio
from agent_browser import Browser, tools_as_openai

async def main():
    async with Browser(headless=True) as browser:
        agent = await browser.open_agent("https://github.com/vercel/next.js")
        obs = await agent.observe(max_tokens=2000)
        if obs.page_gate not in (None, "open", "cookie_wall", "unknown"):
            print("Blocked:", obs.page_gate, obs.page_gate_hint)
            return
        result = await agent.click_text("Issues", scope="nav", intent="issues")
        print(result.ok, result.url_after, result.outcome_verified)

asyncio.run(main())

OpenAI / Anthropic tool schemas:

from agent_browser import tools_as_openai, tools_as_anthropic
tools = tools_as_openai()       # Chat Completions
# tools = tools_as_anthropic()  # Messages API

C) CLI

agent-browser version
agent-browser open https://example.com
agent-browser scrape https://example.com -o data/out.json

---

Core concepts

MCP / tool surface

browser_navigate · browser_observe · browser_click · browser_click_text · browser_type · browser_wait · browser_find · browser_network · browser_resync · browser_prepare

---

Environment variables

---

Project layout

src/agent_browser/
  browser.py / page.py / cli.py
  agent/          # AgentSession, MCP tools bridge, settle, overlays, grounding, outcomes, skills
  mcp/            # FastMCP stdio server
  observation/    # Compact observation builder
  semantic/ accessibility/ events/ network/ vision/ memory/ planning/
docs/
  mcp.md                 # Add to Claude / Cursor / custom agents
  USER_GUIDE.md
  agent-native-loop.md
  security.md
examples/
  agent_loop_demo.py
  openai_tool_agent.py
  mcp_config_cursor.json
  benchmark_hard_site.py
  compare_rockstar_vi.py
tests/                   # 118+ automated tests

---

Development

git checkout dev
pip install -e ".[dev,mcp]"
playwright install chromium
pytest -q
ruff check src tests

---

Roadmap status

---

Ethics

• Use only on sites and accounts you’re allowed to automate.
• No captcha/JS-challenge bypass — we detect and report gates.
• Respect robots.txt / ToS / rate limits for your use case.
• Prefer AGENT_BROWSER_ALLOWED_HOSTS in shared demos.

---

License

MIT — see LICENSE.

---

Small observations. Real clicks. Verified outcomes.
_{Agentic Browser · built for LLMs that have to act on the web}