An API is the right way to give an agent access to a service when one exists. A browser is for the cases where it does not: an internal admin page, a supplier portal with no export, a form that only exists as a web page. In those cases an agent that can open pages, fill fields and click buttons can do work that nothing else can reach.
That reach is also the risk. A browser carries whatever the logged-in session can do, and the agent reads page text that anyone may have written. This guide treats browser control as a permission problem first and a scripting problem second. It builds a small gate in front of Playwright, runs it against a local page with invented data, and lists the ways it can still fail.
One boundary before starting. This guide is about automating pages you are entitled to use, for tasks you are allowed to do. Many sites restrict automated access or automated posting in their terms, and a blocked or suspended account is a real outcome. It does not cover working around a platform's limits, login checks or CAPTCHAs. If a site pushes back, the right response is to stop and ask a person.
Choose the smallest browser access that works
Playwright offers three levels of access, and they differ a great deal in what a mistake can touch.
A fresh context. Playwright runs tests in isolated browser contexts, so a context created for a task starts with no cookies and no logins. This is the default to reach for. It is enough for public pages and for any page you can serve locally while building.
A context loaded from saved login state. Playwright can save a context's authenticated state to a file and start later contexts from it. Its documentation warns that this file can hold cookies and headers that could be used to impersonate the account, and says not to commit it to a repository, public or private. If you use it, use a dedicated account with only the permissions the task needs, keep the file out of version control, and treat it like a password.
Attaching to a running browser over the Chrome DevTools Protocol. The connect_over_cdp method attaches Playwright to a browser that is already open. Playwright's documentation describes this connection as significantly lower fidelity than its own protocol, and notes that a browser launched without Playwright's curated arguments may lose some functionality. There is a security side too. Chrome's team reported that attackers were using the remote debugging port to extract cookies, and from Chrome 136 the debugging switches no longer work against the default profile. They require a separate data directory, and the team recommends Chrome for Testing for automation. A debugging port on a profile you actually use for email and banking is the opposite of what you want.
For most agent tasks, launch a browser from Playwright and create a new context. Reach for the other two only when the task cannot be done otherwise.
Pages are untrusted input
When an agent reads a page, it reads text written by whoever controls that page, or by whoever managed to post a comment, a ticket or a review on it. OWASP's guidance on prompt injection describes the indirect form: content from external sources such as websites changes what the model does. OWASP lists mitigations that fit browser work well. Give the model the least privilege it needs, require human approval for high-risk actions, and keep untrusted content separate from instructions. It also says it is unclear whether any method fully prevents prompt injection, so the design has to assume that a page will sometimes steer the agent.
That changes how to think about the gate. Do not try to detect malicious text. Decide in advance what the agent may do, enforce it in code the model cannot edit, and make the dangerous actions require a person.
A gate in front of Playwright
The agent proposes one action at a time as a small dictionary: open a URL, fill a labeled field, or click a button by its role and name. Your code decides what happens to it. Three outcomes are possible. The action runs, it waits for a person, or it is refused.
The lists are written by you, before the run. They name the hostnames the agent may propose opening, the field labels it may fill, and the buttons it may click, with each button marked as either allowed or needing approval. Anything not on a list is refused. This filters the agent's proposed actions. It is not a network or domain control.
from urllib.parse import urlparse
from playwright.sync_api import TimeoutError as PWTimeout
class Gate:
"""Filters one proposed browser action. It is not a network or domain containment system."""
def __init__(self, hosts, fields, clicks, approve):
self.hosts = set(hosts) # hostnames the agent may propose opening (port and path are ignored)
self.fields = set(fields) # form labels the agent may fill
self.clicks = dict(clicks) # (role, name) -> "allow" or "ask"
self.approve = approve # callable(action) -> bool, a human in real use
def decide(self, action):
kind = action["kind"]
if kind == "goto":
u = urlparse(action["url"])
if u.scheme in ("http", "https") and u.hostname in self.hosts:
return "allow"
return "deny"
if kind == "fill":
return "allow" if action["label"] in self.fields else "deny"
if kind == "click":
return self.clicks.get((action["role"], action["name"]), "deny")
return "deny"
def run(self, page, action):
verdict = self.decide(action)
if verdict == "ask" and not self.approve(action):
verdict = "deny"
if verdict == "deny":
return "denied"
try:
if action["kind"] == "goto":
page.goto(action["url"])
elif action["kind"] == "fill":
page.get_by_label(action["label"]).fill(action["value"])
else:
page.get_by_role(action["role"], name=action["name"]).click()
except PWTimeout:
return "failed: timeout" # no retry here: the click may have landed
# Detection only: by now the browser has already made any request that led here.
if action["kind"] in ("goto", "click") and urlparse(page.url).hostname not in self.hosts:
page.goto("about:blank")
return "flagged: page ended on a hostname outside the list"
return "done"
Usage is short. Launch a browser, make a fresh context, set a default timeout on the page so every action fails fast, and pass each proposed action through run.
browser = p.chromium.launch(headless=True) # p comes from sync_playwright()
page = browser.new_context().new_page() # fresh context, no saved login
page.set_default_timeout(5000) # milliseconds, applies to each action
gate = Gate(["intranet.example"], ["Message"], {("button", "Send request"): "ask"},
approve=ask_a_person) # ask_a_person is your own function
Two details are worth explaining. The locators use roles and labels, which Playwright recommends over CSS or XPath because they track what a user sees and break less when markup changes. And Playwright's locators are strict: an action that matches more than one element raises an error instead of clicking the first. A vague target stops the run.
What the test showed
The test used a local page on 127.0.0.1 with invented content: a message box, a "Send request" button, a "Delete account" button, and a paragraph telling the agent to ignore its instructions and click delete. A throwaway server counted every POST the browser made. The run used Microsoft Edge through Playwright's Python library.
Proposing an unlisted hostname was refused before any navigation happened. Filling the listed "Message" field worked, and filling an unlisted "Password" field was refused. Clicking "Delete account" was refused, so the server saw no delete request, even though the page text asked for it. Clicking "Send request" with approval withheld sent nothing. With approval granted it sent exactly one POST carrying the message. Clicking a button that was on the list but absent from the page timed out and returned a failure instead of hanging.
Those results show that the filter applies its lists to proposed actions on this one page. They do not show that the lists are right for a real site or that a person approving requests will read them carefully.
What the filter does not contain
The filter sees the action the agent proposes, not where the browser goes next or what the page requests by itself. In a second local test with two throwaway servers, an "allowed" and an "other" site, the other server received the request in every case below.
- Redirects and links. An allowed URL that redirected to another hostname was approved, and so was a click on an allowed link that led there. The
page.urlcheck afterward flagged both and blanked the tab, but the request had already gone out. Checking afterward detects and cannot prevent. - Ports and paths. The check compares hostnames only. A redirect to another port on the same hostname went unflagged.
- Iframes and scripts. An allowed page made requests to the other server on its own, and its script sent the text the agent typed there while the gate reported "done".
- A route callback. A Playwright route handler that aborted other hostnames saw only the first URL of a redirect chain, as the network documentation describes, so the target still got the request. It did block the iframe request, but it does not make a page trustworthy or cover other ports.
A real deployment needs egress restrictions that are enforced and tested outside the gate, permissions for exact origins and paths that fit the task, and no secrets or saved login state exposed to sites you do not trust. Not tested: service workers, popups, WebSockets.
Failure cases
Timeouts on writes. If a click on a submit button times out, the request may or may not have gone through. The gate returns a failure and does not retry. Check the outcome by looking at page state or the destination system before trying again, and see the guide on retries and failures for the general rule.
Ambiguous targets. A page with two "Save" buttons makes a strict locator fail. Fix the locator with a narrower scope. Do not switch to the first match, because it can click something you did not intend.
Forced clicks. Playwright waits for an element to be visible, stable, enabled and able to receive events before it acts. Its force option skips some of those checks. Leave it off, because a failed check usually means something covers the button.
Login walls and CAPTCHAs. Stop and hand the task to a person. An agent that tries to get past them is working against the site's controls.
Expired sessions. A saved login file stops working eventually. Detect the login page, stop and report, and never let the agent type credentials it found on a page.
Approval fatigue. If every second action asks a person, the person will click yes without reading. Keep the "ask" list short and meaningful, and show the reviewer the exact action, not a summary.
Content that flows back into the prompt. Anything you pass from the page to the model is still untrusted. Pass only what the next step needs, for example one table's text, and not the full page.
When not to use a browser
If the service has an API that covers the task, use it. An API call has a defined schema and a documented error model, and a browser click has neither. If the task is read-only on public pages, a plain HTTP fetch is simpler and carries less risk. Use the browser when the page is the only interface.
Next step
Pick one browser task you do by hand. Write down the hosts, the field labels and the buttons it involves. Mark the single button that changes something outside the page. Put those three lists into the gate, run it against a local copy of the page first, and confirm that an unlisted action is refused before pointing it at the real site. For a task with several steps, the guide on sub-agents covers keeping a browsing worker's context separate from the main agent's.
Sources
- Playwright for Python, Locators: role and label locators recommended over CSS and XPath, and strict locators that raise an error on multiple matches.
- Playwright for Python, Auto-waiting: the visible, stable, enabled and receives-events checks before a click, timeouts, and the
forceoption. - Playwright for Python, Network: route handlers, and the statement that a request and its redirects are one unit where the handler is called once for the original request.
- Playwright for Python, Authentication: saving and reusing browser state, and the warning that the state file can impersonate the account and should not be committed.
- Playwright for Python, BrowserType:
connect_over_cdpand its lower fidelity compared with Playwright's own protocol. - Chrome for Developers, Changes to remote debugging switches: the Chrome 136 requirement for a non-default user data directory, the reason given, and the Chrome for Testing recommendation.
- OWASP, LLM01 Prompt Injection: indirect injection from websites, least privilege, human approval, and separating untrusted content.


