Run agent tasks: the hosted loop
Hand the agent a goal and let the hosted loop plan the steps. How task runs end, what the separate reviewer checks, and every option on the request.
Last updated:
State the goal, not the steps
A task is the hosted agent loop: you describe an outcome — find the invoice for March and download it — and the agent plans and executes the steps itself, observing the page between actions. You write no selectors and no loop.
Over plain HTTP the API answers 202 and you poll the run; both SDKs do the polling for you. runTask blocks until the run is terminal, while startTask returns immediately and hands you the run to poll.
Run a task from the SDK
Requires: api-key inference
import { Browserberg } from '@browserberg/sdk';
const bb = new Browserberg({
apiKey: process.env.BROWSERBERG_API_KEY!,
baseUrl: 'https://browserberg.com',
});
await using session = await bb.sessions.create({ ttlSeconds: 600 });
// runTask blocks until the run is terminal. The reviewer's verification is a
// SEPARATE model call against a re-scraped page: the agent never certifies
// its own success.
const run = await session.runTask({
task: 'Open https://example.com and report what the page heading says.',
maxSteps: 6,
});
console.log('status:', run.status);
console.log('answer:', run.answer);
console.log('reviewer:', run.verification?.thoughts ?? '(none)');
import os
from browserberg import Browserberg
bb = Browserberg(os.environ["BROWSERBERG_API_KEY"], base_url="https://browserberg.com")
with bb.sessions.create(ttl_seconds=600) as session:
run = session.run_task(
"Open https://example.com and report what the page heading says.",
max_steps=6,
)
print("status:", run.status)
print("answer:", run.answer)
status: completed
answer: The page heading says: "Example Domain".
reviewer: The page data now shows the heading 'Example Domain' on https://example.com, matching the agent's answer. Since the claim is of type `done` and the answer reports success, and the page evidence confirms it, the claim is valid.
Three ways a run ends
completed means the goal was reached. terminated means the agent or the reviewer concluded the task should stop — a portal that refuses, a form that cannot be submitted honestly. failed means the run could not proceed at all. The distinction matters: a terminated run is a decision, a failed run is a defect.
The verdict is never the agent grading itself. A separate reviewer call inspects a re-scraped page and answers whether the goal actually holds; its verification.thoughts come back on the run record.
Two options narrow what the agent can do. pinToStartSite removes navigation from the model's action schema entirely, so a hostile page cannot steer the agent off the portal — the action is structurally impossible, not merely discouraged. readOnly keeps the run to observation and extraction.
Task options
| Name | Type | Description |
|---|---|---|
task
required
|
string | What to achieve, in plain language. Up to 4000 characters. |
startUrl
|
string | Where the run begins. Without it, the agent starts on the session's current page. |
variables
|
object | Named values the task text can reference, kept out of the goal string itself. |
maxSteps
|
integer |
Upper bound on agent steps; the hard cap is 100.
Default: 25
|
maxFailures
|
integer | How many failed steps the run tolerates before giving up. |
pinToStartSite
|
boolean | Strips navigation from the action schema: the run stays on the start site. |
readOnly
|
boolean | Observation and extraction only; no clicks, no typing. |
timeoutSeconds
|
integer | Wall-clock limit for the whole run. |