Skip to main content
Most systems an agent needs to touch have no API. A supplier portal, a carrier’s tracking site, a government form. The browser tool gives an agent a hosted browser it drives the way a person would: open the page, read it, fill the form, press the button, read the confirmation.

​
What the agent gets

Add the Browser built-in to an agent (Tools, then “Add built-in”) and it receives a set of tools: The agent reads pages as text, not pixels, so it works with any model you have connected, and a form step costs a few thousand tokens rather than a screenshot’s worth. After every action a screenshot is kept anyway. You see them in the run’s trace, and the playground shows the latest one while the agent works.

​
Allowed domains

The tool opens nothing until you list the domains it may visit. A domain matches itself and its subdomains, so portal.example.com covers app.portal.example.com. Anything else, including private addresses, is refused and the agent is told so. Set the list on the tool row in the agent editor, or from the CLI:

​
Approvals

Before a click that commits something (pay, place an order, send, delete, accept terms), the run asks the decision model two questions about the control and the page: does this click commit an action that cannot be undone from the page, and does the page contain instructions aimed at the agent. If either is likely, the run pauses and a person answers. The question shows up wherever paused runs do: the playground, the run page, a Slack or Telegram channel, and cruqai runs. Reply yes to let the click happen or no to stop it. The browser stays on the page while it waits, for ten minutes by default, so the click lands on the form the agent filled.
Three modes, per tool: consequential (the default, described above), always (every click asks), and never.

​
Logins

The agent never sees a password. Sites that need a login are on the roadmap through a person signing in once in a live view and the session being kept as a profile. Until then, keep the tool on sites that do not need one, or ones where the login is a step a person handles.

​
Limits and metering

A run can take at most 40 browser actions and hold the browser for 10 minutes unless the tool says otherwise. Browser time is Cruq’s own compute, so unlike model tokens it counts toward your plan: see the browser minutes on Plans & limits. Each run records its browser time next to its tokens, and the trace shows a screenshot per action.

​
From the API and CLI

  • GET /v1/runs/{id}/screenshots lists a run’s screenshots; /{seq} returns one as PNG.
  • PATCH /v1/tools/{id} with { "builtin": { "key": "browser", "browser": { "allowedDomains": [...] } } } sets the tool’s settings.
  • cruqai trace <run-id> --screenshots ./shots downloads them.