Skip to main content
The TypeScript SDK extends Playwright with AI-powered browser automation. Launch a cloud browser, get a page that works like a normal Playwright Page, then use .agent for full-task AI execution or AI-enhanced versions of click, fill, and selectOption that fall back to natural language when selectors fail.

Launch a cloud browser

launchCloudBrowser

Create a new cloud-hosted browser session and connect to it.
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();

// Use Playwright methods
await page.goto("https://example.com");

// Or use AI
await page.agent.runTask("Fill out the contact form and submit it");

await browser.close();

Parameters

ParameterTypeRequiredDefaultDescription
timeoutnumberNo60Session timeout in minutes (5–1440).
proxyLocationProxyLocationNoundefinedGeographic proxy location for browser traffic.

Returns SkyvernBrowser

Cloud browser sessions are only available with SkyvernEnvironment.Cloud or SkyvernEnvironment.Staging.

useCloudBrowser

Get or create a cloud browser session. Reuses the most recent available session if one exists, otherwise creates a new one.
const browser = await skyvern.useCloudBrowser();
const page = await browser.getWorkingPage();

Parameters

Same as launchCloudBrowser. Options are only used when creating a new session.

Returns SkyvernBrowser


connectToCloudBrowserSession

Connect to an existing cloud browser session by ID.
const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
const page = await browser.getWorkingPage();

Parameters

ParameterTypeRequiredDescription
browserSessionIdstringYesThe ID of the cloud browser session.

Returns SkyvernBrowser


connectToBrowserOverCdp

Connect to any browser running with Chrome DevTools Protocol (CDP) enabled, whether local or remote.
const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
const page = await browser.getWorkingPage();

Parameters

ParameterTypeRequiredDescription
cdpUrlstringYesThe CDP WebSocket URL (e.g., "http://localhost:9222").

Returns SkyvernBrowser


SkyvernBrowser

A browser context wrapper that provides Skyvern-enabled pages.

getWorkingPage()

Get the most recent page or create a new one if none exists.
const page = await browser.getWorkingPage();

newPage()

Create a new page (tab) in the browser context.
const page = await browser.newPage();

close()

Close the browser and release resources. If connected to a cloud session, also closes the session.
await browser.close();

SkyvernBrowserPage

A SkyvernBrowserPage extends Playwright’s Page with AI capabilities. Every standard Playwright method (goto, click, fill, waitForSelector, etc.) works as-is. Additionally, it provides:
  • page.agent — AI-powered task execution (full automations)
  • AI-enhanced click, fill, selectOption — try selectors first, fall back to AI
  • page.act, page.extract, page.validate, page.prompt — single AI actions

AI-enhanced Playwright methods

These methods extend the standard Playwright API with AI fallback. Pass a CSS selector and it works like normal Playwright. Add a prompt option and if the selector fails, AI takes over.

click

// Standard Playwright click
await page.click("#submit-button");

// AI-powered click (no selector needed)
await page.click({ prompt: "Click the 'Submit' button" });

// Selector with AI fallback
await page.click("#submit-button", { prompt: "Click the 'Submit' button" });

fill

// Standard Playwright fill
await page.fill("#email", "user@example.com");

// AI-powered fill
await page.fill({ prompt: "Fill 'user@example.com' in the email field" });

// Selector with AI fallback
await page.fill("#email", "user@example.com", {
  prompt: "Fill the email address field",
});

selectOption

// Standard Playwright select
await page.selectOption("#country", "us");

// AI-powered select
await page.selectOption({ prompt: "Select 'United States' from the country dropdown" });

// Selector with AI fallback
await page.selectOption("#country", "us", {
  prompt: "Select United States from country",
});

page.agent — Full task execution

The agent property provides methods for running complete AI-powered automations within the browser page context. These always wait for completion.

agent.runTask

