Introducing AgentFerrum - Browser automation for AI agents

[Florian95]

Hey all,

Sharing AgentFerrum, a gem I built on top of Ferrum for browser automation in an AI agent context.

The problem

I'm building AI agents that browse the web, and dumping raw HTML into the LLM context is wasteful. A typical web page is tens of thousands of tokens of noise (scripts, styles, hidden elements, data-* attributes). The agent needs to understand the page and interact with it, not parse a DOM.

What AgentFerrum does

The gem produces a hybrid snapshot: an accessibility tree of interactive elements (with clickable refs) + a markdown rendering of the visible content. In practice that's a 50-80% token reduction compared to raw HTML.

browser = AgentFerrum::Browser.new
browser.navigate("https://shop.example.com/cart")

snap = browser.snapshot
puts snap.to_s

# Shopping Cart
URL: https://shop.example.com/cart

## Interactive Elements
@e1: [link] "Home" href="/"
@e2: [textbox] "Search" value=""
@e3: [button] "Remove"
@e4: [button] "Checkout"

## Page Content
# Your Cart

| Product | Qty | Price |
|---------|-----|-------|
| Widget  | 2   | $20   |

Total: **$20.00**

The agent reads the snapshot, decides to checkout, clicks @e4. No CSS selectors needed.

browser.click("@e4")

Benchmark on real sites

Site	Raw HTML	Snapshot	Reduction
Hacker News	~8,600 tokens	~4,500 tokens	47%
Wikipedia	~140,000 tokens	~31,000 tokens	78%
GitHub	~265,000 tokens	~22,000 tokens	92%

What's inside

• Hybrid snapshots — Accessibility tree (via CDP Accessibility.getFullAXTree) + markdown (via ReverseMarkdown)
• Ref-based actions — Click, fill, select, hover via @e1, @e2... resolved through backendNodeId
• Visibility filtering — JS to strip hidden elements, Nokogiri to clean up noise attributes
• Stealth mode — 3 profiles (:minimal, :moderate, :maximum) ported from puppeteer-extra-plugin-stealth
• Download management — Configurable path, wait with timeout
• Smart waiting — Poll on CSS/XPath/text/block conditions
• AI-friendly errors — Error messages tell the agent what to do next

Install

gem "agent_ferrum"

Links

• RubyGems
• GitHub

Inspirations

agent-browser (Vercel) for the accessibility tree + refs concept, Crucible for the stealth/downloads patterns, and FerrumMCP for Ruby/Ferrum patterns.

About the name

I named it AgentFerrum as a nod to this project since it's built entirely on top of it. If the maintainers would prefer I don't use "Ferrum" in the name, just let me know and I'll happily rename it.

---

Happy to hear any feedback. Ferrum is really nice to work with — the direct CDP access is exactly what's needed for accessibility tree extraction. Thanks to the Ferrum team for the solid foundation!

[Florian95]

I named it AgentFerrum as a nod to this project since it's built entirely on top of it. If the maintainers would prefer I don't use "Ferrum" in the name, just let me know and I'll happily rename it.