Common Use Cases

The five jobs people bring to Kernel, with a working shape for each

Each section below is a working shape for one job — what to configure, what to run, and the failure mode to plan for. They assume KERNEL_API_KEY is set and you’ve been through the quickstart.

Web agents

The job: a model decides what to do on a page it hasn’t seen before.

The shape: playwright execution as the agent’s default tool, computer controls as the fallback when a step doesn’t respond to a selector, and one browser per task with a timeout_seconds safety net.

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();
const browser = await kernel.browsers.create({ stealth: true, timeout_seconds: 600 });

// Tool 1: give the model a way to run a script and get data back.
async function runScript(code: string) {
  const { result } = await kernel.browsers.playwright.execute(browser.session_id, { code });
  return result;
}

// Tool 2: give the model a way to look, and to act on what it sees.
async function screenshot() {
  return kernel.browsers.computer.captureScreenshot(browser.session_id);
}

async function click(x: number, y: number) {
  return kernel.browsers.computer.clickMouse(browser.session_id, { x, y });
}

try {
  await runScript(`await page.goto('https://example.com');`);
  // ... your agent loop, calling the three tools above
} finally {
  await kernel.browsers.deleteByID(browser.session_id);
}

Plan for: the model looping on a step that can’t work. Cap the number of turns, and give it the live view URL so a person can see what it’s stuck on. Replays turn a failed run into something you can review afterwards.

Skip writing the tool layer yourself with Browser Loop, which ships this catalog with per-model compatibility handled.

Data extraction

The job: pull structured data off pages, repeatedly, at volume.

The shape: one playwright execution call per page — return the data, don’t stream the DOM to your machine — a browser pool so you’re not paying creation latency per page, and proxies to spread load across exit IPs.

await kernel.browserPools.create({
  name: 'scrape',
  size: 20,
  timeout_seconds: 600,
  stealth: true,
});

async function scrape(url: string) {
  const browser = await kernel.browserPools.acquire('scrape', { acquire_timeout_seconds: 30 });
  try {
    const { result } = await kernel.browsers.playwright.execute(browser.session_id, {
      code: `
        await page.goto(${JSON.stringify(url)}, { waitUntil: 'domcontentloaded' });
        return await page.$$eval('[data-product]', (els) => els.map((el) => ({
          title: el.querySelector('h3')?.textContent?.trim(),
          price: el.querySelector('[data-price]')?.textContent?.trim(),
        })));
      `,
    });
    return result;
  } finally {
    await kernel.browserPools.release('scrape', { session_id: browser.session_id, reuse: true });
  }
}

Plan for: blocks rather than errors. A site that starts returning a challenge page looks like a successful scrape with zero rows. Assert on row count, and watch the CAPTCHA and proxy telemetry events. Concurrency and create-rate ceilings are per plan — see concurrency and limits.

Form fill

The job: put data into a form a person would normally fill in.

The shape: playwright execution for the fields, computer controls for the widgets that fight you (custom dropdowns, date pickers, canvas-based signature fields), and a verification read before you submit.

await kernel.browsers.playwright.execute(browser.session_id, {
  code: `
    await page.goto('https://example.com/apply');
    await page.fill('#full-name', 'Ada Lovelace');
    await page.fill('#email', '[e-mail]');
    await page.selectOption('#country', 'GB');
  `,
});

// Read it back before submitting — this is the step people skip.
const { result: filled } = await kernel.browsers.playwright.execute(browser.session_id, {
  code: `return { name: await page.inputValue('#full-name'), country: await page.inputValue('#country') };`,
});

if (filled.name !== 'Ada Lovelace') throw new Error('form did not take the value');

await kernel.browsers.playwright.execute(browser.session_id, {
  code: `await page.click('button[type=submit]'); await page.waitForURL('**/thanks');`,
});

Plan for: silent rejection. A field that a React component controls can accept fill() and then reset on blur. Read values back, and fall back to computer controls typing for anything that won’t hold.

For checkouts, don’t handle card data yourself — see payments in browser agents.

Authenticated workflows

The job: the work is behind a login, and you don’t want credentials in your agent’s context.

The shape: managed auth performs the login once and writes the session into a profile; every later browser attaches that profile and starts logged in. Kernel health-checks the connection and reauthenticates supported flows in the background.

// Once per end user, per domain.
const connection = await kernel.auth.connections.create({
  domain: 'app.example.com',
  profile_name: 'user-8f21c3',
});

const login = await kernel.auth.connections.login(connection.id);
console.log('send the user here:', login.hosted_url);

// Later, on every run — no credentials involved.
const browser = await kernel.browsers.create({
  profile: { name: 'user-8f21c3', save_changes: true },
  stealth: true,
  timeout_seconds: 600,
});

Plan for: the session going stale anyway. Check the connection’s state before a run rather than discovering a logged-out page mid-task — see connection lifecycle. If you’re holding logins for your own end users, give each one its own project.

QA and testing

The job: run a browser suite against a real deployment, and be able to explain a failure afterwards.

The shape: headless browsers for cost and concurrency, replays recording so a red test comes with video, and private networking when the environment under test isn’t public.

const browser = await kernel.browsers.create({
  headless: true,
  timeout_seconds: 300,
});

const replay = await kernel.browsers.replays.start(browser.session_id);

try {
  await kernel.browsers.playwright.execute(browser.session_id, {
    code: `
      await page.goto('https://staging.example.com');
      await page.click('text=Sign in');
      await page.waitForSelector('#dashboard', { timeout: 15000 });
    `,
  });
} finally {
  await kernel.browsers.replays.stop(replay.replay_id, { id: browser.session_id });
  await kernel.browsers.deleteByID(browser.session_id);
}

Plan for: flakes that aren’t your app. Telemetry separates a network failure from an assertion failure, and creation latency has known causes worth ruling out before you blame the test.

Replays need a headful browser. If you want video for a failing test, run that one headful.

Going further

• Integrations — the same jobs, framework by framework.
• Agent Skills — install Kernel patterns into your coding agent.
• Site-specific skills — make an agent reliable on one particular website.