Run a complete AI task in the context of the current page.
const result = await page.agent.runTask("Fill out the contact form and submit it", {
  dataExtractionSchema: {
    type: "object",
    properties: {
      confirmation_number: { type: "string" },
    },
  },
});
console.log(result.output);
ParameterTypeRequiredDescription
promptstringYesNatural language task description.
options.engineRunEngineNoAI engine to use.
options.urlstringNoURL to navigate to. Defaults to current page URL.
options.dataExtractionSchemaRecord<string, unknown> | stringNoJSON schema for output.
options.maxStepsnumberNoMaximum AI steps.
options.timeoutnumberNoMax wait time in seconds. Default: 1800.
options.webhookUrlstringNoWebhook URL for notifications.
options.totpIdentifierstringNoTOTP identifier.
options.totpUrlstringNoTOTP URL.
options.titlestringNoRun display name.
options.errorCodeMappingRecord<string, string>NoCustom error code mapping.
options.modelRecord<string, unknown>NoLLM model configuration.
Returns TaskRunResponse.

agent.login

Run a login workflow in the context of the current page. Supports multiple credential providers via overloaded signatures.
// Skyvern credentials
await page.agent.login("skyvern", {
  credentialId: "cred_123",
});

// Bitwarden
await page.agent.login("bitwarden", {
  bitwardenItemId: "item_id",
  bitwardenCollectionId: "collection_id",
});

// 1Password
await page.agent.login("1password", {
  onepasswordVaultId: "vault_id",
  onepasswordItemId: "item_id",
});

// Azure Vault
await page.agent.login("azure_vault", {
  azureVaultName: "vault_name",
  azureVaultUsernameKey: "username_key",
  azureVaultPasswordKey: "password_key",
});
Returns WorkflowRunResponse.

agent.downloadFiles

Download files in the context of the current page.
const result = await page.agent.downloadFiles("Download the latest invoice PDF", {
  downloadSuffix: ".pdf",
  downloadTimeout: 30,
});
ParameterTypeRequiredDescription
promptstringYesWhat to download.
options.urlstringNoURL to navigate to. Defaults to current page URL.
options.downloadSuffixstringNoExpected file extension.
options.downloadTimeoutnumberNoDownload timeout in seconds.
options.maxStepsPerRunnumberNoMax AI steps.
options.timeoutnumberNoMax wait time in seconds. Default: 1800.
Returns WorkflowRunResponse.

agent.runWorkflow

Run a pre-defined workflow in the context of the current page.
const result = await page.agent.runWorkflow("wpid_abc123", {
  parameters: { company_name: "Acme Corp" },
});
console.log(result.output);
ParameterTypeRequiredDescription
workflowIdstringYesThe workflow permanent ID.
options.parametersRecord<string, unknown>NoWorkflow input parameters.
options.templatebooleanNoWhether it’s a template.
options.titlestringNoRun display name.
options.timeoutnumberNoMax wait time in seconds. Default: 1800.
Returns WorkflowRunResponse.

Single AI actions

act

Perform a single AI action on the page.
await page.act("Scroll down and click the 'Load More' button");

extract

Extract structured data from the current page.
const data = await page.extract({
  prompt: "Extract all product names and prices",
  schema: {
    type: "array",
    items: {
      type: "object",
      properties: {
        name: { type: "string" },
        price: { type: "string" },
      },
    },
  },
});
console.log(data);
ParameterTypeRequiredDescription
promptstringYesWhat to extract.
schemaRecord<string, unknown> | unknown[] | stringNoJSON schema for output.
errorCodeMappingRecord<string, string>NoCustom error codes.
Returns Record<string, unknown> | unknown[] | string | null.

validate

Validate the current page state with AI.
const isLoggedIn = await page.validate("Check if the user is logged in");
console.log(isLoggedIn); // true or false
Returns boolean.

prompt

Send a prompt to the LLM and get a structured response.
const result = await page.prompt(
  "What is the main heading on this page?",
  { heading: { type: "string" } },
);
console.log(result);
Returns Record<string, unknown> | unknown[] | string | null.

Complete example

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();

// Navigate with Playwright
await page.goto("https://app.example.com");

// Login with AI
await page.agent.login("skyvern", { credentialId: "cred_abc123" });

// Extract data with AI
const data = await page.extract({
  prompt: "Extract all invoice numbers and amounts from the billing page",
  schema: {
    type: "array",
    items: {
      type: "object",
      properties: {
        invoice_number: { type: "string" },
        amount: { type: "string" },
      },
    },
  },
});
console.log(data);

// Clean up
await browser.close();
await skyvern.close();