@capsuleer/browser

Web browsing module for Capsuleer agents. Search the internet via Google and read any webpage as clean, agent-readable markdown. The two tools work together — search() finds relevant pages, browse() reads them.

capsuleer install browser

Requires a Google Custom Search API key and Programmable Search Engine ID, supplied by Axon at capsule boot.

Setup

Create a Google Programmable Search Engine and enable it to search the entire web. Then get an API key from Google Cloud Console with the Custom Search API enabled.

Pass both to the capsule via env in your agent config:

capsule({
  name: "my-agent",
  env: {
    GOOGLE_API_KEY: process.env.GOOGLE_API_KEY!,
    GOOGLE_SEARCH_ENGINE_ID: process.env.GOOGLE_SEARCH_ENGINE_ID!,
  }
})

API

Search

const results = await browser.search("bun javascript runtime benchmarks")
// → {
//     query: "bun javascript runtime benchmarks",
//     total: 4210000,
//     results: [
//       { title: "Bun vs Node.js benchmarks", url: "https://...", snippet: "..." },
//       { title: "Runtime performance comparison", url: "https://...", snippet: "..." },
//       ...
//     ]
//   }

// Limit results (max 10, default 10)
const top3 = await browser.search("sqlite performance tips", { num: 3 })

Browse

const page = await browser.browse("https://bun.sh/docs/runtime/bunfig")
// → {
//     url: "https://bun.sh/docs/runtime/bunfig",
//     title: "bunfig.toml – Bun Docs",
//     markdown: "# bunfig.toml\n\nBun's per-project configuration file...",
//     byteLength: 8420,
//     durationMs: 312,
//   }

// Read the full content
console.log(page.markdown)

Scripts, styles, navbars, footers, iframes, and SVGs are stripped before conversion. What comes back is the readable content of the page — headings, paragraphs, lists, code blocks, and links.

Typical agent pattern

// 1. Search for relevant pages
const { results } = await browser.search("how to run PRAGMA optimize in sqlite")

// 2. Browse the most relevant result
const page = await browser.browse(results[0].url)

// 3. Reason about the content
console.log(page.markdown)

Observability

{ "ok": true, "op": "browser.search", "data": { "query": "bun benchmarks", "results": 10, "durationMs": 210 } }
{ "ok": true, "op": "browser.browse", "data": { "url": "https://...", "title": "Bun Docs", "bytes": 8420, "durationMs": 312 } }

Policy

const capsule = await Capsule({
  policy: {
    browser: {
      search: true,
      browse: { allow: ["https://*"], deny: ["http://*"] },  // https only
    }
  }
})

See the policy docs for the full rule syntax.

Notes

• browse() returns raw markdown — large pages can be verbose. Consider truncating or summarising if passing directly to an LLM context window.
• Google Custom Search is limited to 100 free queries/day. Beyond that, billing applies at ~$5/1000 queries.
• search() does not require browse() — snippets alone are often enough for simple factual lookups.