{"slug": "using-lightpanda-with-agent-browser", "title": "Using Lightpanda with agent-browser", "summary": "Vercel's agent-browser CLI now supports Lightpanda as an alternative browser engine, offering 9x faster performance and 16x less memory usage than Chrome for AI agent workflows. By using Lightpanda's headless engine, agents achieve higher accuracy on benchmarks like AssistantBench and GAIA Level 1 while reducing token consumption per snapshot.", "body_md": "# Using Lightpanda with agent-browser\n\n### Katie Brown\n\n#### Cofounder & COO\n\n## TL;DR\n\n[agent-browser ](https://github.com/vercel-labs/agent-browser) is Vercel’s browser automation CLI for AI agents. Point it at\nLightpanda with `--engine lightpanda`\n\nand your existing workflow runs on an\nengine that starts instantly, runs faster and uses far less memory than Chrome.\nThis post covers best practices and includes a demo to try yourself.\n\n## Why use agent-browser with Lightpanda\n\nagent-browser gives an agent a clean way to act on the web. You navigate to a\npage, take a snapshot, and get back a compact accessibility tree where every\nelement has a short ref like `@e1`\n\n. The agent reads that, picks a ref, and clicks\nor fills it. The text output runs around 200 to 400 tokens per snapshot instead\nof the 3,000 to 5,000 you would spend dumping raw DOM.\n\nUnderneath, agent-browser talks to a browser over the Chrome DevTools Protocol (CDP). By default that browser is Chromium. Lightpanda speaks CDP, so agent-browser manages it the same way: it spawns the process, connects over CDP, and shuts it down. Every downstream command works through the same path.\n\nLightpanda’s engine is the reason to swap. It skips the graphical rendering\nthat Chrome carries, so it runs [9x faster and uses 16x less memory ](https://lightpanda.io/blog/posts/from-local-to-real-world-benchmarks) on\nequivalent workloads. For an agent that loops through hundreds of pages per\ntask, reading structure and acting on it rather than looking at pixels, it\ndoesn’t need Chrome’s rendering pipeline. An agent that only handles what it\nneeds is faster and more accurate, because there’s less in front of it to get\nwrong.\n\nWe measured this by running agent-browser on both engines through\nAssistantBench and GAIA Level 1, with Claude Sonnet 4.6 as the model held\nconstant. agent-browser wrapping Lightpanda hit 0.606 strict accuracy on\nAssistantBench and 0.887 on GAIA Level 1, ahead of the same tool surface on\nChrome. You can read the [full benchmark\nwriteup ](https://lightpanda.io/blog/posts/benchmarking-lightpanda-for-agents)\nand reproduce it from the [open harness ](https://github.com/lightpanda-io/agent-benchmarks).\n\n## Set the engine once, not on every command\n\nYou can pass `--engine lightpanda`\n\non every call. If it’s your default, set it once instead.\n\nThe environment variable is the cleanest option for a shell session or a CI job:\n\n```\nexport AGENT_BROWSER_ENGINE=lightpanda\nagent-browser open example.com\nagent-browser snapshot -i\n```\n\nFor a project that should always use Lightpanda, put it in `agent-browser.json`\n\nso every contributor gets the same behaviour.\n\nIf the `lightpanda`\n\nbinary is not on your `PATH`\n\n, point at it explicitly with\n`--executable-path /path/to/lightpanda`\n\n. Otherwise, agent-browser finds it by\nname.\n\n## The snapshot, ref, act, re-snapshot loop\n\nThis is the core workflow, and it’s the same on Lightpanda as on Chrome. Open a page, snapshot it, act on a ref, then snapshot again before the next action.\n\n```\nagent-browser open https://example.com\nagent-browser snapshot -i\n# - heading \"Example Domain\" [ref=e1]\n# - link \"Learn more\" [ref=e2]\nagent-browser click @e2\n```\n\nRefs are tied to a single snapshot. The moment the page changes, those refs are\nstale. If you click a link that navigates, the old `@e2`\n\nno longer means\nanything. Take a fresh snapshot to get new refs before you act again.\n\n```\nagent-browser click @e1      # this navigates\nagent-browser snapshot -i    # get fresh refs for the new page\nagent-browser click @e3      # safe to act now\n```\n\nThe browser persists between commands through a background daemon, so chaining\nis cheap. You can join a sequence with `&&`\n\nin one shell call and it stays\nfast:\n\n```\nagent-browser open example.com && agent-browser snapshot -i\n```\n\n## Reach for snapshots, not screenshots\n\nThis is where the engine difference matters. Because Lightpanda has no graphical rendering engine, if you ask it for a screenshot you’ll get a placeholder image. That’s by design.\n\nPlenty of workflows rely on screenshots: capture the page, overlay numbered\nboxes, send the image to a vision model, and ask it where to click. That works,\nand for some tasks it’s the right call. But it’s worth testing the snapshot\npath first, because skipping vision could cut latency and token cost. The\n`snapshot -i`\n\naccessibility tree already tells the model what’s on the page and\ngives it a ref to act on.\n\nIf you’re building on Lightpanda, ground your agent in the snapshot and the get commands rather than the camera:\n\n```\nagent-browser get title\nagent-browser get url\nagent-browser get text \"#main\"\n```\n\nIf your task genuinely needs a rendered image, that is your signal to fall back to Chrome for that step. More on that below.\n\n## Run wide in CI and at scale\n\nInstant startup and a small memory footprint change what you can do with concurrency. A fleet of headless Chrome instances is the part of an automation or testing stack that leaks memory and needs scheduled restarts. Lightpanda was built for sustained automation, so you can run more sessions at once.\n\nCI runners are resource-constrained. [agent-browser’s own docs ](https://agent-browser.dev/engines/lightpanda) call out\nLightpanda as a good fit for fast scraping, agent workflows where speed and low\nmemory matter, CI with constrained resources, and high-volume parallel\nautomation.\n\n## Fallback to Chrome\n\nLightpanda is purpose-built and headless-only, so the following Chrome features are not supported:\n\n- Extensions (\n`--extension`\n\n) - Persistent profiles (\n`--profile`\n\n) - Saved storage state (\n`--state`\n\n) - File access (\n`--allow-file-access`\n\n)\n\nagent-browser gives you a clear error if you combine `--engine lightpanda`\n\nwith a\nflag it cannot honour, so you find out immediately rather than halfway through\na run.\n\nThe good news is that the fallback costs you almost nothing. The commands are identical across engines. If a task needs full browser fidelity, a real screenshot, a persistent login profile, or an extension, you switch back to Chrome by changing one flag. A common pattern is to run the bulk of your workload on Lightpanda for speed and cost, then route the few steps that truly need rendering to Chrome.\n\n## Try it yourself\n\nHere is a complete session you can paste into a terminal. It installs both tools, runs the snapshot-act loop against a real site, and extracts data.\n\nInstall Lightpanda from [the latest\nnightly ](https://github.com/lightpanda-io/browser/releases/tag/nightly) with\nthe one-liner:\n\n```\ncurl -fsSL https://pkg.lightpanda.io/install.sh | bash\n```\n\nInstall agent-browser and select Lightpanda as the engine:\n\n```\nnpm install -g agent-browser\nexport AGENT_BROWSER_ENGINE=lightpanda\n```\n\nNow the demo. Open Hacker News, snapshot it to see the refs, then pull the top headlines straight from the rendered DOM:\n\n```\nagent-browser open https://news.ycombinator.com\nagent-browser snapshot -i\nagent-browser eval \"[...document.querySelectorAll('.titleline > a')].slice(0,10).map((a,i)=>(i+1)+'. '+a.textContent).join('\\n')\" | node -pe \"JSON.parse(require('fs').readFileSync(0))\"\nagent-browser close\n```\n\n`snapshot -i`\n\nreturns a compact tree of every link on the page, each with a ref\nthe agent can act on. The output looks like this:\n\n```\n- link \"Hacker News\" [ref=e2]\n- link \"new\" [ref=e3]\n- link \"Om Malik has died\" [ref=e12]\n- link \"om.co\" [ref=e13]\n- link \"68comments\" [ref=e17]\n- link \"An entire Herculaneum scroll has been read for the first time\" [ref=e19]\n...\n```\n\nThe snapshot gives the agent the page structure. The `eval`\n\nline reads the\nrendered DOM after JavaScript has run and returns the top headlines.\nagent-browser hands the result back as a JSON string, so `node`\n\nprints it as\nclean lines:\n\n```\n1. Om Malik has died\n2. We All Depend on Open Source. We Will Defend It Together\n3. An entire Herculaneum scroll has been read for the first time\n4. Framework's 10G Ethernet module exposes USB-C's complexity\n...\n```\n\nThe page stays loaded between commands through a background daemon, and close ends the session.\n\n## FAQ\n\n### What is agent-browser?\n\nagent-browser is an open-source browser automation CLI from Vercel, built for AI agents. It drives a browser over CDP and returns pages as compact accessibility-tree snapshots with short element refs, so an agent can act on a page using a few hundred tokens instead of parsing raw HTML. It works with Claude Code, Cursor, Codex, and any agent that can run shell commands.\n\n### How do I use Lightpanda as the engine?\n\nPass `--engine lightpanda`\n\non a command, set `AGENT_BROWSER_ENGINE=lightpanda`\n\nin\nyour environment, or add `\"engine\": \"lightpanda\"`\n\nto `agent-browser.json`\n\n.\nagent-browser then spawns Lightpanda and connects over CDP.\n\n### Why use Lightpanda instead of Chrome with agent-browser?\n\nLightpanda runs 9x faster and uses 16x less memory than headless Chrome because it has no rendering pipeline. Under the same agent-browser tool surface in our benchmarks, the Lightpanda engine cut GAIA Level 1 wall time per task by 29% and quartered the timeout rate. For agent loops, scraping, and CI, that is lower cost and fewer failed runs.\n\n### Do screenshots work with Lightpanda?\n\nNo. Lightpanda has no graphical rendering engine, so a screenshot returns a\nplaceholder image. Ground your agent in `snapshot -i`\n\nand the `get`\n\ncommands\ninstead. If a task truly needs a rendered image, switch that step to the Chrome\nengine.\n\n### When should I fall back to Chrome?\n\nUse Chrome when you need full browser fidelity: real screenshots, browser extensions, persistent login profiles, or saved storage state. The commands are identical across engines, so switching is a one-flag change. Many teams run the bulk of a workload on Lightpanda and route only the rendering-dependent steps to Chrome.\n\n### Katie Brown\n\n#### Cofounder & COO\n\nKatie led the commercial team at BlueBoard, where she met Pierre and Francis. She rejoined them on the Lightpanda adventure to lead GTM and to keep the product closely aligned with what developers actually need. She also drives community efforts and, by popular vote, serves as chief sticker officer.", "url": "https://wpnews.pro/news/using-lightpanda-with-agent-browser", "canonical_source": "https://lightpanda.io/blog/posts/using-lightpanda-with-agent-browser", "published_at": "2026-06-26 00:00:00+00:00", "updated_at": "2026-06-26 14:34:59.793814+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools"], "entities": ["Vercel", "Lightpanda", "agent-browser", "Chrome", "Claude Sonnet", "AssistantBench", "GAIA"], "alternates": {"html": "https://wpnews.pro/news/using-lightpanda-with-agent-browser", "markdown": "https://wpnews.pro/news/using-lightpanda-with-agent-browser.md", "text": "https://wpnews.pro/news/using-lightpanda-with-agent-browser.txt", "jsonld": "https://wpnews.pro/news/using-lightpanda-with-agent-browser.jsonld"}}