PenterDocumentationBrowser Agent
Documentation

Browser Agent

Browser Agent lets a PENTER agent operate the scoped application while the operator can reason about browser state, network behavior and the action timeline alongside the rest of the engagement.

01

Use Browser Agent for stateful application work

Web testing often depends on navigation order, authentication state, form state and application-side behavior. Browser Agent keeps those interactions inside the same engagement rather than forcing the agent to reason from disconnected screenshots or raw HTTP alone.

Rendered state

Observe the current application state the agent is acting on.

Interaction

Navigate, inspect elements, click, type, press keys, scroll, reload and take snapshots.

Correlated context

Use browser results alongside network/console/tool context and the agent timeline.
02

Supported agent browser actions

ActionPurposeTypical inputs
navigateOpen a URL in the scoped browser.url
snapshotCapture current browser/application state for the agent.none
elementsInspect actionable/visible elements before interacting.none / current page
clickActivate a selected page element.selector
typeEnter text into an input/control.selector, text
pressSend a key such as Enter, Escape or navigation keys.key
scrollMove the page viewport.direction, amount
reloadReload the current page.none
Inspect before acting when selectors are uncertain
Prefer an element inspection/snapshot step before a click or type action when the page is dynamic. This makes the action easier to review and reduces accidental interaction with the wrong control.
03

Packaged Desktop downloads Browser Agent Chromium on first use

Playwright Chromium is intentionally not embedded in the Windows installer. The packaged Browser Agent uses a dedicated headless Chromium download stored under PENTER user data.

  • The first Browser Agent start shows the download size and waits for operator confirmation.
  • The browser zip is downloaded from the Playwright CDN into the PENTER user-data browser directory.
  • PENTER verifies the downloaded artifact against a pinned SHA-256 before using it.
  • Later launches reuse the installed browser instead of downloading it again.
  • Development builds use the Playwright browser installation from the local development environment.
Download hardening
The packaged downloader does not follow redirects to plain HTTP and does not honor arbitrary Playwright download-host override environment variables for this managed download path.
04

Browser state belongs to the engagement

Authentication cookies, navigation position and selected application state can materially change what the agent can see. Keep browser sessions aligned with the same workspace/authorization boundary.

  • Do not reuse an authenticated browser session across unrelated customer workspaces.
  • Confirm the visible host belongs to the current authorized engagement before active interaction.
  • Use snapshots/elements to ground the model in current state after major navigation changes.
  • For API-only verification, prefer a direct HTTP tool when a full browser is unnecessary.
05

Network, console and element-selection context

The Desktop Browser Agent view maintains dedicated network and console logs beside the rendered browser frame. The operator can open the inspector, switch between those views, and use Select element mode to turn a point in the rendered page into structured DOM context.

  • Select element resolves the DOM node at the clicked page coordinate and derives a CSS selector.
  • Selected context includes bounded element text/HTML and useful attributes such as id, name, type and href.
  • The selected element can be pinned into the wider PENTER browser/engagement context for later agent work.
  • Browser observations include new console messages and new network requests so UI actions can be correlated with application behavior.
  • The Browser Agent action loop has a bounded action limit rather than running without a ceiling.
06

Recommended Browser Agent workflow

StepActionReason
1Navigate to the authorized target.Establish browser context.
2Snapshot / inspect elements.Ground the agent in current UI state.
3Perform one bounded interaction.Keep causality clear.
4Inspect resulting state/network/console.Determine what actually changed.
5Repeat or switch to HTTP/tool verification.Use the cheapest reliable surface for evidence.
6Attach relevant evidence to the candidate finding.Preserve reproduction context.
07

Browser Agent troubleshooting

Browser Agent asks to download Chromium.
This is expected on first packaged use. Approve the managed download if you want Browser Agent functionality on that machine.
The page loaded but an element cannot be clicked.
Refresh the element list/snapshot first. Dynamic pages can replace DOM nodes and invalidate an older selector.
The browser is authenticated as the wrong user.
Stop using that state for the current engagement. Start a clean browser/workspace state rather than mixing identities.
A direct HTTP request would be simpler.
Use it. Browser Agent is most valuable when rendered state, navigation, JavaScript behavior or session flows matter.
Next step

Ready to get started?

Follow the setup guide, install the current approved Desktop release, and connect your account.