Sessions

A session is a browser the vendor keeps running for you until you release it. Most of the time you don't need one. The CLI and the tools open one only when a provider can't do the job without it, and close it in the same call.

In TypeScript

import { create } from "@agntn/browsers";

const provider = await create("browserless");
const session = await provider.createSession({ viewport: { width: 1280, height: 800 } });

session.id;
session.cdpUrl; // connect Playwright or Puppeteer here

await provider.releaseSession(session.id);

createSession takes region, headless, viewport, profileId, timeout, proxy, stealth, captchaSolving and an extra bag for vendor fields. What a vendor does with each is the vendor's business. listSessions() and getSession(id) read back what's open.

With a session you also get navigate(url, session) and evaluate(script, session) on Kernel, Browserless and Playwright. That's where the library ends and your own automation begins. For clicks and logins, take cdpUrl and drive the browser yourself.

From the CLI

browsers session create -p kernel
browsers session list -p kernel
browsers session release <session-id> -p kernel

For a model

browsers_session creates one and answers with an opaque ID. browsers_release releases it. That's all a model can do with it. No other tool takes a session ID, and the CDP URL never goes back into the conversation.

Sounds limiting. It's on purpose. The tools never grew navigate or evaluate, so a model can read pages but can't click through your logins. Release what you open. The description of browsers_release says it to the model too, because a forgotten browser is a line on somebody's invoice.