Browser agent
LAST RESORT, and it costs money: hands a plain-language task to a hosted AI browser agent (Browser Use) when no Bowmark function covers the site or a…
LAST RESORT, and it costs money: hands a plain-language task to a hosted AI browser agent (Browser Use) when no Bowmark function covers the site or a script against one failed. Returns a session id and a private link your user can open to watch and take over the live browser; later scripts poll it, answer its questions and stop it.
Also known as: browser agent, browser use, computer use, hosted browser agent, ai browser, do it in a browser, use the website for me, fallback browser, operate a website, web agent, browser automation, browser automation click, click element browser automation, click element in a browser, automate a browser
Call it
bowmark.browser_agent.start(options: StartBrowserAgentOptions): Promise<StartBrowserAgentResult>
bowmark.browser_agent.status(id: string, options?: BrowserAgentStatusOptions): Promise<BrowserAgentStatusResult>
bowmark.browser_agent.send(id: string, message: string, options?: SendBrowserAgentOptions): Promise<SendBrowserAgentResult>
bowmark.browser_agent.stop(id: string): Promise<StopBrowserAgentResult>
bowmark.browser_agent.list(options?: ListBrowserAgentsOptions): Promise<ListBrowserAgentsResult>
bowmark.browser_agent.watchLink(id: string): Promise<WatchLinkResult>Functions
| Function | What it does |
|---|---|
start | Starts a hosted browser agent on task and returns at once with its session id and a watchUrl. Use ONLY after the library had nothing for this site or a function failed — each turn… |
status | Reads a session: running, needs_input (relay question to your user, answer with send), idle (done — read result), failed, stopped or closed. Pass the previous cursor for… |
send | Sends the agent a follow-up in the same browser: an answer to its question, the go-ahead after your user took over, or a new instruction. |
stop | Stops the agent and shuts its browser; the watch link stops working. |
list | Lists this account's browser agent sessions (open ones by default) — check how many you're holding before starting a new one, especially when looping. |
watchLink | Makes a NEW watch link for an open session, for when the one from start was lost. |
Types
type BrowserAgentStatus = "running" | "needs_input" | "idle" | "failed" | "stopped" | "closed";
interface BrowserAgentQuestion {
kind: "question" | "takeover"; // takeover = a person must act in watchUrl (login, captcha)
question: string;
}
interface StartBrowserAgentOptions {
task: string; // plain language, name the site
backend?: string; // default "browser_use"
model?: string; // e.g. "claude-sonnet-5"; default "gpt-5.6-luna"
maxCostUsd?: number; // vendor spend ceiling per turn, default 2, max 25
proxyCountry?: string; // e.g. "us"
timeoutMs?: number;
}
interface StartBrowserAgentResult {
id: string; // keep this: status/send/stop take it
status: BrowserAgentStatus;
watchUrl: string; // private link to WATCH AND CONTROL the live browser — show it to your user only
backend: string;
model: string;
warnings: string[];
}
interface BrowserAgentStep { at: string; kind: "thinking" | "action" | "message"; text: string }
interface BrowserAgentStatusOptions {
cursor?: string; // from the previous status() — only newer steps return
waitMs?: number; // wait up to this long (max 60000) for the status to change
timeoutMs?: number;
}
interface BrowserAgentStatusResult {
id: string;
status: BrowserAgentStatus;
question: BrowserAgentQuestion | null; // set when status is "needs_input"
result: string | null; // the agent's answer for its last finished turn
error: string | null;
steps: BrowserAgentStep[];
cursor: string;
task: string;
backend: string;
model: string;
closed: boolean;
warnings: string[];
}
interface SendBrowserAgentOptions { interrupt?: boolean; timeoutMs?: number }
interface SendBrowserAgentResult { id: string; status: BrowserAgentStatus; warnings: string[] }
interface StopBrowserAgentResult { id: string; status: BrowserAgentStatus; warnings: string[] }
interface BrowserAgentSummary {
id: string; status: BrowserAgentStatus; task: string; backend: string; model: string;
question: BrowserAgentQuestion | null; createdAt: string; closedAt: string | null;
}
interface ListBrowserAgentsOptions { open?: boolean } // default true
interface ListBrowserAgentsResult { sessions: BrowserAgentSummary[]; warnings: string[] }
interface WatchLinkResult { id: string; watchUrl: string; warnings: string[] }
type CallOptions = {
timeoutMs?: number // per-provider budget in ms, default 30000, clamped to 1000-55000.
// A provider slower than this is DROPPED from the results and
// NAMED in warnings — never silently absent
}Examples
// run 1 — nothing in the library covers this site, so fall back
const s = await bowmark.browser_agent.start({ task: "On example-rentals.com, find the nightly price of a 2-bedroom for Oct 3-5" });
return { id: s.id, watch: s.watchUrl }; // show watchUrl to your user// a later run — wait for it to change, then act on it
const st = await bowmark.browser_agent.status("<id>", { waitMs: 60000 });
if (st.status === "needs_input") return st.question; // ask your user, then send()
if (st.status === "idle") { await bowmark.browser_agent.stop("<id>"); return st.result; }
return st.steps;Providers behind it
| Provider | |
|---|---|
browser_use | Browser Use |