Guides
Take control of a Browser Agent run
Pause a run, operate its browser, and return control to the agent.
Use version 0.11.0 or later of the JavaScript or Python SDK and a project API that exposes /v2/browser-agent. Create a v2 run with the same project credentials. To allow the agent to request help, set human_intervention_enabled to true at creation.
const { id } = await client.browserAgent.v2.runs.create({
query: 'Open example.com and summarize its heading',
human_intervention_enabled: true,
});receipt = client.browser_agent.v2.runs.create(
query="Open example.com and summarize its heading",
human_intervention_enabled=True,
)
run_id = receipt.idSet RUN_ID to the returned ID. Set LEXMOUNT_API_KEY and LEXMOUNT_PROJECT_ID in a private terminal, then run either example below. Show interactive URLs only to the operator and keep them out of shared logs.
- Operator-initiated pause. Pause a running task and poll until it reaches
paused. Open its currentpreview_url, finish the work, then resume with that pause’s ID. - Agent-initiated assistance. At
waiting_for_human, readintervention.instructionsand openintervention.urlif the task requires browser input. Confirm the handoff in the workspace before interacting. Submitresolvedto continue the same run orunresolvedto end it, using the current intervention ID. Enter passwords and verification codes directly on the destination page. Use the text response for task instructions only. - Changing state. If the interactive URL is unavailable, read the run again later. On 403, check project access. On 409, re-read the current state and IDs. A 202 acknowledges the request. Read the run again to check its status. For application-level retries of create, pause, resume, or complete, supply the same payload and key (
idempotencyKeyin Node.js,idempotency_keyin Python) from the first attempt.
Node.js
import { Lexmount } from 'lexmount';
import { createInterface } from 'node:readline/promises';
import { stdin, stdout } from 'node:process';
import { setTimeout as sleep } from 'node:timers/promises';
const client = new Lexmount({
baseURL: 'https://api.lexmount.cn',
projectId: process.env.LEXMOUNT_PROJECT_ID,
apiKey: process.env.LEXMOUNT_API_KEY,
});
const runs = client.browserAgent.v2.runs;
const id = process.env.RUN_ID; // ID of an existing v2 run
if (!id || !stdin.isTTY || !stdout.isTTY) throw new Error('Use a private terminal and set RUN_ID');
const terminal = createInterface({ input: stdin, output: stdout });
try {
let run = await runs.get(id);
if (run.status === 'running') await runs.pause(id);
for (let i = 0; i < 30; i++) {
run = await runs.get(id);
if (!['running', 'pausing'].includes(run.status)) break;
await sleep(1000);
}
if (run.status === 'paused' && run.pause && run.preview_url) {
await terminal.question(`Open ${run.preview_url} and press Enter after finishing: `);
await runs.resume(id, run.pause.id);
} else if (run.status === 'waiting_for_human' && run.intervention) {
const help = run.intervention;
console.log(help.instructions);
if (help.url) console.log(help.url);
const outcome = await terminal.question('Enter resolved or unresolved: ');
if (!['resolved', 'unresolved'].includes(outcome)) throw new Error('Invalid outcome');
const response = outcome === 'resolved' && help.response_required ? await terminal.question('Brief response: ') : undefined;
await runs.completeIntervention(id, help.id, { outcome, response });
} else {
console.log(`No handoff available (status: ${run.status}).`);
}
} finally {
terminal.close();
}Python
import os
import sys
import time
from lexmount import Lexmount
if not sys.stdin.isatty() or not sys.stdout.isatty():
raise SystemExit("Use a private terminal")
with Lexmount(base_url="https://api.lexmount.cn",
project_id=os.environ["LEXMOUNT_PROJECT_ID"],
api_key=os.environ["LEXMOUNT_API_KEY"]) as client:
runs = client.browser_agent.v2.runs
run_id = os.environ["RUN_ID"] # ID of an existing v2 run
run = runs.get(run_id)
if run.status == "running":
runs.pause(run_id)
for _ in range(30):
run = runs.get(run_id)
if run.status not in ("running", "pausing"):
break
time.sleep(1)
if run.status == "paused" and run.pause and run.preview_url:
input(f"Open {run.preview_url} and press Enter after finishing: ")
runs.resume(run_id, run.pause.id)
elif run.status == "waiting_for_human" and run.intervention:
help_request = run.intervention
print(help_request.instructions)
if help_request.url:
print(help_request.url)
outcome = input("Enter resolved or unresolved: ")
if outcome not in ("resolved", "unresolved"):
raise SystemExit("Invalid outcome")
response = input("Brief response: ") if outcome == "resolved" and help_request.response_required else None
runs.complete_intervention(run_id, help_request.id, outcome=outcome, response=response)
else:
print(f"No handoff available (status: {run.status}).")With AsyncLexmount, use the same method names and parameters inside async with. Await each SDK call and use await asyncio.sleep(1) between polls.
