← Blog

BLOG

AI Agent for Chrome: Runtime Architecture and Setup

How to give an AI agent for Chrome a real browser runtime: hosted Chromium, CDP wiring, session isolation, and production criteria.

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

An AI agent for Chrome is a model-driven loop that observes a page, decides on an action, and executes it against a real Chromium instance. The model is the easy part. The hard part is the browser it drives: where it runs, how it is isolated, how state persists between steps, and how you debug it when a task fails at step 14. This guide covers the runtime decisions behind a working Chrome agent, the CDP wiring that connects your AI agent for Chrome to a browser, and the production criteria that separate a demo from something you can leave running.

If you are still deciding whether you need a dedicated runtime at all, start with Remote browsers for AI agents. If you have already decided and need connection details, the documentation covers session creation and endpoints.

What "AI agent for Chrome" actually means

The phrase gets used for three different things, and conflating them causes most of the confusion in this space:

  1. A browser extension that adds an assistant to your local Chrome. The agent shares your tabs, cookies, and logged-in sessions. Great for personal use, unsuitable for automation you need to run repeatedly or in parallel.
  2. A local automation script using Playwright or Puppeteer. Your code launches Chrome on the same machine, drives it over CDP, and the model supplies decisions. This works until you need concurrency, isolation, or a machine that stays up.
  3. A hosted browser runtime. Chromium runs on a provider's infrastructure, your agent connects over CDP, and sessions are created and destroyed through an API. This is the shape that survives production.

Most teams building an AI agent for Chrome end up at option three, not because local Chrome is bad, but because the operational properties are different. A local Chrome instance is a single resource tied to one machine. A hosted session is an API call you can make per task, per user, or per parallel worker.

Why local Chrome breaks down for agents

Local Chrome is fine for a single agent doing a single task while you watch. It degrades in predictable ways once you scale:

  • Concurrency. Each agent needs its own browser context. Running twenty agents against one Chrome profile means shared cookies, shared tabs, and race conditions on navigation.
  • Isolation. An agent that clicks the wrong thing in your personal browser is a real problem. Agents need a disposable environment with no access to your logged-in accounts unless you deliberately grant it.
  • Uptime. Long-running agents need a browser that stays alive across worker restarts. A laptop that sleeps kills the session.
  • Observability. When an agent fails, you need the DOM at the failure point, a screenshot, console logs, and ideally a recording. Local Chrome gives you whatever you happened to log.
  • Environment drift. Chrome versions, extensions, and OS differences change agent behavior. A pinned hosted Chromium removes that variable.

None of these are model problems. They are runtime problems, and they are the reason hosted Chromium exists as a category.

The runtime architecture of a Chrome agent

A production Chrome agent has four layers. Understanding them separately makes debugging tractable.

Layer 1: The agent loop

The agent receives a task, observes the current page state (usually a DOM snapshot, accessibility tree, or screenshot), asks the model for the next action, executes it, and repeats. The loop terminates on success, failure, or a step budget. This layer is model-agnostic and framework-agnostic; browser-use, Stagehand, and custom loops all implement some version of it.

Layer 2: The control protocol

The agent does not talk to Chrome directly. It talks to the browser over the Chrome DevTools Protocol (CDP), usually through Playwright or Puppeteer. CDP is a JSON-based protocol over WebSocket that exposes domains for page navigation, DOM inspection, input events, network interception, and runtime evaluation. The Chrome DevTools Protocol documentation is the authoritative reference for what each domain exposes.

Layer 3: The browser session

A session is a running Chromium process with its own profile directory, its own network stack, and its own lifecycle. Hosted runtimes expose sessions through an API: create one, get a CDP endpoint, connect, do work, stop it. Session isolation means one agent's cookies and storage never leak into another's.

Layer 4: The infrastructure

This is everything below the session: the container or VM the browser runs in, the proxy configuration, the network egress, the storage for recordings and profiles, and the metering that tracks how long each session ran. This layer is what you are actually buying when you use a hosted runtime.

Connecting an agent to Chrome over CDP

The connection is the part most teams get wrong on the first attempt. Playwright's connectOverCDP is the standard entry point for a hosted Chromium endpoint. The pattern below creates a session, connects, runs a task, and tears down cleanly.

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

interface SessionInfo {
  cdpUrl: string;
  sessionId: string;
}

// Your runtime provider returns a CDP WebSocket endpoint per session.
async function createSession(): Promise<SessionInfo> {
  const res = await fetch(`${process.env.BROWSER_API_URL}/sessions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.BROWSER_API_KEY}`,
    },
    body: JSON.stringify({
      // Configurable browser settings: region, proxy, viewport, profile reuse.
      profile: "checkout-agent",
      timeoutSeconds: 600,
    }),
  });
  if (!res.ok) throw new Error(`session create failed: ${res.status}`);
  return res.json();
}

async function runTask(task: string) {
  const { cdpUrl, sessionId } = await createSession();
  let browser: Browser | undefined;

  try {
    browser = await chromium.connectOverCDP(cdpUrl);
    const context = browser.contexts()[0] ?? (await browser.newContext());
    const page: Page = context.pages()[0] ?? (await context.newPage());

    await page.goto("https://example.com", { waitUntil: "domcontentloaded" });

    // Hand the page to your agent loop. The loop reads state,
    // asks the model for an action, and executes it via page.* calls.
    await runAgentLoop(page, task);

    return { sessionId, status: "ok" };
  } finally {
    // Disconnect the client; the session lifecycle is managed by the API.
    await browser?.close();
  }
}

