Examples

Each example describes one complete task. Select TypeScript or Python in any panel to update every example on the page. When the selected client does not support a workflow, the panel states that boundary explicitly. Every example here runs on the SDK published in npm 0.1.0-alpha.6, except the navigation-only session, which ships with the native runtime.

Install and configure a customer environment

Installs the registry package, prepares branded Google Chrome, and makes the API key available to the client through the process environment.

npm install node-mantis@0.1.0-alpha.6
npx playwright install chrome
export NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>"

python -m pip install "node-mantis[browser]==0.1.0a1"
python -m nodemantis install-browser --browser chrome
export NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>"

Validate a customer installation

Checks a customer environment before a workload starts. TypeScript uses the SDK preflight. Python 0.1.0a1 uses its installation smoke, which checks credentials, hosted usage, platform compatibility, Chrome, and a bundled fixture.

import { NodeMantis } from "node-mantis";

const report = await NodeMantis.preflight({
  checkBrowser: true,
  timeoutMs: 5000,
});

if (!report.ok) {
  console.error(report.checks);
  process.exit(1);
}

from nodemantis import run_smoke

result = run_smoke(
    browser="chrome",
)

if not result.ok:
    print(result)
    raise SystemExit(1)

Run a multi-step browser goal

Launches a managed browser at a starting page and lets the agent perform multiple actions until the goal is complete or the iteration limit is reached.

import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start({
  startUrl: "https://example.com",
});

try {
  const result = await mantis.run("Open the More information link.", {
    maxIterations: 5,
  });
  console.log(result.ok, result.reason, mantis.page.url());
} finally {
  await mantis.close();
}

Run one bounded page step

Performs a tightly scoped instruction on the current page. Use maxActions to cap work and allowNavigation to declare whether leaving the page is expected.

import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start();

try {
  await mantis.go("https://example.com");
  const result = await mantis.step("Open the More information link.", {
    maxActions: 5,
    allowNavigation: true,
  });
  console.log(result.ok, result.reason);
} finally {
  await mantis.close();
}

Retrieve grounded structured data

Captures the current live DOM once and maps it into a typed result. Standalone retrieval does not click, search, paginate, or navigate. Use a retrieval-enabled run or step when the browser must interact before collecting the answer.

import { z } from "zod";
import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start({
  startUrl: "https://example.com",
});

try {
  const result = await mantis.retrieve("Explain what this page is for.", {
    schema: z.object({ purpose: z.string() }),
    model: "small",
  });

  if (result.status === "success") {
    console.log(result.data, result.contributorIds);
  } else {
    console.log(result.status, result.reason);
  }
} finally {
  await mantis.close();
}

Open a navigation-only session Coming soon

Loads and inspects a page without installing agent perception. Agent, retrieval, extraction, and check methods are unavailable in this mode.

import { NodeMantis } from "node-mantis";

const probe = await NodeMantis.start({
  navigationOnly: true,
  headless: true,
});

try {
  const navigation = await probe.go("https://example.com");
  console.log(navigation.url, navigation.title);
} finally {
  await probe.close();
}

Attach to an existing Playwright page

Adds Node Mantis to browser infrastructure your application already owns. Closing the Node Mantis session does not close an attached page or browser; the application remains responsible for that lifecycle.

import { chromium } from "playwright";
import { NodeMantis } from "node-mantis";

const browser = await chromium.launch({ channel: "chrome", headless: true });
const page = await browser.newPage();
await page.goto("https://example.com");

const mantis = await NodeMantis.attach(page);

try {
  const result = await mantis.check("Is this the Example Domain page?");
  console.log(result.ok, result.reason);
} finally {
  await mantis.close();
  await browser.close();
}