> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Long-running tasks

> Design agentic web workflows with phases, budgets, retries, status, and blocker handling.

Long-running agentic web workflows need structure. Treat the agent run as one part of a workflow, not the whole system.

## Break work into phases

```text theme={null}
1. Prepare job context.
2. Run the browser agent for one scoped goal.
3. Validate output and source URLs.
4. Persist results.
5. Continue, retry, or ask for review.
```

Prefer several scoped runs over one vague prompt that tries to finish an entire business process.

## Set budgets

```ts theme={null}
const agent = web.agent({
  model,
  browser: { policy: { allowedDomains: ["sam.gov"] } },
  maxTurns: 12,
  maxToolCalls: 20,
  timeoutMs: 180_000,
  toolTimeoutMs: 30_000,
});
```

Budgets help your product fail clearly when a site is slow, blocked, or more complex than expected.

## Return blockers clearly

Do not treat a blocked run as a successful empty result. Persist the status, error, page evidence, and any artifacts.

```ts theme={null}
if (result.status === "blocked") {
  await db.agentRuns.update({
    where: { id: runId },
    data: {
      status: "blocked",
      summary: result.text,
      browserId: result.browserId,
    },
  });
}
```

## Use sessions for related runs

Use `agent.session(...)` when multiple related tasks should share one browser.

```ts theme={null}
const session = await agent.session({
  startUrl: "https://www.sec.gov/edgar/search/",
});

try {
  const company = await session.run("Find Apple's latest 10-Q filing.");
  const detail = await session.run("Open the filing detail page and summarize the exhibits.");
  console.log(company.text, detail.text);
} finally {
  await session.close();
}
```

## Production checklist

* Constrain domains.
* Request structured output.
* Set turn, tool, and time budgets.
* Stream progress for user-facing jobs.
* Store status, result, source URLs, and artifacts.
* Return blockers instead of inventing missing data.
* Require approval for high-impact actions.