Skip to main content
hexr.browser gives your agent access to a headless Chromium instance for tasks that require real-world web interaction — reading news sites, extracting structured data, taking screenshots for vision models, or filling out forms. Each browser session runs in a sandboxed container, destroys its cookies on exit, and is gated by OPA policies that restrict which domains your agent can access. This guide covers the three most common use cases: web research, visual analysis, and form submission.

​
Steps

1

Install and import the browser module

The browser module is included with the Hexr SDK. Import browse from hexr.browser:
web_researcher.py
from hexr import hexr_agent, hexr_llm
from hexr.browser import browse
2

Choose a use case and write your agent

Pick from the three patterns below based on what your agent needs to do:
from hexr import hexr_agent, hexr_llm
from hexr.browser import browse

@hexr_agent(name="web-researcher", tenant="acme-corp")
def main():
    # Browse a page and get structured content
    result = browse(
        url="https://news.ycombinator.com",
        actions=["extract_text"],
    )

    # Summarize with an LLM
    summary = hexr_llm(
        provider="openai",
        model="gpt-4o",
        prompt=f"Summarize the top stories:\n{result.text}",
    )
    print(summary)
3

Build and deploy

hexr build web_researcher.py --tenant acme-corp
hexr push && hexr deploy
The browser sidecar is automatically provisioned — no additional Helm values needed for basic use.

​
Available actions

ActionDescription
extract_textExtract all visible text content
extract_linksGet all hyperlinks
screenshotTake a PNG screenshot
fillFill a form field by CSS selector
clickClick an element by CSS selector
waitWait for an element to appear
scrollScroll the page

​
Security model

ProtectionDescription
Isolated browserRuns in a sandboxed container, separate from the agent process
No cookie persistenceSession cookies are destroyed after each browse() call
URL allowlistingOPA policies restrict which domains the agent can access
SPIFFE authenticatedBrowser access is tied to the agent’s SPIFFE identity
Use vault.get() instead of hardcoding credentials in fill actions. The vault is scoped to your agent’s SPIFFE identity and never exposes secrets in traces or logs.
Browser access to external domains is controlled by OPA policy. If your agent attempts to access a domain not in the allowlist, the request will be blocked. Configure allowed domains in your Helm values before deploying.

​
Next steps

Secure secrets

Store credentials for form submissions with SPIFFE-scoped Vault access.

Code execution

Process browser-extracted data with safely sandboxed code.

LLM observability

Trace vision model calls made with browser screenshots.

SDK reference

Full reference for hexr.browser.browse and all supported actions.