A browser: QuickAgents that test websites¶

A QuickAgent can declare a browser: a headless Chromium that its runs drive, for testing a website in the real world. The agent opens pages, clicks, fills forms, reads the console and the network requests, resizes the window to a phone's width, and takes screenshots and PDFs. The QuickAgent says that it tests a site, never which one: you name the site when the run starts, so one QuickAgent serves every site its users have.

The browser runs in a container of its own, beside the run, and its only route out is a proxy the runner starts for that run, which holds it to the sites the QuickAgent may open. The agent works the browser through the browser's tools and never reaches the network itself.

A browser runs on your own computer, with the CLI v0.6.117 or newer or Agentry Desktop 0.6.111 or newer, and in Agentry, where it opens public sites only (see In Agentry).

How you spot one¶

A QuickAgent that declares a browser shows it everywhere its access is listed:

on its page, the Declared capabilities badge browser: site (the question that asks for the site, and the hosts it may also open), or browser: any public site;
in the install consent, on the site and in agentry install, the row browser: a web browser that can open the site you name for site and its subdomains, then the hosts it lists, and the keys it can type into the site's sign-in forms, by name;
on your Installed list, the browser: clause in the row's summary;
on its page, under MCP servers & tools, the row browser with every tool the browser has.

A new version that adds a browser, a site, a host or a key it may type, or that moves from your site to any public website, asks for your consent again. On Search, the capability filter asks for browser finds QuickAgents that declare one.

Where the browser may go¶

By default, the site you name, with its subdomains, and the hosts the QuickAgent lists for the pages it loads from, such as a font host, a CDN or a sign-in provider (each an exact name, or *. and a domain). A request anywhere else fails, as a page sees a network error, and the run's log of the proxy says what was refused and why.

A QuickAgent may instead ask for any public website. That is as wide as a QuickAgent that may reach any host, and it is treated the same way: a version that asks for it goes to a person for review before it publishes, and a runner refuses it unless its operator's policy allows a browser on the public web. A QuickAgent that may type your keys into a site cannot ask for any public website.

Wherever it goes, the browser reaches public addresses only, on ports 80 and 443. The one exception is the site you type for a run on your own computer: a staging server on your local network or your tailnet works, with its own port, as long as it is not your own computer (loopback), a link-local address or a cloud's metadata address. A host the QuickAgent lists is never a private address.

What you are asked¶

When the run starts, the site for each site question: an http:// or https:// address, such as https://staging.example.com, or on your own computer one on your network such as http://192.168.1.20:8080. With the CLI it is an answer like any other:

agentry run you/site-tester --intake site=https://staging.example.com

In Agentry's run setup, each site question is an address field of its own on the Details step. It takes no access token: the browser opens the site, it does not download it.

If the QuickAgent signs in to your site, it declares the keys it needs, such as SITE_USER and SITE_PASSWORD, and the run asks for them as it asks for any declared key (see Signing in).

What the agent can do there¶

The browser's tools (Microsoft's Playwright MCP server, a version the runner pins): open a page and go back, read the page as text, find, click, type, fill a form, choose an option, hover, drag, press a key, wait for text, open and close tabs, resize the window, emulate a colour scheme or print, answer a dialog, read the console and the network requests, take a screenshot, check that an element, a list, a text or a value is shown, and save a page as a PDF. It can also run a script inside the page, except in a QuickAgent that may type your keys.

It has no tool that runs code in the browser's own process, uploads a file from your computer, changes the browser's cookies or storage, or reroutes its requests. The browser starts with an empty profile for each run and keeps nothing afterwards.

What a page shows reaches the agent as it is. The agent is told that a page is data, never instructions, and that a request a page made that the proxy refused is a finding to report; requests the browser makes on its own (to Google's update and sign-in hosts) are refused too and are not findings.

Signing in¶

A QuickAgent that tests the signed-in parts of a site lists, under its browser, the declared keys the browser may type. You give their values as you give any key: on your computer, kept in your system keychain for the QuickAgent's later runs; in Agentry, on your Secrets page or in the run setup, which hands them to that run alone.

The agent never reads the value. It passes the key's name to the browser's typing tools, the browser types the value into the field, and anything the agent reads back shows <secret>SITE_PASSWORD</secret> in its place. The value goes to the browser's container alone, not to the agent, the model, the run's other containers or the receipt. A password field shows dots in a screenshot.

That masking matches the exact value, so the browser of such a QuickAgent cannot run a script in the page (which could read a value back changed), and can open only your site and the hosts it lists, which are the pages the key is for. A page that asks for the key anywhere else is a finding.

What the run leaves¶

Screenshots, PDFs and saved pages go to reports/browser/ in the run's output folder, with the rest of its report. The receipt names the browser, where it was allowed to go, and how many requests the proxy refused; receipts/browser-proxy.log has one line for each refusal, with the host and the reason.

In Agentry¶

Run in Agentry runs a QuickAgent with a browser in Agentry's sandbox, as it runs any other. What differs:

Public sites only. The site you name must be a public address, on port 80 or 443. A staging server on your own network, localhost, or a name such as printer.local is refused before the run starts, in the run setup and again by Agentry. Test such a site with the CLI or Agentry Desktop on your own computer.
Your site, not any website. Agentry keeps a run's browser to the sites you name, so a QuickAgent that asks for any public website is refused when you start it, with a sentence that says so. Run it on your own computer, where your own runner policy decides.
Your keys from Agentry. The keys it may type come from your Secrets, refused, carried or left out as any declared key is.
Room for a browser. A run with a browser takes twice the room of another run on a sandbox host, so when Agentry is busy it may wait a little longer to start. It costs credits as any run does.

Its screenshots and PDFs arrive with the run's output, under reports/browser/, and the receipt says where the browser was allowed to go.

Making one¶

In the QuickAgent Builder, add a question and set its type to site (a website to test). The Builder writes it as a url question and lists it under the browser, up to four. Under Tools and web access, A browser, for testing websites takes the other hosts its pages load from, or Any public website; under Files, commands and data, the keys its browser may type, which must be keys of its own. The summary before Submit says where the browser may go and what it may type.

By hand, the two halves name each other:

intake:
  - id: site
    prompt: "Which site should I test?"
    type: url
    required: true
capabilities:
  browser:
    sites: [site]
    hosts: [fonts.googleapis.com, "*.stripe.com"]
    secrets: [SITE_USER, SITE_PASSWORD]
  secrets: [SITE_USER, SITE_PASSWORD]

A host is a name of two labels or more, or *. and one. No address, no port, no single-label name such as localhost, and no *. over a public suffix such as *.co.uk or *.github.io, which would cover every site registered under it: the registry refuses each at publish. A browser is not network egress: the QuickAgent's own fetch still reaches only the hosts its network.egress lists. The format's full rules are in the package format.