API reference

Everything here is exported from the package entry point:

import { createAgent, runTask, runFast, listSessions, loadSession, Slapify } from "slapify";

Config is read from .slapify/config.yaml (found by walking up from process.cwd()). Inline config is laid over it: top-level keys replace the file's, and browser is merged one level deep. Inline config with an llm works with no config file at all. Sessions are stored in .slapify/tasks/ under process.cwd().

createAgent(options?)

The simplest way in: the task agent with defaults that apply to every run.

import { createAgent } from "slapify";

const agent = createAgent({
  config: {
    llm: { provider: "anthropic", model: "claude-sonnet-4-6", api_key: process.env.ANTHROPIC_API_KEY },
    browser: { headless: true, stealth: true },
  },
});

// Run to completion
const run = await agent.run("Go to news.ycombinator.com and return the top 10 headlines");
console.log(run.status, run.finalSummary);

// Stream events as they happen
const stream = agent.stream("Find the cheapest 27-inch 4K monitor on example-store.com");
for await (const event of stream) {
  if (event.type === "status_update") console.log("->", event.message);
  if (event.type === "tool_start") console.log(`  [${event.toolName}]`);
}
console.log((await stream.result).finalSummary);

// Continue an earlier session, memory and history included
await agent.resume(run.id, "Now open the top story and summarise the comments");

options is AgentOptions: every runTask option except goal, plus config. Per-call options override the defaults, and onEvent handlers from both are called.

runTask(options)

The function underneath createAgent. Returns Promise<TaskSession> and throws if the run fails (for example, 5 failed turns in a row).

import { runTask, type TaskEvent } from "slapify";

const session = await runTask({
  goal: "Get the current gold price and record it",
  schema: { type: "object", properties: { price: { type: "number" }, currency: { type: "string" } } },
  outputFile: "gold.json",
  timeLimitMinutes: 10,
  onEvent: (e: TaskEvent) => {
    if (e.type === "status_update") console.log(e.message);
    if (e.type === "done") console.log(e.summary);
  },
  onHumanInput: async (question, hint) => promptUser(question, hint), // your own UI
});
console.log(session.structuredOutput);

Key TaskRunOptions:

TaskSession

id, goal, status ("running" | "completed" | "failed" | "sleeping" | "scheduled"), createdAt, updatedAt, iteration, memory: Record<string, string>, scheduledJobs, finalSummary?, savedFlowPath?, perfAudits? (one entry per perf_audit call), structuredOutput?.

TaskEvent

listSessions() and loadSession(id)

listSessions(): TaskSession[] returns every session in .slapify/tasks/, newest first. loadSession(id): TaskSession | null loads one.

runFast(options)

Ultrafast mode. Needs jev in config. See Decision models and fast mode.

import { runFast } from "slapify";

const res = await runFast({
  goal: "Find a waterproof jacket under $150 and add it to the cart in size M",
  url: "https://shop.example",
  onEvent: (e) => { if (e.type === "step") console.log(e.step.operation, e.step.label ?? ""); },
});
console.log(res.status, res.reason, `${res.elapsedMs}ms`);

FastResult: status ("done" | "blocked" | "limit" | "error"), reason, steps: FastStep[], decisions, textCalls, elapsedMs, jevMs, textMs, jevInputTokens, finalUrl, replay?. Each FastStep has operation, target?, label?, text?, confidence, targetConfidence?, timings, url, pageChanged? and note?.

Slapify (flows)

Runs .flow files and inline steps. Also the default export.

import { Slapify } from "slapify";

const slapify = new Slapify({ configDir: ".slapify" });

const result = await slapify.run(
  ["Go to https://example.com", 'Click "More information"', 'Verify URL contains "iana.org"'],
  "example-test",
);
console.log(result.status, result.passedSteps, result.duration);

const results = await slapify.runMultiple(["tests/"], { parallel: true, workers: 4 });
console.log(slapify.saveSuiteReport(results)); // report folder path

Constructor SlapifyOptions: configDir (load config and credentials from there, with config merged over), or config with an llm (only llm, browser and report are used), plus optional credentials. With neither, it loads from the current directory.

options (RunOptions) take onTestStart(name, totalSteps), onStep(stepResult, name) and onTestComplete(result). TestResult has status ("passed" | "failed"), steps: StepResult[], totalSteps, passedSteps, failedSteps, skippedSteps, duration, autoHandled, assumptions, and perfAudit? and jev? when used.

In Jest or Vitest:

test("user can log in", async () => {
  const result = await new Slapify({ configDir: ".slapify" }).runFile("tests/login.flow");
  expect(result.status).toBe("passed");
}, 120_000);

Performance audits

Audit results arrive on TaskSession.perfAudits (task mode, one per perf_audit call) and TestResult.perfAudit (from TestRunner.runFlow with its audit flag, which is what slapify run --performance uses). Each result has url, auditedAt, vitals (fcp, lcp, cls, ttfb, domContentLoaded, loadComplete), scores (performance, accessibility, bestPractices, seo, or null), react (detection, re-render issues, interaction tests, or null) and network (sizes, API calls, slow and failed calls, long tasks, memory). The lower-level runPerfAudit() function is not exported from the package entry point in 0.0.23.

BrowserAgent

The browser layer the agent uses, over agent-browser. Construct it with a BrowserConfig; the browser opens on the first navigate().

import { BrowserAgent } from "slapify";

const browser = new BrowserAgent({ headless: true, stealth: true });
await browser.navigate("https://example.com");
const state = await browser.getState(); // { url, title, snapshot, refs }
console.log(await browser.getPageText());
await browser.close();

Lower-level exports

Exported types

Agent, AgentOptions, AgentRunOptions, AgentStream, TaskRunOptions, TaskSession, TaskEvent, TaskStatus, FastRunOptions, FastResult, FastStep, FastEvent, FastOperation, InitOptions, SlapifyOptions, RunOptions, RunMultipleOptions, SlapifyConfig, LLMConfig, BrowserConfig, JevConfig, ReviewConfig, FilesConfig, ReportConfig, CredentialsConfig, CredentialProfile, CookieConfig, FlowFile, FlowStep, StepResult, ActionLog, TestResult, BrowserState, RefInfo.