TypeScript SDK

@lookover-ai/webagent-sdk is a TypeScript client for the public /v1 API. It works in Node 22 and in browsers (it uses the global fetch). Request and reply shapes come from the webagent contracts package, and every reply is checked against its schema.

The version in the repository is 0.3.0.

InstallCopy Anchor Link

Add this to the .npmrc of your project:

@lookover-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Set NODE_AUTH_TOKEN to your GitHub token. Then install the package. It needs zod as a peer dependency.

pnpm add @lookover-ai/webagent-sdk zod

First callsCopy Anchor Link

import { WebagentClient, WebagentApiError } from "@lookover-ai/webagent-sdk";

const client = new WebagentClient({
  apiKey: process.env.WEBAGENT_API_KEY!, // wa_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
});

// A browser session you drive with actions.
const session = await client.createSession({ startUrl: "https://example.com" });
try {
  console.log(await session.snapshotText());
  const png = await session.screenshot({ format: "png" });
} finally {
  await session.close();
}

// A skill run: start it, then wait for the verdict.
const { runId } = await client.runSkill("smoke-uat", {
  inputs: { url: "https://example.com" },
});
const run = await client.waitForSkillRun(runId);
console.log(run.status, run.summary);

// The test report: one verdict, the failed steps, console errors and failed network calls.
const report = await client.getSkillRunReport(runId);
console.log(report.verdict, report.summary);

// Errors carry the API error code.
try {
  await client.getSession("sess_us_000000000000000000000000");
} catch (e) {
  if (e instanceof WebagentApiError && e.code === "not_found") console.log("gone", e.requestId);
}

The API hostCopy Anchor Link

The key picks the host. A key wa_us_... goes to https://api.us.webagent.lookover.ai. To use another host, for example a local stack or a proxy, pass baseUrl:

const client = new WebagentClient({ apiKey, baseUrl: "http://localhost:4400" });

Other options: fetch (your own implementation) and timeoutMs (per request, default 60 seconds).

MethodsCopy Anchor Link

What the less obvious ones do:

• createSession(request?, { idempotencyKey }) starts a session with any session option (startUrl, headers, credentials, proxyUrl, and more). It returns a handle. The handle sends actions to the session's own host and refreshes its token for you.
• runSkill(name, { inputs, session, ... }, { idempotencyKey }) starts a run and returns { runId, sessionId, status } at once.
• waitForSkillRun(runId, { pollMs, timeoutMs }) polls until the run is not running. Defaults: 1 second, 5 minutes. It throws a timeout error after that.
• listSkillRuns({ status, skill, limit, cursor }) returns { runs, next }. Pass next as cursor for the following page.
• skillRunReport(runId) returns the HTML report of a finished run.
• getSkillRunReport(runId) returns the JSON test report of a skill run: verdict (pass, fail, error or running), summary, steps, findings, consoleErrors, networkFailures and evidence. It calls GET /v1/skill-runs/:id/report.json and checks the reply against its schema. See Reading results.
• getTaskReport(taskId) returns the same report for a goal task, from GET /v1/tasks/:id/report.json. A task has no assertions: pass means the agent says it is done. The console and network lists come from the session log, which is saved when the session ends, so read a report again if its notes say the log is not available.
• listTasks(sessionId?) lists goal tasks, newest first, at most 200.
• createSession, runSkill and createSchedule accept an idempotencyKey, so a retry does not make a second run.

ErrorsCopy Anchor Link

A failed call throws WebagentApiError with code (an error code), status (0 when no reply arrived), details, requestId and retryAfterS. The SDK does not retry for you. Retry on rate_limited, capacity_exceeded and runner_unavailable as your app needs, with the same idempotencyKey.

What the SDK does not coverCopy Anchor Link

• Goal tasks. There is no method to start a task (run_task). Use the MCP tools for that, or drive the session with act yourself. listTasks lists tasks and getTaskReport reads the report of one.
• Operator routes. /v1/admin/* is not covered.
• Vault, proxies, keys, profiles, replay, logs and share links. There are no methods for them. Use the REST API.
• Public npm release. See the note at the top.