API Reference

This page documents all methods available on the Shiplight SDK agent.

Creating an Agent

import { configureSdk, createAgent } from "@shiplightai/sdk";

// Configure SDK (call once at startup)
configureSdk({
  env: {
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
  },
});

// Create agent
const agent = createAgent({
  model: "claude-haiku-4-5",
  computer_use_model: "claude-sonnet-4-6",
  variables: {
    username: "test@example.com",
    password: "secret",
  },
  sensitiveKeys: ["password"],
  testDataDir: "./test-data",
  downloadDir: "./downloads",
});

Options

Option	Type	Required	Description
model	string	Yes	Primary LLM model name, optionally in provider:model form
computer_use_model	string	No	Model for computer-use operations; defaults to model
variables	Record<string, unknown>	No	Initial agent variables
sensitiveKeys	string[]	No	Variable keys withheld from LLM context and masked in logs
testDataDir	string	No	Base directory for files used by upload actions
downloadDir	string	No	Directory for browser downloads

agent.act(page, instruction)

Perform a single action on the page. Use this for discrete actions like clicking, filling, or selecting.

await agent.act(page, "Click the login button");
await agent.act(page, "Fill the email field with test@example.com");
await agent.act(page, 'Select "Express" from the shipping dropdown');

Parameters

Parameter	Type	Required	Description
page	Page	Yes	Playwright page instance
instruction	string	Yes	Natural language instruction for a single action

Returns

Promise<AgentStepResult>. An action the model cannot complete returns { success: false, details }, so check success when failure must stop the calling workflow. Runtime errors can still reject the promise.

agent.run(page, instruction, options?)

Run a multi-step instruction until the goal is achieved. Use this for complex tasks that require multiple actions.

// Multi-step tasks
await agent.run(page, "Complete the checkout process");
await agent.run(page, "Fill out the entire registration form");

// Limit steps to prevent runaway execution
await agent.run(page, "Add 3 items to cart", { maxSteps: 10 });

Parameters

Parameter	Type	Required	Description
page	Page	Yes	Playwright page instance
instruction	string	Yes	Natural language instruction describing the goal
options.maxSteps	number	No	Maximum steps the agent can take. Default: 15

Returns

Promise<AgentStepResult> on success, including success, optional details, and optional executed actions.

Throws

An error with name AgentTaskFailedError when the agent stops without completing the goal. Provider, browser, and other runtime errors also reject the promise.

agent.step(page, action, description, options?)

Wrap Playwright code with self-healing. If the code throws an exception, the agent attempts to accomplish the goal described in description.

const result = await agent.step(
  page,
  async () => {
    await page.click("#submit-btn");
  },
  "Click the submit button",
);

if (result.success) {
  console.log("Action completed");
} else {
  console.log("Failed:", result.details);
}

Parameters

Parameter	Type	Required	Description
page	Page	Yes	Playwright page instance
action	() => Promise<void>	Yes	Async function containing Playwright code
description	string	Yes	What the agent should accomplish if action fails
options.maxSteps	number	No	Maximum AI recovery steps. Default: 5

Returns

Promise<AgentStepResult>. step() catches errors from both the Playwright callback and recovery and returns { success: false, details }.

See Self-Healing for detailed usage.

---

agent.assert(page, statement)

Assert a condition on the page. Throws an error if the assertion fails.

await agent.assert(page, "Login button is visible");
await agent.assert(page, "Cart contains 3 items");
await agent.assert(page, "Error message is not displayed");

Parameters

Parameter	Type	Required	Description
page	Page	Yes	Playwright page instance
statement	string	Yes	Assertion statement in natural language

Returns

Promise<boolean> - Returns true if assertion passes.

Throws

Error if the assertion is false or cannot be established. Provider, browser, and other runtime errors also reject the promise.

agent.evaluate(page, statement)

Evaluate a condition on the page. A false or indeterminate condition returns false instead of causing an assertion failure.

const isLoggedIn = await agent.evaluate(page, "User is logged in");
if (!isLoggedIn) {
  await agent.act(page, "Click the login button");
}

Parameters

