Open a browser
writ_browser_useOpens a real cloud browser for interactive website tasks like clicking, filling forms, or bypassing login walls; returns the first live page observation for you to drive step by step.
Instructions
A REAL CLOUD BROWSER FOR A TASK ON A WEBSITE: the user's own signed-in account (email, social, shop, bank or work portal — pass a persona_id from writ_personas; the password stays sealed in Writ, so never ask for a password), a click, form, submit, search inside an app, setting change or buy/book/post, or a page a plain fetch cannot open (login wall, 403, CAPTCHA).
OPENS a real cloud browser and returns the FIRST live page observation. It is NOT an autonomous agent — YOU are the brain and the driver (Writ runs no model here): do every step with writ_browser_act(session_id), turn by turn, until the task is done. Call writ_browser_use ONCE per task; never again for the same task, and never wait for it to finish anything.
RECORDING IS ALWAYS ON, SAVING IS ON DEMAND: every interaction you drive is recorded. If the user wants to REUSE the task ("record it", "so I can re-run it"), drive it the recordable way from the first action — a value they will want to change goes in as {{name}} with the real value in writ_browser_act inputs, the data goes out through an extract action — then writ_browser_save(name): its answer lists the steps, inputs and a run_example, and the workflow replays at zero AI cost (writ_run_workflow). Otherwise just finish the task and writ_browser_cancel — an open browser bills until it is closed.
WHAT YOU CAN DO IN IT: navigate, click, fill, type, select, press keys, scroll, switch tabs, upload a file, sign in (a persona's 2FA code is minted server-side); SEE the page (read_text, get_dom for the real HTML, inspect a selector, list_candidates for repeating rows, get_screenshot); read EVERY backend call the page makes (capture_network, then search/read them with writ_browser_network); run ANY JavaScript on the live page (evaluate_js) and call the site's backend from inside the session with its cookies (api_call); work a page whose content only appears after interaction.
NOT FOR: just READING a page, a few pages, or the top N items of a listing — that is writ_scrape (one call, 2-10s, no browser); collecting a site into a dataset (writ_crawl_site); turning a site into an API (writ_website_to_api, which opens the same browser bound to a build). A browser costs execution time for as long as it is open, so open one only when the task needs interaction.
The page comes back after every batch and on demand via writ_browser_context(section=page). FOLLOW THE USER'S DIRECTIONS and ASK the user directly in chat whenever you need a decision, a value to type, a credential, or a 2FA/OTP code — never guess or invent secrets (for a sensitive fill set data_key so the saved step keeps a placeholder, never the raw value). writ_browser_compose adds what the recorder cannot see (named functions, explicit steps, an input's description/default). Prefer replaying an existing saved workflow (writ_list_workflows -> writ_run_workflow) when one already does the task. BLOCKED BY A BOT WALL / CAPTCHA? A browser's exit IP is fixed once it opens, so cancel it (writ_browser_cancel) and reopen with use_residential=true. And before opening a browser at all, call writ_browser_sessions: an open one is warm and cheaper to continue than a new one.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Starting URL to open (required). | |
| goal | No | Optional label describing the task, for the run log and your own reference. Passing it does NOT make the tool carry out the task — you still drive every step yourself with writ_browser_act after this returns. | |
| persona_id | No | Saved identity to sign in with (list them with writ_personas). Required for sites behind a login with 2FA. A desktop persona ('device:…') opens the browser on its own desktop, which fills {{secret:username}} / {{secret:password}} / 2FA itself — you never see its values. | |
| use_residential | No | Open on the platform residential network (premium) for a site that blocks datacenter IPs or shows a bot wall / captcha. Default off (free); turn on when a plain open is blocked. | |
| execution_target | No | Where the session runs: 'cloud' (managed cloud fleet), 'auto' (prefer the user's OWN linked Writ desktop app when it is online, else cloud), or 'local' (REQUIRE their own desktop app). Running on the user's own machine keeps the session on their computer + IP and exposes nothing local to the cloud. Omit to use the account's default set in the Writ app. If a 'local' run reports local_agent_offline, their app is closed — tell them, and only pass execution_target='cloud' to re-run in the cloud if they agree. | |
| residential_country | No | Two-letter ISO country the residential exit should be in (e.g. 'us', 'fr') — for a site that serves a different page per country, or throttles foreign traffic. Omit for an automatic exit. Ignored unless the session egresses residential. |