Agent SDK
@shiplightai/sdk is a companion SDK for Playwright. It adds natural-language browser actions, self-healing Playwright steps, AI assertions, data extraction, and extensible custom actions.
Installation
The SDK requires Node.js 22 or newer and Playwright 1.60.
bash
npm install @shiplightai/sdk playwright
npx playwright install chromiumSupported Providers
The SDK supports Google Gemini, Anthropic Claude, and OpenAI models. Pass a model name to createAgent() and provide the corresponding provider key through configureSdk({ env }). You can instead provide a SHIPLIGHT_API_TOKEN to route supported model calls through the Shiplight proxy.
| Provider | Auto-detected model names | Direct credential |
|---|---|---|
gemini-* | GOOGLE_API_KEY | |
| Anthropic | claude-* | ANTHROPIC_API_KEY |
| OpenAI | gpt-*, o followed by a digit, chatgpt-* | OPENAI_API_KEY |
Use provider:model for explicit routing, for example openai:ft:gpt-4o:my-org. The implemented explicit provider names are google, anthropic, and openai.
API Overview
| Method | Description |
|---|---|
agent.run(page, instruction) | Multi-step task execution |
agent.act(page, instruction) | Single browser action |
agent.step(page, action, description) | Wrap Playwright code with self-healing |
agent.assert(page, statement) | AI-powered assertion (throws on failure) |
agent.evaluate(page, statement) | AI condition check (returns boolean) |
agent.extract(page, description, varName) | Extract data from the page |
agent.login(page, options) | AI-driven login with optional 2FA |
agent.waitUntil(page, condition) | Wait for an AI-evaluated condition |
agent.getVariable(name) | Read a stored variable |
agent.setVariable(name, value) | Store a variable |
agent.registerAction(action) | Add a custom action |
Quick Example
typescript
import "dotenv/config";
import { chromium } from "playwright";
import { configureSdk, createAgent } from "@shiplightai/sdk";
configureSdk({
env: {
GOOGLE_API_KEY: process.env.GOOGLE_API_KEY!,
},
});
const agent = createAgent({ model: "gemini-3-flash-preview" });
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://example.com");
await agent.act(page, 'Click the "More information" link');
await agent.assert(page, "The page contains information about IANA");
await browser.close();Next Steps
- API Reference — Detailed method documentation
- Configuration — SDK and agent options
- Self-Healing — The
step()method for wrapping existing Playwright code - Custom Actions — Extend the agent with domain-specific capabilities
- Examples — Working code examples