Parameter	Type	Required	Description
page	Page	Yes	Playwright page instance
statement	string	Yes	Condition to evaluate in natural language

Returns

Promise<boolean> - true if the condition is met, and false if it is false or indeterminate. Provider, browser, and other runtime errors can still reject the promise.

agent.extract(page, description, variableName)

Extract data from the page and store it in a variable.

await agent.extract(page, "the order total", "orderTotal");
await agent.act(page, "Verify {{ orderTotal }} is displayed on receipt");

Parameters

Parameter	Type	Required	Description
page	Page	Yes	Playwright page instance
description	string	Yes	Description of the element to extract from
variableName	string	Yes	Name of variable to store the extracted value

Returns

Promise<void>

---

agent.login(page, options)

Perform automated login. The agent navigates to the URL, finds login fields, enters credentials, and handles 2FA if configured.

// Basic login
await agent.login(page, {
  url: "https://example.com/login",
  username: "user@example.com",
  password: "secret123",
});

// With 2FA (TOTP)
await agent.login(page, {
  url: "https://example.com/login",
  username: "user@example.com",
  password: "secret123",
  totpSecret: "JBSWY3DPEHPK3PXP",
});

Parameters

Parameter	Type	Required	Description
options.url	string	Yes	URL of the login page
options.username	string	Yes	Username or email
options.password	string	Yes	Password
options.totpSecret	string	No	TOTP secret for 2FA

Returns

Promise<boolean> - true if login was successful.

---

agent.getVariable(name)

Get a variable value from the variable store.

await agent.extract(page, "the order total", "orderTotal");
const total = agent.getVariable("orderTotal");
console.log("Order total:", total);

Parameters

Parameter	Type	Required	Description
name	string	Yes	Variable name

Returns

string | undefined - Variable value, or undefined if not set.

agent.setVariable(name, value, sensitive?)

Set a variable value in the variable store.

agent.setVariable("couponCode", "SAVE20");
await agent.act(page, "Enter {{ couponCode }} in the promo field");

// Sensitive values are withheld from LLM context and masked in logs
agent.setVariable("apiKey", "secret123", true);

Parameters

Parameter	Type	Required	Description
name	string	Yes	Variable name
value	string	Yes	Variable value
sensitive	boolean	No	Withhold from LLM context and mask in logs. Default: false

Returns

void

---

agent.registerAction(action)

Register a custom action to extend the agent's capabilities.

import { z } from "@shiplightai/sdk";

agent.registerAction({
  name: "extract_email_code",
  description: "Extract verification code from email inbox",
  schema: z.object({
    email_address: z.string().describe("Email address to check"),
  }),
  async execute(args, ctx) {
    const code = await myEmailService.getCode(args.email_address);
    ctx.variableStore.set("verification_code", code);
    return { success: true, message: `Found code: ${code}` };
  },
});

Throws

Registration throws when a required field is missing or the same agent already has an action with that name.

See Custom Actions for the complete action interface.

Result shape

Import AgentStepResult when you need to name the result type:

import type { AgentStepResult } from "@shiplightai/sdk";

const result: AgentStepResult = await agent.act(page, "Click submit");

act(), run(), and step() return this type. It includes success: boolean and may include details, executed actions, and debugging metadata.

agent.waitUntil(page, condition, timeoutSeconds?)

Wait until a condition becomes true. Polls the page state and evaluates whether the condition is met.

// Wait for loading to complete
await agent.waitUntil(page, "Loading spinner is no longer visible");

// Wait with custom timeout (returns false on timeout)
const appeared = await agent.waitUntil(page, "Table shows at least 5 rows", 30);
if (!appeared) {
  throw new Error("Data did not load in time");
}

// Wait for modal to close
await agent.waitUntil(page, "Confirmation modal is closed");

Parameters

Parameter	Type	Required	Default	Description
page	Page	Yes	-	Playwright page instance
condition	string	Yes	-	Natural language condition to wait for
timeoutSeconds	number	No	60	Maximum wait time in seconds

Returns

Promise<boolean> - true if condition was met, false if timeout.