Browser

Oya Browser docs

Playbooks: record once, replay with no model

A playbook is a task the agent did once, kept as Playwright code. Variables and secrets, healing when a page changes, signing in on replay, export and background runs.

Playbooks

A playbook is a task the agent did once, kept as Playwright steps. Replaying it runs those steps with no model in the loop, so it is fast, costs no tokens and does the same thing every time.

TypeScript
await browser.ask("Check eligibility for member {{memberId}}", {
  data: { memberId: "W2847-1193" },
});
const playbook = await browser.toPlaybook("eligibility-check");

// Later, on every case:
const result = await browser.play("eligibility-check", { memberId: "W5512-0042" });
// { steps: 7, total: 7, fellBack: false }

In the console the same loop is a button: run a prompt, then press Save as playbook.

Variables and secrets

Put values in the prompt as {{name}}. Anything in data the agent can read; anything in secrets it never sees. Either way it types them through the placeholder, so the saved playbook keeps names, not values.

TypeScript
await browser.ask("Sign in as {{user}} with {{password}}, then open claims", {
  data: { user: "[email protected]" },
  secrets: { password: process.env.PORTAL_PASSWORD },
});

playbook.variables lists the inputs and playbook.defaults what the run used, so play(name) with nothing repeats it and you pass only what changes. A secret has no default: it never left the page.

Free-text fields

A comment box or a question to answer should not be the same text every run. Oya spots these fields and leaves them to your model, one short call per field, listed in playbook.answers. The generated code reads:

eligibility-check.js
await page.getByLabel("Reason for visit").fill(
  vars["reason"] ?? (await oya.llm.answer("Reason for visit", vars)),
);

Pass the field's key in play() to type fixed text instead. A playbook without such a field makes no model call at all.

When a page changes

If a step no longer fits the page, the agent finishes the task from there and its fix replaces the broken steps, so the next replay runs clean. The result says healed: true. Pass { autoHeal: false } to throw the step's error instead.

Signing in on replay

A replay that lands on a login page signs in with the persona's stored login and second factor, then carries on. Store them once; they are sealed at rest and never read back. See for the code types.

TypeScript
await oya.personas.setCredentials(personaId, {
  domain: "portal.payer.example",
  username: "[email protected]",
  password: process.env.PORTAL_PASSWORD,
});
await oya.personas.setMfa(personaId, { type: "totp", secret: process.env.PORTAL_TOTP });

The Playwright code

playbook.code is the same flow as a Playwright module you own. Read it in review, keep it in git, or run it on any Playwright page:

TypeScript
// playbook.code, saved as eligibility-check.js:
// export default async function run(page, vars, oya) { ... }
import run from "./eligibility-check.js";

await run(page, { memberId: "W5512-0042" }, oya);

Export and import

Move a playbook from staging to production, or from the cloud to your own deployment. Secrets travel by name only; set their values where it lands.

TypeScript
const doc = await staging.playbooks.export("eligibility-check");
await production.playbooks.import(doc, { overwrite: true });
Terminal
oya playbooks export eligibility-check --out eligibility-check.json
oya playbooks import eligibility-check.json --replace

Background runs

For long queues, submit a replay and hear back. onHumanAttention fires for a CAPTCHA or code nobody could solve; the run waits until you respond().

TypeScript
await browser.submit({ playbook: "eligibility-check" }, {
  data: { memberId: "W5512-0042" },
  onSuccess: (result) => save(result),
  onHealed: (result) => notify("the portal changed; the playbook was fixed"),
  onHumanAttention: async (request) => { /* finish by hand */ await request.respond("done"); },
});
MethodEndpointWhat it does
POST/api/browsers/:id/playbooksSave the browser’s last run: { name }. Overwrites a playbook of the same name
POST/api/browsers/:id/playbooks/:name/playReplay: { variables, autoHeal }
GET/api/playbooksEvery saved playbook
PATCH/api/playbooks/:nameRename: { name }. 409 if the name is taken, 404 if there is none; its healed draft moves too
GET/api/playbooks/:name/exportOne playbook as a JSON document
POST/api/playbooks/importSave an export: { playbook, name?, overwrite? }
DELETE/api/playbooks/:nameDelete a playbook
Every endpoint takes the API key as a bearer token, like the rest of the REST API.