Skip to content

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)');

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.

Read on

  • Observe, act, extract The verbs the loop is built from
  • Tasks reference Every field on the task run record
  • Building workflows When a repeatable process beats a one-off goal