← Blog

BLOG

Using Web Workflows with a Remote Browser Runtime

Using web workflows reliably means running real pages in an isolated browser. Learn how to connect agents, automate tasks, and operate safely.

10 min readRemote Browser
Ivory computer towers connected across terracotta platforms in a quiet desert landscape
The infrastructure behind your browserREMOTE BROWSER / ILLUSTRATION

Using web workflows in production means more than sending HTTP requests. It means loading real pages, preserving the right session state, interacting with rendered controls, handling navigation, and verifying that an action produced the expected result.

For simple data retrieval, an API or direct HTTP client is often the better tool. But when a workflow depends on JavaScript, authentication cookies, visual state, client-side navigation, file uploads, or multi-step interaction, a browser runtime is usually the correct execution layer.

A remote browser gives that workflow a managed Chromium session. Your application or AI agent controls the session through browser automation protocols such as CDP, Playwright, Puppeteer, or Selenium, while the browser runs outside your local machine.

What “using web” means in practice

Using web is a useful description for workflows where software must operate a website as a user would. The browser is not merely displaying HTML; it is maintaining state and executing the page’s application logic.

A typical workflow may need to:

  • Open a website and wait for client-side rendering.
  • Sign in with an existing authenticated profile.
  • Search, filter, sort, or paginate through results.
  • Complete a form with validation and conditional fields.
  • Upload or download a file.
  • Open a new tab or handle a redirect.
  • Confirm that a change was saved.
  • Preserve cookies or session state for a later task.
  • Capture structured output from a rendered page.

This distinction matters for AI agents. An agent can decide what to do, but it still needs a reliable runtime to perform actions and inspect outcomes. A language model should not be treated as the browser. The browser supplies the page state, DOM, network context, cookies, and interaction surface that the model needs to make grounded decisions.

A remote runtime is particularly useful when the agent runs in a serverless function, queue worker, container, or hosted service. Those environments may not have a durable display, an installed browser, persistent storage, or a safe way to keep sessions isolated.

Choose the right way to use web pages

The right method for using web depends on the interface you must operate and the amount of state involved. A browser is not automatically better than an API, and a remote browser does not remove the need for application-level reliability.

ApproachBest fitMain advantageMain trade-off
Direct API or HTTP clientStable, documented data and actionsFast, structured, and easy to testCannot reproduce browser-only behavior
Local browser automationDevelopment, debugging, and small controlled jobsSimple feedback loop and local visibilityYou manage browser installation, resources, and isolation
Remote browser runtimeHosted agents, workers, and production automationBrowser sessions run separately from application infrastructureRequires session lifecycle, connection, and usage management
Human-in-the-loop browser sessionSensitive approvals or ambiguous workflowsA person can review and interveneLower automation and higher operational coordination

Use an API when the website exposes the exact operation you need and the API is permitted for your use case. Use a browser when the workflow depends on the website’s user interface or browser state.

A practical decision test is:

  1. Can the task be completed with a stable, authorized API?
  2. Does the task require a logged-in browser profile?
  3. Does the page render important data only after JavaScript runs?
  4. Must the workflow interact with controls rather than retrieve records?
  5. Does the execution environment support a reliable, isolated browser?

If the answer to the first question is yes and the others are no, an API may be sufficient. If several of the remaining questions apply, a hosted browser is often a better fit. The remote browser for AI agents guide provides more context on where this runtime layer belongs in an agent architecture.

A reliable workflow for using web

A robust browser task should be designed as a sequence of observable state changes rather than a list of clicks. This makes failures easier to classify and reduces the chance that an agent continues after an unexpected page transition.

1. Create or select a session

Start with an isolated browser session. Decide whether the task needs:

  • A clean context for public pages.
  • A persistent profile containing approved cookies and preferences.
  • A proxy or other configurable browser setting for a specific network requirement.
  • A fixed region or browser configuration.
  • A live viewer for debugging or human review.

Do not share one authenticated profile across unrelated tenants or jobs. Session isolation is both a security boundary and a correctness feature: one task should not inherit another task’s cookies, tabs, or partially completed form.

2. Connect through a supported protocol

Your worker can connect to the hosted Chromium session over CDP and use a familiar automation library. Playwright, Puppeteer, and Selenium are useful choices when the rest of your application already uses one of them.

The connection endpoint should be treated as a secret. Keep it in a protected environment variable or secret manager, and avoid writing it to logs.

3. Observe before acting

Before clicking, inspect the current URL, title, visible text, and relevant controls. For an AI agent, this observation is the grounding step that converts a plan into an action based on the current page rather than an assumed page structure.

Prefer semantic locators where possible:

  • Role and accessible name for buttons and links.
  • Label for form controls.
  • A stable test identifier when the application provides one.
  • A narrowly scoped CSS or text locator as a fallback.

Avoid relying on the position of an element, generated class names, or a fixed delay. Those choices make workflows fragile when the page layout changes.

4. Wait for meaningful state

A page being loaded does not always mean that the task is ready. Wait for the specific state needed by the next action: a search result, a visible dialog, an enabled submit button, or a status message.

Use bounded timeouts and classify timeout failures. A timeout may indicate a slow page, an authentication redirect, a selector change, a blocked request, or an application error. Retrying every timeout blindly can duplicate a purchase, form submission, or other side effect.

5. Verify the result