Two details matter here. First, connectOverCDP attaches to an existing browser rather than launching one, so you must not call chromium.launch(). Second, closing the Playwright client does not necessarily stop the remote session; session termination is a separate API call or a timeout. Check your provider's semantics before assuming cleanup is automatic.

For a deeper walkthrough of the connection layer, see Remote control browser.

Choosing between local Chrome, a cloud VM, and a hosted runtime

The comparison below is the decision most teams actually face. It is not about which option is "best" in the abstract; it is about which operational properties you need.

CriterionLocal ChromeSelf-managed cloud VMHosted browser runtime
Setup timeMinutesHours to daysMinutes
Per-task isolationManual (contexts)Manual (containers)Built into session API
ConcurrencyLimited by one machineLimited by your orchestrationBounded by plan; see pricing
Persistent profilesNative, but sharedYou build the storage layerConfigurable per session
Live debuggingDevTools on your machineSSH plus remote DevToolsViewer plus CDP endpoint
Proxy and network controlOS-levelFull controlConfigurable browser settings
Version pinningWhatever you installedYou manage imagesProvider-managed Chromium
Cost modelHardware plus your timeVM hours plus your timePer browser-hour
Failure recoveryManual restartYour orchestrationSession recreation via API

The honest trade-off: a self-managed VM gives you maximum control and is the right answer if you have strict data residency requirements or need kernel-level customization. A hosted runtime trades some of that control for a session API, isolation guarantees, and the absence of browser infrastructure work. For most agent teams, the infrastructure work is not the differentiator, so the hosted path wins on time to production.

Production criteria for a Chrome agent runtime

When you evaluate a runtime, these are the properties that determine whether your agent holds up under real load. Ask for each one explicitly.

Session isolation and lifecycle

Every task should get a fresh session unless you deliberately want continuity. Isolation must cover cookies, local storage, cache, and network identity. The lifecycle should be explicit: create, use, stop. Sessions that linger after a task completes are wasted spend and a potential data leak.

Persistent profiles

Some agents need to stay logged in across runs: a support agent that checks a dashboard, a monitoring agent that polls an internal tool. Persistent profiles let you reuse authentication state without re-running the login flow every time. The runtime should let you name a profile, attach it to a session, and control whether changes persist. See the documentation for how profile attachment works.

CDP fidelity

A hosted browser is only useful if it behaves like the Chrome your agent was tested against. That means full CDP coverage for the domains your agent uses: Page, Runtime, Network, DOM, Input, and Target. Partial CDP implementations cause subtle failures, especially around network interception and multi-target handling.

Observability

You need three things when an agent fails: a live view of the session while it runs, a recording or screenshot at the failure point, and access to console and network logs. A live viewer is not a luxury; it is how you tell the difference between a model error and a page error in under a minute.

Network and proxy configuration

Agents that hit geo-restricted content or need stable egress IPs depend on proxy configuration. The runtime should let you set proxies per session and expose the resulting network identity so you can verify it. Be precise about what you need: different proxy types and static IPs solve different problems, so match the option to the task rather than assuming one fits all.

Usage controls and cost visibility

Browser time is the unit of cost. You want per-session metering, the ability to cap session duration, and a clear view of what each task consumed. Refer to pricing for current rates rather than assuming a number; browser-hour costs vary by provider and plan.

Common failure modes and how to avoid them

The agent connects but every action times out. Usually a CDP endpoint mismatch: you connected to the browser-level endpoint but are issuing page-level commands without a target. Verify you are operating on a page from context.pages() rather than the browser object.

Sessions leak between tasks. Either you are reusing a profile unintentionally, or the runtime is not isolating storage. Confirm that each task creates a new session and that profile attachment is explicit.

The agent works locally but fails on the runtime. Version drift is the usual cause. Pin the Chromium version your agent was tested against, or test against the runtime's version before shipping.

Long tasks die mid-run. Session timeouts are often shorter than agent tasks. Set the session timeout to exceed your worst-case task duration, and implement a checkpoint so a failed session can resume rather than restart.

Costs spike unexpectedly. Parallel agents that never terminate are the classic cause. Enforce a step budget in the agent loop and a hard session timeout in the runtime. Both, not either.

When a hosted runtime is the wrong choice

Hosted Chromium is not universally correct. It is the wrong choice when:

  • Your agent must run inside a customer's network with no external egress.
  • You need kernel-level or OS-level customization that the provider does not expose.
  • Your workload is a single daily task where a local script is genuinely sufficient.
  • Regulatory constraints require you to control the entire stack, including the browser binary.

In those cases, a self-managed VM with Playwright is the right answer, and the CDP wiring above still applies; only the endpoint changes.

Getting started

The shortest path to a working AI agent for Chrome is: pick a runtime, create a session, connect with connectOverCDP, and run your agent loop against the page. Start with a single task, add a live viewer, and only then add concurrency. The failure modes above are all observable if you have the viewer and the logs; they are invisible if you do not.

For the full setup sequence, including session creation, profile attachment, and teardown, see the documentation. For a broader look at how hosted browsers fit into agent stacks, read Remote web browser.