Every important action needs a postcondition. After submitting a form, verify a confirmation message or destination URL. After downloading a file, verify that the expected file exists and has a plausible size or type. After updating a record, reload or inspect the resulting state when safe to do so.

Verification is especially important for agents because a successful click does not prove that the intended business action succeeded.

6. End or hand off the session

When the task is complete, close or release the session according to its ownership policy. Disposable tasks should not leave browser sessions running indefinitely. A persistent workflow may instead save the profile for an approved later step.

The Remote Browser documentation is the appropriate place to check current session and connection behavior before implementing a production worker.

TypeScript example: connect over CDP

The following example assumes your session provider has returned a CDP endpoint. Remote Browser supplies hosted Chromium sessions; the endpoint and session configuration should come from your application’s session-creation flow rather than being hard-coded.

import { chromium, type Page } from "playwright";

async function runTask(): Promise<void> {
  const cdpUrl = process.env.REMOTE_BROWSER_CDP_URL;

  if (!cdpUrl) {
    throw new Error("REMOTE_BROWSER_CDP_URL is not configured");
  }

  const browser = await chromium.connectOverCDP(cdpUrl);
  const [context] = browser.contexts();

  if (!context) {
    throw new Error("No browser context is available");
  }

  const page: Page =
    context.pages()[0] ?? (await context.newPage());

  try {
    await page.goto("https://your-app.example", {
      waitUntil: "domcontentloaded",
      timeout: 30_000,
    });

    const search = page.getByRole("searchbox");
    await search.fill("example query");
    await search.press("Enter");

    const result = page.getByRole("heading", {
      name: /results/i,
    });

    await result.waitFor({
      state: "visible",
      timeout: 15_000,
    });

    console.log({
      title: await page.title(),
      url: page.url(),
      result: await result.textContent(),
    });
  } finally {
    // Close or release the session according to your ownership policy.
    await browser.close();
  }
}

runTask().catch((error) => {
  console.error("Browser task failed", error);
  process.exitCode = 1;
});

This pattern uses an existing browser context instead of assuming that a new local browser can be launched. For the protocol details and connection limitations, see the official Playwright `connectOverCDP` documentation.

Production criteria for using web

A proof of concept can stop after a selector succeeds. A production workflow needs controls around the browser, the task, and the data moving through both.

Session and profile management

Persistent profiles are useful for workflows that require an approved login or stable preferences. They also increase the impact of a session leak. Define who owns each profile, which jobs can use it, and when its credentials should be rotated or revoked.

For multi-tenant systems, assign profiles and sessions by tenant or task boundary. Do not rely on an agent to remember which account it should use. Enforce that rule in the worker and session configuration.

Authentication and sensitive data

Keep credentials outside prompts and source code. If a task requires a login, use a controlled authentication step or an approved persistent profile. Redact cookies, authorization headers, personal data, and form values from logs.

Treat screenshots and live viewers as sensitive outputs. They may expose account details even when the underlying text logs are clean.

Reliability and recovery

Build explicit recovery paths for common browser failures:

  • The page redirects to a login screen.
  • A required control is absent.
  • A popup or new tab appears.
  • A consent dialog covers the intended control.
  • The remote connection drops.
  • A page exceeds its timeout.
  • The target site returns an error or rate limit.
  • The action may have succeeded even though the response was lost.

Use idempotency where the target application supports it. For irreversible actions, verify state before retrying. If the result is ambiguous, pause for review instead of submitting the same action again.

Observability

Record enough information to diagnose a failure without capturing secrets. Useful fields include:

  • Task and tenant identifiers.
  • Session identifier.
  • Start and end timestamps.
  • Current URL and page title.
  • Action name and outcome.
  • Timeout or connection category.
  • Whether a retry occurred.
  • Final business result.

Track browser usage separately from model usage. A task may spend most of its time waiting for a page, reconnecting, or handling a challenge rather than generating text. These measurements help you decide whether to optimize selectors, page flow, session lifetime, or model behavior. Review current limits and billing details on the pricing page rather than assuming a fixed allowance.

Site rules and operational boundaries

Only automate websites and accounts you are authorized to access. Respect terms, robots guidance where applicable, authentication policies, and rate limits. Configurable proxy or browser settings can help meet legitimate network requirements, but they should not be treated as permission to evade access controls.

The objective of using web in production is dependable task completion within an approved boundary, not maximizing the number of requests a browser can send.

A practical implementation checklist

Before moving a web workflow from a local script to a hosted runtime, confirm that you can answer these questions:

  • What exact browser state does the task require?
  • Is an API available and preferable for any part of the workflow?
  • Which profile or session may access the target account?
  • How are CDP endpoints stored and rotated?
  • Which selectors represent stable, user-visible controls?
  • What condition proves that each action succeeded?
  • Which failures are safe to retry?
  • How are ambiguous side effects handled?
  • What data is redacted from logs and screenshots?
  • When is the session closed, reused, or escalated to a person?
  • Which metrics show that the workflow is improving?

Using web becomes predictable when the browser is treated as infrastructure rather than an invisible side effect of an agent prompt. A hosted Chromium session supplies the execution environment; your code still owns authorization, task boundaries, verification, and recovery.

For teams deciding between local and hosted execution, remote browser online explains the operational model, while remote control browser covers the control path from an application or agent to a live browser session.