同步完整源码 - 2026-05-24
This commit is contained in:
@@ -0,0 +1,860 @@
|
||||
---
|
||||
title: Actions Reference
|
||||
subtitle: Every page action and agent method
|
||||
description: Reference for all page actions (act, extract, validate, prompt, click, fill, select_option) and agent methods (login, run_task, download_files, run_workflow) with parameters and return types.
|
||||
slug: developers/browser-automations/actions-reference
|
||||
keywords:
|
||||
- act
|
||||
- extract
|
||||
- validate
|
||||
- prompt
|
||||
- click
|
||||
- fill
|
||||
- select_option
|
||||
- agent.login
|
||||
- agent.run_task
|
||||
- agent.download_files
|
||||
- agent.run_workflow
|
||||
- fill_form
|
||||
- locator
|
||||
- frame_switch
|
||||
---
|
||||
|
||||
Browser automations are built in code using three layers: Page (AI-enhanced Playwright), Agent (multi-step AI goals), and Browser (cloud Chromium instance). This page lists every operation available on a Page or through an Agent. For the full SDK documentation with all parameter options, see the [SDK Reference](/sdk-reference/browser-automation/act).
|
||||
|
||||
If you're building automations visually instead, see [Block Types and Configuration](/cloud/building-workflows/configure-blocks) for the equivalent operations in the Cloud UI workflow editor.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
### Page actions
|
||||
|
||||
| Action | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`act`](#act) | Perform any action from a natural-language prompt | `None` |
|
||||
| [`extract`](#extract) | Pull structured data from the page | `dict`, `list`, `str`, or `None` |
|
||||
| [`validate`](#validate) | Assert a condition about the page | `bool` |
|
||||
| [`prompt`](#prompt) | Ask the LLM a question about the page | `dict`, `list`, `str`, or `None` |
|
||||
| [`click`](#click) | Click an element (selector, AI, or both) | `str \| None` |
|
||||
| [`fill`](#fill) | Fill an input field (selector, AI, or both) | `str` |
|
||||
| [`select_option`](#select_option) | Select a dropdown option (selector, AI, or both) | `str \| None` |
|
||||
| [`type`](#type) | Type text character-by-character (Python only) | `str` |
|
||||
| [`hover`](#hover) | Move mouse over an element (Python only) | `str` |
|
||||
| [`scroll`](#scroll) | Scroll the page by pixel offset (Python only) | `None` |
|
||||
| [`upload_file`](#upload_file) | Upload files to a file input (Python only) | `str` |
|
||||
| [`locator`](#locator) | Locate an element with AI, returns a chainable Locator (Python only) | `Locator` |
|
||||
|
||||
### Agent methods
|
||||
|
||||
| Method | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`agent.login`](#agentlogin) | Authenticate with stored credentials | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
|
||||
| [`agent.run_task`](#agentrun_task) | Run a multi-step AI task on the current page | [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) |
|
||||
| [`agent.download_files`](#agentdownload_files) | Navigate and download files | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
|
||||
| [`agent.run_workflow`](#agentrun_workflow) | Run a Cloud UI workflow on the current page | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
|
||||
|
||||
### Form automation (Python only)
|
||||
|
||||
| Method | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`fill_form`](#fill_form) | AI-powered single-page form fill | `None` |
|
||||
| [`fill_multipage_form`](#fill_multipage_form) | Form fill across multiple pages | `int` (pages filled) |
|
||||
| [`fill_from_mapping`](#fill_from_mapping) | Fill fields by index-to-value mapping | `None` |
|
||||
| [`extract_form_fields`](#extract_form_fields) | Extract all form field metadata | `list[dict]` |
|
||||
| [`validate_mapping`](#validate_mapping) | Check if a field mapping is valid | `bool` |
|
||||
| [`fill_autocomplete`](#fill_autocomplete) | Fill input with typeahead handling | `str` |
|
||||
|
||||
### iframe management (Python only)
|
||||
|
||||
| Method | Purpose | Returns |
|
||||
|--------|---------|---------|
|
||||
| [`frame_switch`](#frame_switch) | Switch context to an iframe | `dict` |
|
||||
| [`frame_main`](#frame_main) | Switch back to the main frame | `dict` |
|
||||
| [`frame_list`](#frame_list) | List all frames on the page | `list[dict]` |
|
||||
|
||||
---
|
||||
|
||||
## Page actions
|
||||
|
||||
### act
|
||||
|
||||
Perform any action described in natural language.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.act("Click the login button")
|
||||
await page.act("Scroll down to the pricing section")
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.act("Click the login button")
|
||||
await page.act("Scroll down to the pricing section")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | What action to perform |
|
||||
| `skip_refresh` | `bool` | No | Skip page refresh before acting |
|
||||
| `use_economy_tree` | `bool` | No | Use a smaller DOM tree for faster processing |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [act](/sdk-reference/browser-automation/act)
|
||||
|
||||
---
|
||||
|
||||
### extract
|
||||
|
||||
Pull structured data from the visible page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
data = await page.extract(
|
||||
"Extract all product names and prices",
|
||||
schema={
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"price": {"type": "number"},
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const data = await page.extract({
|
||||
prompt: "Extract all product names and prices",
|
||||
schema: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
name: { type: "string" },
|
||||
price: { type: "number" },
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | What to extract |
|
||||
| `schema` | `dict \| list \| str` | No | JSON Schema for typed output |
|
||||
| `error_code_mapping` | `dict` | No | Map custom error codes |
|
||||
|
||||
**Returns:** `dict`, `list`, `str`, or `None`
|
||||
|
||||
**SDK reference:** [extract](/sdk-reference/browser-automation/extract)
|
||||
|
||||
---
|
||||
|
||||
### validate
|
||||
|
||||
Assert a condition about the current page state.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
is_logged_in = await page.validate("The user is logged in")
|
||||
```
|
||||
|
||||
```typescript
|
||||
const isLoggedIn = await page.validate("The user is logged in")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | Condition to check |
|
||||
| `model` | `dict` | No | Override LLM model config |
|
||||
|
||||
**Returns:** `bool`
|
||||
|
||||
**SDK reference:** [validate](/sdk-reference/browser-automation/validate)
|
||||
|
||||
---
|
||||
|
||||
### prompt
|
||||
|
||||
Ask the LLM a question about the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.prompt(
|
||||
"How many items are in the navigation menu?",
|
||||
schema={"count": {"type": "integer"}}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.prompt(
|
||||
"How many items are in the navigation menu?",
|
||||
{ schema: { count: { type: "integer" } } }
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | Question to ask |
|
||||
| `schema` | `dict` | No | JSON Schema for structured response |
|
||||
| `model` | `dict` | No | Override LLM model config |
|
||||
|
||||
**Returns:** `dict`, `list`, `str`, or `None`. Without a `schema`, returns a `dict` of the form `{"llm_response": "..."}` (TypeScript: `{ llmResponse: "..." }`). With a `schema`, returns data shaped to your schema.
|
||||
|
||||
**SDK reference:** [prompt](/sdk-reference/browser-automation/prompt)
|
||||
|
||||
---
|
||||
|
||||
### click
|
||||
|
||||
Click an element using a selector, AI prompt, or both.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.click("#submit-button") # selector
|
||||
await page.click(prompt="Click the 'Submit' button") # AI
|
||||
await page.click("#submit-button", prompt="Click the 'Submit' button") # both
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.click("#submit-button") // selector
|
||||
await page.click({ prompt: "Click the 'Submit' button" }) // AI
|
||||
await page.click("#submit-button", { prompt: "Click the 'Submit' button" }) // both
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector |
|
||||
| `prompt` | `str` | No | AI prompt (fallback or primary) |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
|
||||
|
||||
**Returns:** `str \| None` (resolved selector)
|
||||
|
||||
**SDK reference:** [click](/sdk-reference/browser-automation/click)
|
||||
|
||||
---
|
||||
|
||||
### fill
|
||||
|
||||
Fill an input field using a selector, AI prompt, or both.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.fill("#email", value="user@example.com") # selector
|
||||
await page.fill(prompt="Fill 'user@example.com' in the email field") # AI
|
||||
await page.fill("#email", value="user@example.com", prompt="Fill email") # both
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.fill("#email", "user@example.com") // selector
|
||||
await page.fill({ prompt: "Fill 'user@example.com' in the email field" }) // AI
|
||||
await page.fill("#email", "user@example.com", { prompt: "Fill email" }) // both
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector |
|
||||
| `value` | `str` | No | Value to fill |
|
||||
| `prompt` | `str` | No | AI prompt (fallback or primary) |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
|
||||
| `totp_identifier` | `str` | No | TOTP identifier for 2FA fields |
|
||||
| `totp_url` | `str` | No | TOTP URL |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [fill](/sdk-reference/browser-automation/fill)
|
||||
|
||||
---
|
||||
|
||||
### select_option
|
||||
|
||||
Select a dropdown option using a selector, AI prompt, or both.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.select_option("#country", value="us") # selector
|
||||
await page.select_option(prompt="Select 'United States' from the country dropdown") # AI
|
||||
await page.select_option("#country", value="us", prompt="Select United States") # both
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.selectOption("#country", { value: "us" }) // selector
|
||||
await page.selectOption({ prompt: "Select 'United States' from the country dropdown" }) // AI
|
||||
await page.selectOption("#country", { value: "us", prompt: "Select United States" }) // both
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector |
|
||||
| `value` | `str \| list[str]` | No | Option value(s) to select |
|
||||
| `prompt` | `str` | No | AI prompt (fallback or primary) |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
|
||||
|
||||
**Returns:** `str | None` (resolved selector)
|
||||
|
||||
**SDK reference:** [select_option](/sdk-reference/browser-automation/select-option)
|
||||
|
||||
---
|
||||
|
||||
### type
|
||||
|
||||
Type text character-by-character. Unlike `fill`, this triggers keystroke events for each character, so use it for fields that react to individual key presses (search autocomplete, OTP inputs). Python only.
|
||||
|
||||
```python
|
||||
# Character-by-character input via selector
|
||||
await page.type("#search", value="wireless headphones")
|
||||
|
||||
# AI-powered type
|
||||
await page.type(prompt="Type 'hello' into the search box")
|
||||
|
||||
# Selector with AI fallback
|
||||
await page.type("#search", value="query text", prompt="Type into the search field")
|
||||
|
||||
# TOTP input from a stored secret
|
||||
await page.type("#otp", totp_identifier="my-app")
|
||||
|
||||
# TOTP generated on the fly from an otpauth URI
|
||||
await page.type("#otp", totp_url="otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS or XPath selector for the input field |
|
||||
| `value` | `str` | No | Text to type character-by-character |
|
||||
| `prompt` | `str` | No | Natural-language description of the target field |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
| `totp_identifier` | `str` | No | Identifier for a stored TOTP secret |
|
||||
| `totp_url` | `str` | No | `otpauth://` URI to generate a one-time password on the fly |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [type](/sdk-reference/browser-automation/type)
|
||||
|
||||
---
|
||||
|
||||
### hover
|
||||
|
||||
Move the mouse over an element. Python only.
|
||||
|
||||
```python
|
||||
# Simple hover
|
||||
await page.hover("#menu-item")
|
||||
|
||||
# Hover with a hold duration (useful for tooltip reveals)
|
||||
await page.hover("#tooltip-trigger", hold_seconds=1.5)
|
||||
|
||||
# Hover with intention logging for debugging
|
||||
await page.hover("#menu-item", intention="Reveal the main menu dropdown")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | Yes | CSS or XPath selector for the target element |
|
||||
| `timeout` | `float` | No | Max wait time in milliseconds for the element. Defaults to `BROWSER_ACTION_TIMEOUT_MS` |
|
||||
| `hold_seconds` | `float` | No | How long to hold the hover, in seconds. Default `0.0` |
|
||||
| `intention` | `str` | No | Description of the hover intent, used for logging |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [hover](/sdk-reference/browser-automation/hover)
|
||||
|
||||
---
|
||||
|
||||
### scroll
|
||||
|
||||
Scroll the page by a pixel offset along the x and y axes. Python only.
|
||||
|
||||
```python
|
||||
await page.scroll(0, 500) # Scroll down 500px
|
||||
await page.scroll(0, -300) # Scroll up 300px
|
||||
await page.scroll(200, 0) # Scroll right 200px
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `scroll_x` | `int` | Yes | Horizontal scroll offset in pixels. Positive values scroll right |
|
||||
| `scroll_y` | `int` | Yes | Vertical scroll offset in pixels. Positive values scroll down |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [scroll](/sdk-reference/browser-automation/scroll)
|
||||
|
||||
---
|
||||
|
||||
### upload_file
|
||||
|
||||
Upload one or more files to a file input. Pass a selector for direct Playwright behavior, a prompt for AI-powered file input detection, or both. Python only.
|
||||
|
||||
```python
|
||||
# Direct selector
|
||||
await page.upload_file("#file-input", files="/path/to/file.pdf")
|
||||
|
||||
# Multiple files
|
||||
await page.upload_file("#file-input", files=["/path/to/file1.pdf", "/path/to/file2.pdf"])
|
||||
|
||||
# AI-powered file input detection (no selector needed)
|
||||
await page.upload_file(prompt="Upload the resume to the file input")
|
||||
|
||||
# Selector with AI fallback: try the selector first, use AI if it fails
|
||||
await page.upload_file(
|
||||
"#file-input",
|
||||
files="/path/to/file.pdf",
|
||||
prompt="Upload the resume to the file input",
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS or XPath selector for the file input |
|
||||
| `files` | `str \| list[str]` | No | File path or list of file paths to upload |
|
||||
| `prompt` | `str` | No | Natural-language description of the file input to target |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [upload_file](/sdk-reference/browser-automation/upload-file)
|
||||
|
||||
---
|
||||
|
||||
### locator
|
||||
|
||||
Locate an element using a CSS/XPath selector, an AI prompt, or both. When called with a `prompt`, returns an `AILocator`, a lazy Playwright `Locator` that resolves the element via AI on first use. Python only.
|
||||
|
||||
```python
|
||||
# AI-powered: pass a natural-language prompt
|
||||
locator = page.locator(prompt="the submit button")
|
||||
await locator.click()
|
||||
|
||||
# Full Playwright chaining works
|
||||
text = await page.locator(prompt="the error message").text_content()
|
||||
|
||||
# Standard Playwright selector (no AI, identical to vanilla Playwright)
|
||||
locator = page.locator("#submit-btn")
|
||||
await locator.click()
|
||||
|
||||
# Selector with AI fallback: try the selector first, use AI if it fails
|
||||
locator = page.locator("#submit-btn", prompt="the submit button")
|
||||
await locator.click()
|
||||
```
|
||||
|
||||
<Note>
|
||||
When called with only a `selector` (no `prompt`), `page.locator(selector)` behaves exactly like the standard Playwright `page.locator(selector)`. No AI is involved.
|
||||
</Note>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS or XPath selector passed to Playwright's built-in `locator()` |
|
||||
| `prompt` | `str` | No | Natural-language description of the element. When provided, returns an `AILocator` that resolves via AI |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
| `**kwargs` | | No | Additional keyword arguments forwarded to Playwright's `locator()` |
|
||||
|
||||
**Returns:** `Locator` (standard Playwright `Locator` when only a selector is given, or `AILocator` when a prompt is provided)
|
||||
|
||||
#### AILocator methods
|
||||
|
||||
When `prompt` is provided, the returned `AILocator` supports all standard Playwright `Locator` methods:
|
||||
|
||||
- **Actions:** `click()`, `fill()`, `type()`, `select_option()`, `check()`, `uncheck()`, `clear()`, `hover()`, `focus()`, `press()`
|
||||
- **Queries:** `text_content()`, `inner_text()`, `inner_html()`, `get_attribute()`, `input_value()`, `count()`
|
||||
- **State:** `is_visible()`, `is_hidden()`, `is_enabled()`, `is_disabled()`, `is_editable()`, `is_checked()`
|
||||
- **Chaining:** `first()`, `last()`, `nth()`, `filter()`, `locator()`, `get_by_text()`, `get_by_role()`, `get_by_label()`, `get_by_placeholder()`
|
||||
- **Utilities:** `wait_for()`, `screenshot()`, `playwright_locator` (access raw `Locator`)
|
||||
|
||||
**SDK reference:** [locator](/sdk-reference/browser-automation/locator)
|
||||
|
||||
---
|
||||
|
||||
## Agent methods
|
||||
|
||||
All agent methods return either a [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) (for `agent.run_task`) or a [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) (for `agent.login`, `agent.download_files`, `agent.run_workflow`). Follow the links for the full field list.
|
||||
|
||||
### agent.login
|
||||
|
||||
Authenticate with stored credentials. Handles multi-page login flows, CAPTCHAs, and 2FA.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
await page.agent.login(
|
||||
credential_type="skyvern",
|
||||
credential_id="cred_123"
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
await page.agent.login("skyvern", {
|
||||
credentialId: "cred_123"
|
||||
})
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `credential_type` | `CredentialType` | Yes | `skyvern`, `bitwarden`, `onepassword`, or `azure_vault` |
|
||||
| `credential_id` | `str` | No | Credential ID (required for `skyvern` type) |
|
||||
| `url` | `str` | No | Login page URL |
|
||||
| `prompt` | `str` | No | Additional login instructions |
|
||||
| `timeout` | `float` | No | Max wait time in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
|
||||
|
||||
**SDK reference:** [agent.login](/sdk-reference/browser-automation/agent-login)
|
||||
|
||||
---
|
||||
|
||||
### agent.run_task
|
||||
|
||||
Run a multi-step AI task on the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.agent.run_task(
|
||||
"Go to the billing page and download the latest invoice",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"invoice_number": {"type": "string"},
|
||||
"amount": {"type": "string"},
|
||||
},
|
||||
},
|
||||
)
|
||||
print(result.output)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.agent.runTask(
|
||||
"Go to the billing page and download the latest invoice",
|
||||
{
|
||||
dataExtractionSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
invoice_number: { type: "string" },
|
||||
amount: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
console.log(result.output)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | Multi-step goal description |
|
||||
| `data_extraction_schema` | `dict \| str` | No | JSON Schema for structured output. See [Extract Structured Data](/developers/browser-automations/extract-structured-data). |
|
||||
| `max_steps` | `int` | No | Cap AI steps. The run terminates with `timed_out` if hit. Controls cost; each step is one AI decision + action cycle. |
|
||||
| `engine` | `RunEngine` | No | AI engine. Defaults to `skyvern-1.0` in the SDK for backward compatibility. Pass `skyvern-2.0` for the latest model (also the Cloud UI default). Other options: `openai-cua`, `anthropic-cua`, `ui-tars`. |
|
||||
| `model` | `dict` / `Record<string, unknown>` | No | Override LLM model configuration |
|
||||
| `url` | `str` / `string` | No | URL to navigate to (defaults to current page URL) |
|
||||
| `webhook_url` | `str` / `string` | No | Callback URL. Skyvern POSTs the full run result on completion or failure. See [Webhooks](/developers/going-to-production/webhooks). |
|
||||
| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP. See [Handle 2FA](/developers/credentials/handle-2fa). |
|
||||
| `totp_url` | `str` / `string` | No | Endpoint Skyvern calls to pull TOTP codes. See [Handle 2FA](/developers/credentials/handle-2fa). |
|
||||
| `title` | `str` / `string` | No | Display name for this run |
|
||||
| `error_code_mapping` | `dict` / `Record<string, string>` | No | Map custom error codes to conditions. Keys are your error codes, values describe when to trigger them. If matched, `output` contains `{"error": "your_code"}`. |
|
||||
| `user_agent` | `str` / `string` | No | Custom User-Agent header for the browser |
|
||||
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse)
|
||||
|
||||
**SDK reference:** [agent.run_task](/sdk-reference/browser-automation/agent-run-task)
|
||||
|
||||
---
|
||||
|
||||
### agent.download_files
|
||||
|
||||
Navigate and download files from the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.agent.download_files(
|
||||
"Download the latest invoice PDF",
|
||||
download_suffix=".pdf",
|
||||
download_timeout=30,
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the latest invoice PDF",
|
||||
{
|
||||
downloadSuffix: ".pdf",
|
||||
downloadTimeout: 30,
|
||||
},
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` | Yes | What to download |
|
||||
| `download_suffix` | `str` | No | Filename hint prepended to the saved file (e.g., `"invoice"` → `invoice.pdf`). Not a validator; mismatched extensions don't fail the run. |
|
||||
| `download_timeout` | `float` | No | Soft hint (seconds) for how long to wait for a download. The overall `timeout` is what actually fails the run. |
|
||||
| `max_steps_per_run` | `int` | No | Cap AI steps |
|
||||
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
|
||||
|
||||
**SDK reference:** [agent.download_files](/sdk-reference/browser-automation/agent-download-files)
|
||||
|
||||
---
|
||||
|
||||
### agent.run_workflow
|
||||
|
||||
Run a Cloud UI workflow on the current page.
|
||||
|
||||
<CodeGroup>
|
||||
```python
|
||||
result = await page.agent.run_workflow(
|
||||
"wpid_monthly_report",
|
||||
parameters={"month": "2025-03"}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
const result = await page.agent.runWorkflow(
|
||||
"wpid_monthly_report",
|
||||
{ parameters: { month: "2025-03" } }
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `workflow_id` | `str` | Yes | Workflow permanent ID |
|
||||
| `parameters` | `dict` | No | Workflow input parameters |
|
||||
| `template` | `bool` | No | Run a template workflow |
|
||||
| `title` | `str` / `string` | No | Display name for this run |
|
||||
| `webhook_url` | `str` / `string` | No | Callback URL for run completion. See [Webhooks](/developers/going-to-production/webhooks). |
|
||||
| `totp_url` | `str` / `string` | No | Endpoint for pulling TOTP codes |
|
||||
| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP |
|
||||
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
|
||||
|
||||
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
|
||||
|
||||
**SDK reference:** [agent.run_workflow](/sdk-reference/browser-automation/agent-run-workflow)
|
||||
|
||||
---
|
||||
|
||||
## Form automation (Python only)
|
||||
|
||||
### fill_form
|
||||
|
||||
Fill a single-page form using AI. Pass a `data` dict describing the values to fill.
|
||||
|
||||
```python
|
||||
# Simple form fill
|
||||
await page.fill_form(
|
||||
data={"name": "John Doe", "email": "john@example.com", "role": "Engineer"},
|
||||
)
|
||||
|
||||
# With a custom prompt to guide the AI
|
||||
await page.fill_form(
|
||||
data={"name": "John Doe", "email": "john@example.com"},
|
||||
prompt="Fill out the registration form with the provided user details",
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `data` | `dict[str, Any]` | Yes | Key-value pairs of form data to fill |
|
||||
| `prompt` | `str` | No | Instruction for the AI. Defaults to `"Fill out the form"` |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [fill_form](/sdk-reference/browser-automation/fill-form)
|
||||
|
||||
---
|
||||
|
||||
### fill_multipage_form
|
||||
|
||||
Fill a form that spans multiple pages, handling page transitions automatically.
|
||||
|
||||
```python
|
||||
pages_filled = await page.fill_multipage_form(
|
||||
data={"name": "John Doe", "email": "john@example.com", "address": "123 Main St"},
|
||||
max_pages=5,
|
||||
)
|
||||
print(f"Filled {pages_filled} pages")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `data` | `dict[str, Any]` | Yes | Key-value pairs of form data to fill across all pages |
|
||||
| `prompt` | `str` | No | Instruction for the AI. Defaults to `"Fill out the form"` |
|
||||
| `next_button` | `str` | No | Selector or description of the button to advance to the next page |
|
||||
| `max_pages` | `int` | No | Maximum number of pages to fill. Defaults to `10` |
|
||||
| `timeout_seconds` | `float` | No | Timeout in seconds for the entire operation. Defaults to `300` |
|
||||
|
||||
**Returns:** `int` (the number of pages filled)
|
||||
|
||||
**SDK reference:** [fill_multipage_form](/sdk-reference/browser-automation/fill-multipage-form)
|
||||
|
||||
---
|
||||
|
||||
### fill_from_mapping
|
||||
|
||||
Fill form fields using an explicit index-based mapping produced by `extract_form_fields`. Use this when you need precise control over which field gets which value.
|
||||
|
||||
```python
|
||||
fields = await page.extract_form_fields()
|
||||
await page.fill_from_mapping(
|
||||
form_fields=fields,
|
||||
mapping={0: "John", 1: "Doe", 2: "john@example.com"}, # keys are field indices
|
||||
data={"name": "John Doe"}, # optional context
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `form_fields` | `list[dict[str, Any]]` | Yes | Field metadata returned by `extract_form_fields` |
|
||||
| `mapping` | `dict[int, str \| list \| bool \| None]` | Yes | Map of field index to the value to fill |
|
||||
| `data` | `dict[str, Any] \| None` | No | Optional source data for context. Defaults to `None` |
|
||||
|
||||
**Returns:** `None`
|
||||
|
||||
**SDK reference:** [fill_from_mapping](/sdk-reference/browser-automation/fill-from-mapping)
|
||||
|
||||
---
|
||||
|
||||
### extract_form_fields
|
||||
|
||||
Extract all form fields with metadata from the current page. Use the output to drive `fill_from_mapping` or `validate_mapping`.
|
||||
|
||||
```python
|
||||
fields = await page.extract_form_fields()
|
||||
# Returns a list of dicts with field name, type, options, and other metadata:
|
||||
# [{"name": "First Name", "type": "text", "index": 0, ...}, ...]
|
||||
```
|
||||
|
||||
**Returns:** `list[dict[str, Any]]` where each dict contains field name, type, options, and other metadata.
|
||||
|
||||
**SDK reference:** [extract_form_fields](/sdk-reference/browser-automation/extract-form-fields)
|
||||
|
||||
---
|
||||
|
||||
### validate_mapping
|
||||
|
||||
Check if a field mapping is correct for the current form.
|
||||
|
||||
```python
|
||||
fields = await page.extract_form_fields()
|
||||
is_valid = await page.validate_mapping(
|
||||
form_fields=fields,
|
||||
mapping={0: "John", 1: "Doe"},
|
||||
prompt="Validate the name fields are filled correctly",
|
||||
)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `form_fields` | `list[dict[str, Any]]` | Yes | Field metadata returned by `extract_form_fields` |
|
||||
| `mapping` | `dict[int, str \| list \| bool \| None]` | Yes | Map of field index to the value to validate |
|
||||
| `prompt` | `str` | Yes | Instruction describing what to validate |
|
||||
|
||||
**Returns:** `bool` (`True` if the mapping is valid, `False` otherwise)
|
||||
|
||||
**SDK reference:** [validate_mapping](/sdk-reference/browser-automation/validate-mapping)
|
||||
|
||||
---
|
||||
|
||||
### fill_autocomplete
|
||||
|
||||
Fill an input that has autocomplete/typeahead behavior. Types the value, waits for suggestions, then clicks the matching option.
|
||||
|
||||
```python
|
||||
# Direct selector
|
||||
await page.fill_autocomplete(
|
||||
selector="#city",
|
||||
value="San Francisco",
|
||||
option_selector=".autocomplete-option",
|
||||
wait_seconds=1.5,
|
||||
)
|
||||
|
||||
# AI-powered
|
||||
await page.fill_autocomplete(prompt="Fill 'San Francisco' in the city autocomplete")
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector for the input field |
|
||||
| `value` | `str` | No | The text value to type into the field |
|
||||
| `prompt` | `str` | No | Natural-language description of the field and value |
|
||||
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
|
||||
| `option_selector` | `str` | No | CSS selector for the autocomplete dropdown options |
|
||||
| `wait_seconds` | `float` | No | Seconds to wait for the dropdown to appear. Default `1.5` |
|
||||
| `**kwargs` | | No | Standard Playwright fill options (e.g., `timeout`, `force`) |
|
||||
|
||||
**Returns:** `str` (resolved selector)
|
||||
|
||||
**SDK reference:** [fill_autocomplete](/sdk-reference/browser-automation/fill-autocomplete)
|
||||
|
||||
---
|
||||
|
||||
## iframe management (Python only)
|
||||
|
||||
### frame_switch
|
||||
|
||||
Switch the working context to an iframe. Exactly one of `selector`, `name`, or `index` must be provided.
|
||||
|
||||
```python
|
||||
# By CSS selector
|
||||
await page.frame_switch(selector="#payment-iframe")
|
||||
|
||||
# By frame name
|
||||
await page.frame_switch(name="checkout")
|
||||
|
||||
# By zero-based index
|
||||
await page.frame_switch(index=0)
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `selector` | `str` | No | CSS selector for the iframe element |
|
||||
| `name` | `str` | No | The `name` attribute of the iframe |
|
||||
| `index` | `int` | No | Zero-based index of the iframe on the page |
|
||||
|
||||
<Note>
|
||||
Exactly one of `selector`, `name`, or `index` must be provided.
|
||||
</Note>
|
||||
|
||||
**Returns:** `dict[str, Any]` (frame metadata for the switched-to iframe)
|
||||
|
||||
**SDK reference:** [frame_switch](/sdk-reference/browser-automation/frame-switch)
|
||||
|
||||
---
|
||||
|
||||
### frame_main
|
||||
|
||||
Switch back to the main page frame after working inside an iframe.
|
||||
|
||||
```python
|
||||
page.frame_main()
|
||||
```
|
||||
|
||||
**Returns:** `dict[str, str]`
|
||||
|
||||
**SDK reference:** [frame_main](/sdk-reference/browser-automation/frame-main)
|
||||
|
||||
---
|
||||
|
||||
### frame_list
|
||||
|
||||
List all frames on the current page with metadata.
|
||||
|
||||
```python
|
||||
frames = await page.frame_list()
|
||||
# [{"name": "checkout", "url": "...", "index": 0}, ...]
|
||||
```
|
||||
|
||||
**Returns:** `list[dict[str, Any]]` (metadata for each frame on the page)
|
||||
|
||||
**SDK reference:** [frame_list](/sdk-reference/browser-automation/frame-list)
|
||||
@@ -0,0 +1,717 @@
|
||||
---
|
||||
title: Extract Structured Data
|
||||
subtitle: Get consistent, typed output from your automations
|
||||
description: Define JSON Schema extraction schemas for Skyvern tasks to get consistent, typed output. Build schemas for single objects or arrays of items with the interactive schema builder.
|
||||
slug: developers/browser-automations/extract-structured-data
|
||||
keywords:
|
||||
- JSON Schema
|
||||
- extraction schema
|
||||
- typed output
|
||||
- schema builder
|
||||
- array
|
||||
- object
|
||||
- string
|
||||
- number
|
||||
- boolean
|
||||
---
|
||||
|
||||
import { FIELD_TYPES, SchemaBuilder } from "/snippets/schema-builder.mdx";
|
||||
|
||||
When building browser automations in code, you can extract structured data from any page using `page.extract` with a JSON schema, or by passing a `data_extraction_schema` to `page.agent.run_task`. By default, Skyvern returns extracted data in whatever format makes sense for the action. Pass a schema to enforce a specific shape using [JSON Schema](https://json-schema.org/).
|
||||
|
||||
If you're using the Cloud UI workflow editor instead, extraction works through the Extract block. See [Block Types and Configuration](/cloud/building-workflows/configure-blocks) for setup.
|
||||
|
||||
---
|
||||
|
||||
## Define a schema
|
||||
|
||||
Pass a JSON Schema object to `page.extract` via the `schema` parameter, or to `run_task` via `data_extraction_schema`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="page.extract (browser automation)">
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
data = await page.extract(
|
||||
"Get the title of the top post",
|
||||
schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "The title of the top post"
|
||||
}
|
||||
}
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const data = await page.extract({
|
||||
prompt: "Get the title of the top post",
|
||||
schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: {
|
||||
type: "string",
|
||||
description: "The title of the top post",
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
</Tab>
|
||||
<Tab title="run_task">
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the title of the top post",
|
||||
url="https://news.ycombinator.com",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "The title of the top post"
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the title of the top post",
|
||||
url: "https://news.ycombinator.com",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: {
|
||||
type: "string",
|
||||
description: "The title of the top post",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the title of the top post",
|
||||
"url": "https://news.ycombinator.com",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "The title of the top post"
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
The `description` field in each property helps Skyvern understand what data to extract. Be specific.
|
||||
|
||||
<Warning>
|
||||
`description` fields drive extraction quality. Vague descriptions like "the data" produce vague results. Be specific: "The product price in USD, without currency symbol."
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Schema format
|
||||
|
||||
Skyvern uses standard JSON Schema. Common types:
|
||||
|
||||
| Type | JSON Schema | Example value |
|
||||
|------|-------------|---------------|
|
||||
| String | `{"type": "string"}` | `"Hello world"` |
|
||||
| Number | `{"type": "number"}` | `19.99` |
|
||||
| Integer | `{"type": "integer"}` | `42` |
|
||||
| Boolean | `{"type": "boolean"}` | `true` |
|
||||
| Array | `{"type": "array", "items": {...}}` | `[1, 2, 3]` |
|
||||
| Object | `{"type": "object", "properties": {...}}` | `{"key": "value"}` |
|
||||
|
||||
<Note>
|
||||
A schema doesn't guarantee all fields are populated. If the data isn't on the page, fields return `null`. Design your code to handle missing values.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Build your schema
|
||||
|
||||
Use the interactive builder to generate a schema, then copy it into your code.
|
||||
|
||||
<SchemaBuilder />
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Single value
|
||||
|
||||
Extract one piece of information, such as the current price of Bitcoin:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the current Bitcoin price in USD",
|
||||
url="https://coinmarketcap.com/currencies/bitcoin/",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"price": {
|
||||
"type": "number",
|
||||
"description": "Current Bitcoin price in USD"
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the current Bitcoin price in USD",
|
||||
url: "https://coinmarketcap.com/currencies/bitcoin/",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
price: {
|
||||
type: "number",
|
||||
description: "Current Bitcoin price in USD",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the current Bitcoin price in USD",
|
||||
"url": "https://coinmarketcap.com/currencies/bitcoin/",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"price": {
|
||||
"type": "number",
|
||||
"description": "Current Bitcoin price in USD"
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Output (when completed):**
|
||||
|
||||
```json
|
||||
{
|
||||
"price": 104521.37
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### List of items
|
||||
|
||||
Extract multiple items with the same structure, such as the top posts from a news site:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the top 5 posts",
|
||||
url="https://news.ycombinator.com",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"posts": {
|
||||
"type": "array",
|
||||
"description": "Top 5 posts from the front page",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Post title"
|
||||
},
|
||||
"points": {
|
||||
"type": "integer",
|
||||
"description": "Number of points"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "Link to the post"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the top 5 posts",
|
||||
url: "https://news.ycombinator.com",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
posts: {
|
||||
type: "array",
|
||||
description: "Top 5 posts from the front page",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: {
|
||||
type: "string",
|
||||
description: "Post title",
|
||||
},
|
||||
points: {
|
||||
type: "integer",
|
||||
description: "Number of points",
|
||||
},
|
||||
url: {
|
||||
type: "string",
|
||||
description: "Link to the post",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get the top 5 posts",
|
||||
"url": "https://news.ycombinator.com",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"posts": {
|
||||
"type": "array",
|
||||
"description": "Top 5 posts from the front page",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Post title"
|
||||
},
|
||||
"points": {
|
||||
"type": "integer",
|
||||
"description": "Number of points"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "Link to the post"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Output (when completed):**
|
||||
|
||||
```json
|
||||
{
|
||||
"posts": [
|
||||
{
|
||||
"title": "Running Claude Code dangerously (safely)",
|
||||
"points": 342,
|
||||
"url": "https://blog.emilburzo.com/2026/01/running-claude-code-dangerously-safely/"
|
||||
},
|
||||
{
|
||||
"title": "Linux kernel framework for PCIe device emulation",
|
||||
"points": 287,
|
||||
"url": "https://github.com/cakehonolulu/pciem"
|
||||
},
|
||||
{
|
||||
"title": "I'm addicted to being useful",
|
||||
"points": 256,
|
||||
"url": "https://www.seangoedecke.com/addicted-to-being-useful/"
|
||||
},
|
||||
{
|
||||
"title": "Level S4 solar radiation event",
|
||||
"points": 198,
|
||||
"url": "https://www.swpc.noaa.gov/news/g4-severe-geomagnetic-storm"
|
||||
},
|
||||
{
|
||||
"title": "WebAssembly Text Format parser performance",
|
||||
"points": 176,
|
||||
"url": "https://blog.gplane.win/posts/improve-wat-parser-perf.html"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Arrays without limits extract everything visible on the page. Specify limits in your prompt (e.g., "top 5 posts") or the array description to control output size.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
### Nested objects
|
||||
|
||||
Extract hierarchical data, such as a product with its pricing and availability:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get product details including pricing and availability",
|
||||
url="https://www.amazon.com/dp/B0EXAMPLE",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"product": {
|
||||
"type": "object",
|
||||
"description": "Product information",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Product name"
|
||||
},
|
||||
"pricing": {
|
||||
"type": "object",
|
||||
"description": "Pricing details",
|
||||
"properties": {
|
||||
"current_price": {
|
||||
"type": "number",
|
||||
"description": "Current price in USD"
|
||||
},
|
||||
"original_price": {
|
||||
"type": "number",
|
||||
"description": "Original price before discount"
|
||||
},
|
||||
"discount_percent": {
|
||||
"type": "integer",
|
||||
"description": "Discount percentage"
|
||||
}
|
||||
}
|
||||
},
|
||||
"availability": {
|
||||
"type": "object",
|
||||
"description": "Stock information",
|
||||
"properties": {
|
||||
"in_stock": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the item is in stock"
|
||||
},
|
||||
"delivery_estimate": {
|
||||
"type": "string",
|
||||
"description": "Estimated delivery date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get product details including pricing and availability",
|
||||
url: "https://www.amazon.com/dp/B0EXAMPLE",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
product: {
|
||||
type: "object",
|
||||
description: "Product information",
|
||||
properties: {
|
||||
name: {
|
||||
type: "string",
|
||||
description: "Product name",
|
||||
},
|
||||
pricing: {
|
||||
type: "object",
|
||||
description: "Pricing details",
|
||||
properties: {
|
||||
current_price: {
|
||||
type: "number",
|
||||
description: "Current price in USD",
|
||||
},
|
||||
original_price: {
|
||||
type: "number",
|
||||
description: "Original price before discount",
|
||||
},
|
||||
discount_percent: {
|
||||
type: "integer",
|
||||
description: "Discount percentage",
|
||||
},
|
||||
},
|
||||
},
|
||||
availability: {
|
||||
type: "object",
|
||||
description: "Stock information",
|
||||
properties: {
|
||||
in_stock: {
|
||||
type: "boolean",
|
||||
description: "Whether the item is in stock",
|
||||
},
|
||||
delivery_estimate: {
|
||||
type: "string",
|
||||
description: "Estimated delivery date",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Get product details including pricing and availability",
|
||||
"url": "https://www.amazon.com/dp/B0EXAMPLE",
|
||||
"data_extraction_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"product": {
|
||||
"type": "object",
|
||||
"description": "Product information",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Product name"
|
||||
},
|
||||
"pricing": {
|
||||
"type": "object",
|
||||
"description": "Pricing details",
|
||||
"properties": {
|
||||
"current_price": {
|
||||
"type": "number",
|
||||
"description": "Current price in USD"
|
||||
},
|
||||
"original_price": {
|
||||
"type": "number",
|
||||
"description": "Original price before discount"
|
||||
},
|
||||
"discount_percent": {
|
||||
"type": "integer",
|
||||
"description": "Discount percentage"
|
||||
}
|
||||
}
|
||||
},
|
||||
"availability": {
|
||||
"type": "object",
|
||||
"description": "Stock information",
|
||||
"properties": {
|
||||
"in_stock": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the item is in stock"
|
||||
},
|
||||
"delivery_estimate": {
|
||||
"type": "string",
|
||||
"description": "Estimated delivery date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Output (when completed):**
|
||||
|
||||
```json
|
||||
{
|
||||
"product": {
|
||||
"name": "Wireless Bluetooth Headphones",
|
||||
"pricing": {
|
||||
"current_price": 79.99,
|
||||
"original_price": 129.99,
|
||||
"discount_percent": 38
|
||||
},
|
||||
"availability": {
|
||||
"in_stock": true,
|
||||
"delivery_estimate": "Tomorrow, Jan 21"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accessing extracted data
|
||||
|
||||
How you access extracted data depends on which method you used.
|
||||
|
||||
### page.extract (browser automation)
|
||||
|
||||
`page.extract` returns the extracted data directly as the return value:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
data = await page.extract(
|
||||
"Get the top post",
|
||||
schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {"type": "string", "description": "Post title"},
|
||||
"points": {"type": "integer", "description": "Points"}
|
||||
}
|
||||
},
|
||||
)
|
||||
|
||||
# data is the extracted result directly
|
||||
print(f"Title: {data['title']}")
|
||||
print(f"Points: {data['points']}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const data = await page.extract({
|
||||
prompt: "Get the top post",
|
||||
schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: { type: "string", description: "Post title" },
|
||||
points: { type: "integer", description: "Points" },
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// data is the extracted result directly
|
||||
console.log(`Title: ${data.title}`);
|
||||
console.log(`Points: ${data.points}`);
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### run_task (async task)
|
||||
|
||||
The extracted data appears in the `output` field of the completed run. Poll until the task reaches a terminal state, then access the output.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await client.run_task(
|
||||
prompt="Get the top post",
|
||||
url="https://news.ycombinator.com",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": {"type": "string", "description": "Post title"},
|
||||
"points": {"type": "integer", "description": "Points"}
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
run_id = result.run_id
|
||||
|
||||
while True:
|
||||
run = await client.get_run(run_id)
|
||||
|
||||
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
|
||||
break
|
||||
|
||||
await asyncio.sleep(5)
|
||||
|
||||
# Access the extracted data
|
||||
print(f"Output: {run.output}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await client.runTask({
|
||||
body: {
|
||||
prompt: "Get the top post",
|
||||
url: "https://news.ycombinator.com",
|
||||
data_extraction_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
title: { type: "string", description: "Post title" },
|
||||
points: { type: "integer", description: "Points" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
const runId = result.run_id;
|
||||
|
||||
while (true) {
|
||||
const run = await client.getRun(runId);
|
||||
|
||||
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
|
||||
console.log(`Output: ${JSON.stringify(run.output)}`);
|
||||
break;
|
||||
}
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 5000));
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
RUN_ID="your_run_id_here"
|
||||
|
||||
while true; do
|
||||
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY")
|
||||
|
||||
STATUS=$(echo "$RESPONSE" | jq -r '.status')
|
||||
|
||||
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
|
||||
echo "$RESPONSE" | jq '.output'
|
||||
break
|
||||
fi
|
||||
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
If using webhooks, the same `output` field appears in the webhook payload.
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Actions Reference"
|
||||
icon="sliders"
|
||||
href="/developers/browser-automations/actions-reference"
|
||||
>
|
||||
All available page actions and agent methods
|
||||
</Card>
|
||||
<Card
|
||||
title="Build a Browser Automation"
|
||||
icon="play"
|
||||
href="/developers/browser-automations/overview"
|
||||
>
|
||||
Launch a browser, navigate pages, and extract data
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: Handle Browsers
|
||||
subtitle: Launch, connect, configure, and manage browser sessions
|
||||
description: Launch cloud browsers, connect via CDP, configure proxies and timeouts, open multiple tabs, and manage browser lifecycle for Skyvern automations.
|
||||
slug: developers/browser-automations/handle-browsers
|
||||
keywords:
|
||||
- launch_cloud_browser
|
||||
- use_cloud_browser
|
||||
- connect_to_cloud_browser_session
|
||||
- connect_to_browser_over_cdp
|
||||
- launch_local_browser
|
||||
- get_working_page
|
||||
- new_page
|
||||
- close
|
||||
- proxy
|
||||
- CDP
|
||||
- session timeout
|
||||
---
|
||||
|
||||
Every browser automation starts with a browser. You launch a cloud Chromium instance, get a Playwright context, and write your automation against it. Cookies, localStorage, and auth state persist across every page you open inside that browser.
|
||||
|
||||
This page covers browser lifecycle for code-based automations using the Skyvern SDK. If you're running automations through the Cloud UI workflow editor, browser management is handled automatically. See [Browser Sessions](/cloud/browser-management/browser-sessions) for the Cloud UI equivalent.
|
||||
|
||||
---
|
||||
|
||||
## Launch a cloud browser
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `timeout` | `int` | `None` | Session timeout in minutes (5-1440). Server default: 60 minutes |
|
||||
| `proxy_location` | `ProxyLocation` | `None` | Route traffic through a geographic proxy |
|
||||
|
||||
The browser stays alive until `timeout` expires or you call `browser.close()`.
|
||||
|
||||
After a successful launch the handle exposes:
|
||||
|
||||
- `browser.browser_session_id`: the `pbs_*` session id, useful for locking tasks to this session or for logging
|
||||
- `browser.pages`: the list of open Playwright pages in this browser context
|
||||
|
||||
If `timeout < 5`, Skyvern rejects the request with `UnprocessableEntityError` (422). An invalid `proxy_location` enum is rejected the same way.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Launch with a 2-hour timeout and US residential proxy
|
||||
browser = await skyvern.launch_cloud_browser(
|
||||
timeout=120,
|
||||
proxy_location="RESIDENTIAL"
|
||||
)
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser({
|
||||
timeout: 120,
|
||||
proxyLocation: "RESIDENTIAL",
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Reuse an existing browser
|
||||
|
||||
If you have a cloud browser session already running, reuse it instead of launching a new one.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Reuse the most recent available session, or create one if none exists
|
||||
browser = await skyvern.use_cloud_browser()
|
||||
|
||||
# Connect to a specific session by ID
|
||||
browser = await skyvern.connect_to_cloud_browser_session("pbs_abc123")
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
|
||||
// Reuse the most recent available session, or create one if none exists
|
||||
const browser = await skyvern.useCloudBrowser();
|
||||
|
||||
// Connect to a specific session by ID
|
||||
const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
`use_cloud_browser` checks for an available session first. If one exists, it connects to it. If not, it creates a new one with the options you provide.
|
||||
|
||||
Passing an unknown session id to `connect_to_cloud_browser_session` raises `NotFoundError` (HTTP 404).
|
||||
|
||||
---
|
||||
|
||||
## Connect to a local browser
|
||||
|
||||
Connect to any browser running with Chrome DevTools Protocol (CDP) enabled. This works with local Chrome, Chromium, or any CDP-compatible browser.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.connect_to_browser_over_cdp("http://localhost:9222")
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Start Chrome with CDP enabled:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
|
||||
|
||||
# Linux
|
||||
google-chrome --remote-debugging-port=9222
|
||||
```
|
||||
|
||||
For self-hosted Skyvern deployments, you can also launch a local Chromium browser directly (Python only):
|
||||
|
||||
```python
|
||||
# Requires Skyvern.local() - not available in cloud mode
|
||||
skyvern = Skyvern.local()
|
||||
browser = await skyvern.launch_local_browser(headless=False, port=9222)
|
||||
```
|
||||
|
||||
See the [Self-Hosted Browser Configuration](/developers/self-hosted/browser) guide for headless/headful modes, display settings, and Docker setups.
|
||||
|
||||
---
|
||||
|
||||
## Working with pages
|
||||
|
||||
### Get the current page
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
```typescript TypeScript
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Returns the most recent page. If no pages are open, creates a new one. Each call returns a fresh `SkyvernBrowserPage` wrapper. Don't rely on identity (`is` / `===`) comparisons between the return value and earlier page references.
|
||||
|
||||
### Open a new tab
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
page2 = await browser.new_page()
|
||||
await page2.goto("https://example.com/other-page")
|
||||
```
|
||||
```typescript TypeScript
|
||||
const page2 = await browser.newPage();
|
||||
await page2.goto("https://example.com/other-page");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Both pages share the same browser context (cookies, auth state).
|
||||
|
||||
### Wrap an existing Playwright page (Python only)
|
||||
|
||||
```python
|
||||
skyvern_page = await browser.get_page_for(existing_playwright_page)
|
||||
```
|
||||
|
||||
Adds AI methods to a Playwright page you already have.
|
||||
|
||||
---
|
||||
|
||||
## Close the browser
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await browser.close()
|
||||
```
|
||||
```typescript TypeScript
|
||||
await browser.close();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Closes the browser and releases cloud resources. If connected to a cloud session, the session ends. Any unsaved state (cookies, localStorage) is lost unless you saved a [browser profile](/developers/optimization/browser-profiles) first.
|
||||
|
||||
---
|
||||
|
||||
## Proxy and geolocation
|
||||
|
||||
Route browser traffic through residential proxies in specific countries.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.launch_cloud_browser(
|
||||
proxy_location="RESIDENTIAL"
|
||||
)
|
||||
```
|
||||
```typescript TypeScript
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser({
|
||||
proxyLocation: "RESIDENTIAL",
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Available locations:
|
||||
|
||||
| Value | Region |
|
||||
|-------|--------|
|
||||
| `RESIDENTIAL` | United States (default) |
|
||||
| `RESIDENTIAL_GB` | United Kingdom |
|
||||
| `RESIDENTIAL_DE` | Germany |
|
||||
| `RESIDENTIAL_ES` | Spain |
|
||||
| `RESIDENTIAL_FR` | France |
|
||||
| `RESIDENTIAL_IE` | Ireland |
|
||||
| `RESIDENTIAL_IN` | India |
|
||||
| `RESIDENTIAL_JP` | Japan |
|
||||
| `RESIDENTIAL_AU` | Australia |
|
||||
| `RESIDENTIAL_CA` | Canada |
|
||||
| `NONE` | No proxy (direct connection) |
|
||||
|
||||
For self-hosted proxy configuration, see [Proxy Setup](/developers/self-hosted/proxy).
|
||||
|
||||
---
|
||||
|
||||
## Session persistence
|
||||
|
||||
Two mechanisms for preserving browser state between automation runs:
|
||||
|
||||
**Browser Sessions** keep a browser alive between API calls. Use `create_browser_session` from the [Tasks API](/sdk-reference/tasks/run-task) to create a session, then pass its ID to multiple `run_task` calls. See [Browser Sessions](/developers/optimization/browser-sessions).
|
||||
|
||||
**Browser Profiles** save a snapshot of browser state (cookies, localStorage) that persists indefinitely. Create a profile from a completed run, then load it into future runs to skip login. See [Browser Profiles](/developers/optimization/browser-profiles).
|
||||
|
||||
---
|
||||
|
||||
## Full reference
|
||||
|
||||
- [launch_cloud_browser](/sdk-reference/browser-automation/launch-cloud-browser)
|
||||
- [use_cloud_browser](/sdk-reference/browser-automation/use-cloud-browser)
|
||||
- [connect_to_cloud_browser_session](/sdk-reference/browser-automation/connect-to-cloud-browser-session)
|
||||
- [connect_to_browser_over_cdp](/sdk-reference/browser-automation/connect-to-browser-over-cdp)
|
||||
- [launch_local_browser](/sdk-reference/browser-automation/launch-local-browser) (Python only)
|
||||
- [get_working_page](/sdk-reference/browser-automation/get-working-page)
|
||||
- [new_page](/sdk-reference/browser-automation/new-page)
|
||||
- [get_page_for](/sdk-reference/browser-automation/get-page-for) (Python only)
|
||||
- [close](/sdk-reference/browser-automation/close)
|
||||
@@ -0,0 +1,588 @@
|
||||
---
|
||||
title: Build a Browser Automation
|
||||
subtitle: Step-by-step guide to multi-step automations with code
|
||||
description: Launch a cloud browser, interact with pages using AI and Playwright, chain agent tasks, and build complete browser automations in Python or TypeScript.
|
||||
slug: developers/browser-automations/overview
|
||||
keywords:
|
||||
- launch_cloud_browser
|
||||
- get_working_page
|
||||
- page.act
|
||||
- page.extract
|
||||
- page.validate
|
||||
- page.agent.login
|
||||
- page.agent.run_task
|
||||
- selector fallback
|
||||
- login then extract
|
||||
- multi-page
|
||||
- Playwright
|
||||
---
|
||||
|
||||
Browser automations are multi-step automations written in code. You launch a cloud browser, get a Playwright page with AI methods layered on top, and write your automation in Python or TypeScript. The code lives in your repo, runs in your CI, and deploys like any other software.
|
||||
|
||||
This is the code-first path. If you prefer building automations visually with drag-and-drop blocks, see [Workflows](/cloud/building-workflows/build-a-workflow) in the Cloud UI docs.
|
||||
|
||||
<Info>
|
||||
**Workflows vs. Browser Automation:** Workflows are built and run in the Cloud UI, no code required. Browser automations are built and run in code using Page, Agent, and Browser. Both can do multi-step work across pages. Choose based on whether your team prefers a visual editor or a code editor.
|
||||
</Info>
|
||||
|
||||
This guide walks through a real example: logging into a vendor portal, extracting invoice data, and downloading a PDF. Four steps:
|
||||
|
||||
1. **Launch a browser** and get a page
|
||||
2. **Navigate and interact** with the page using AI actions, selectors, or both
|
||||
3. **Use the agent** for complex goals like login, multi-step tasks, and file downloads
|
||||
4. **Run the script** and check results
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Launch a browser and get a page
|
||||
|
||||
Every automation starts by launching a cloud browser and getting a page. The browser is a Chromium instance hosted by Skyvern. The page is a Playwright page with AI methods added on top.
|
||||
|
||||
<Info>
|
||||
Install the SDK first if you haven't:
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python
|
||||
pip install skyvern
|
||||
```
|
||||
|
||||
```bash TypeScript
|
||||
npm install @skyvern/client
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
`pip install skyvern` is enough for Skyvern Cloud and remote API usage. If you are using embedded local mode with `Skyvern.local()` or `launch_local_browser()`, install `pip install "skyvern[local]"`. For a local self-hosted server, install `pip install "skyvern[server]"`.
|
||||
|
||||
All code snippets below run inside an async function. See the [complete example](#complete-example) for the full runnable script.
|
||||
</Info>
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from skyvern import Skyvern
|
||||
|
||||
skyvern = Skyvern(api_key="YOUR_API_KEY")
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The browser stays alive until you call `browser.close()` or the session times out (default: 60 minutes). All pages inside it share cookies, localStorage, and auth state.
|
||||
|
||||
For browser launch options (timeouts, proxies, connecting to local browsers), see [Managing Browsers](/developers/browser-automations/handle-browsers).
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Navigate and interact with the page
|
||||
|
||||
Once you have a page, you can interact with it using standard Playwright, AI actions, or both. For the full list of available methods and parameters, see the [Actions Reference](/developers/browser-automations/actions-reference).
|
||||
|
||||
### Navigate
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.goto("https://vendor-portal.example.com")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.goto("https://vendor-portal.example.com");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Use AI actions (no selectors needed)
|
||||
|
||||
Four methods let you interact with the page using natural language. Skyvern screenshots the page and determines which elements to target.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Perform any action. Returns None.
|
||||
await page.act("Click the login button")
|
||||
|
||||
# Extract structured data. Returns dict (or list if schema root is array).
|
||||
data = await page.extract(
|
||||
"Extract all product names and prices",
|
||||
schema={
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"price": {"type": "number"},
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
# Check page state. Returns bool.
|
||||
is_logged_in = await page.validate("The user is logged in")
|
||||
|
||||
# Ask the AI a question. Returns {"llm_response": str}.
|
||||
result = await page.prompt("What is the total at the bottom of the table?")
|
||||
answer = result["llm_response"]
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Perform any action. Returns void.
|
||||
await page.act("Click the login button");
|
||||
|
||||
// Extract structured data. Returns object (or array if schema root is array).
|
||||
const data = await page.extract({
|
||||
prompt: "Extract all product names and prices",
|
||||
schema: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
name: { type: "string" },
|
||||
price: { type: "number" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Check page state. Returns boolean.
|
||||
const isLoggedIn = await page.validate("The user is logged in");
|
||||
|
||||
// Ask the AI a question. Returns { llmResponse: string }.
|
||||
const result = await page.prompt("What is the total at the bottom of the table?");
|
||||
const answer = result.llmResponse;
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Use selectors with AI fallback
|
||||
|
||||
`click`, `fill`, and `select_option` accept both a CSS selector and an AI prompt. The selector runs first. If it fails, the AI takes over.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Selector only (fast, deterministic)
|
||||
await page.click("#submit-button")
|
||||
await page.fill("#email", value="user@example.com")
|
||||
|
||||
# AI only (no selector needed, resilient to layout changes)
|
||||
await page.click(prompt="Click the 'Submit' button")
|
||||
await page.fill(prompt="Fill 'user@example.com' in the email field")
|
||||
|
||||
# Both - selector first, AI fallback (best for production)
|
||||
await page.click("#submit-button", prompt="Click the 'Submit' button")
|
||||
await page.fill("#email", value="user@example.com", prompt="Fill the email field")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
// Selector only (fast, deterministic)
|
||||
await page.click("#submit-button");
|
||||
await page.fill("#email", "user@example.com");
|
||||
|
||||
// AI only (no selector needed, resilient to layout changes)
|
||||
await page.click({ prompt: "Click the 'Submit' button" });
|
||||
await page.fill({ prompt: "Fill 'user@example.com' in the email field" });
|
||||
|
||||
// Both - selector first, AI fallback (best for production)
|
||||
await page.click("#submit-button", { prompt: "Click the 'Submit' button" });
|
||||
await page.fill("#email", "user@example.com", { prompt: "Fill the email field" });
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Mix Playwright and AI
|
||||
|
||||
Standard Playwright methods work directly. Use selectors where you know the DOM, AI where you don't.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.goto("https://example.com/login")
|
||||
await page.fill("#username", value="demo@example.com") # Playwright - known selector
|
||||
await page.fill("#password", value="s3cur3-p4ss") # Playwright - known selector
|
||||
await page.click(prompt="Click the sign-in button") # AI - button text varies
|
||||
await page.wait_for_selector("#dashboard") # Playwright - wait for page load
|
||||
data = await page.extract("Extract the account balance") # AI - table layout varies
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.goto("https://example.com/login");
|
||||
await page.fill("#username", "demo@example.com"); // Playwright - known selector
|
||||
await page.fill("#password", "s3cur3-p4ss"); // Playwright - known selector
|
||||
await page.click({ prompt: "Click the sign-in button" }); // AI - button text varies
|
||||
await page.waitForSelector("#dashboard"); // Playwright - wait for page load
|
||||
const data = await page.extract({ prompt: "Extract the account balance" }); // AI
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Use the agent for complex goals
|
||||
|
||||
For multi-step goals ("log in with 2FA", "navigate to billing and download the invoice"), hand off to the agent. The agent runs a full AI task loop inside your page, preserving all browser state.
|
||||
|
||||
### Login with stored credentials
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.agent.login(
|
||||
credential_type="skyvern",
|
||||
credential_id="cred_123"
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.agent.login("skyvern", { credentialId: "cred_123" });
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The agent handles multi-page login flows, CAPTCHAs, and 2FA automatically. Four credential providers: `skyvern` (built-in vault), `bitwarden`, `onepassword`, `azure_vault`. Store credentials via the [Credentials API](/sdk-reference/credentials/create-credential).
|
||||
|
||||
### Run a multi-step task
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await page.agent.run_task(
|
||||
"Go to the billing page and extract all invoice details",
|
||||
data_extraction_schema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"invoice_number": {"type": "string"},
|
||||
"amount": {"type": "string"},
|
||||
},
|
||||
},
|
||||
)
|
||||
print(result.output)
|
||||
# {"invoice_number": "INV-2025-042", "amount": "$1,250.00"}
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await page.agent.runTask(
|
||||
"Go to the billing page and extract all invoice details",
|
||||
{
|
||||
dataExtractionSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
invoice_number: { type: "string" },
|
||||
amount: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
);
|
||||
console.log(result.output);
|
||||
// {"invoice_number": "INV-2025-042", "amount": "$1,250.00"}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
After the agent finishes, you take back control. The page retains all state:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.agent.run_task("Navigate to the settings page")
|
||||
# Agent is done - use direct page actions
|
||||
settings = await page.extract("Extract all notification preferences")
|
||||
await page.click("#save-button")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.agent.runTask("Navigate to the settings page");
|
||||
// Agent is done - use direct page actions
|
||||
const settings = await page.extract({ prompt: "Extract all notification preferences" });
|
||||
await page.click("#save-button");
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Download files
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
result = await page.agent.download_files(
|
||||
"Download the Q4 2025 financial report",
|
||||
download_suffix=".pdf",
|
||||
download_timeout=30,
|
||||
)
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
print(f"Downloaded: {file.url}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the Q4 2025 financial report",
|
||||
{ downloadSuffix: ".pdf", downloadTimeout: 30 },
|
||||
);
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
console.log(`Downloaded: ${file.url}`);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Run a workflow on the page
|
||||
|
||||
If you have built a workflow, run it on a page you already control:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
await page.agent.login(credential_type="skyvern", credential_id="cred_123")
|
||||
result = await page.agent.run_workflow(
|
||||
"wpid_monthly_report",
|
||||
parameters={"month": "2025-03"}
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await page.agent.login("skyvern", { credentialId: "cred_123" });
|
||||
const result = await page.agent.runWorkflow("wpid_monthly_report", {
|
||||
parameters: { month: "2025-03" },
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**`agent.run_workflow` vs `skyvern.run_workflow`:** The top-level `run_workflow` opens its own browser. Use `agent.run_workflow` when you need to log in first or do setup before the workflow runs.
|
||||
|
||||
---
|
||||
|
||||
## Complete example
|
||||
|
||||
Putting it all together: log into a vendor portal, extract invoices, and download a statement.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import asyncio
|
||||
from skyvern import Skyvern
|
||||
|
||||
async def main():
|
||||
skyvern = Skyvern(api_key="YOUR_API_KEY")
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
|
||||
# Navigate
|
||||
await page.goto("https://vendor-portal.example.com")
|
||||
|
||||
# Login with stored credentials
|
||||
await page.agent.login(credential_type="skyvern", credential_id="cred_abc123")
|
||||
|
||||
# Extract data using a mix of Playwright and AI
|
||||
await page.click("#billing-tab")
|
||||
invoices = await page.extract(
|
||||
"Extract all invoice numbers, dates, and amounts",
|
||||
schema={
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"invoice_number": {"type": "string"},
|
||||
"date": {"type": "string"},
|
||||
"amount": {"type": "string"},
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
# Download a file
|
||||
result = await page.agent.download_files(
|
||||
"Download the latest monthly statement",
|
||||
download_suffix=".pdf",
|
||||
)
|
||||
|
||||
# Check results
|
||||
print(f"Found {len(invoices)} invoices")
|
||||
for inv in invoices:
|
||||
print(f" {inv['invoice_number']}: {inv['amount']}")
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
print(f"Downloaded: {file.url}")
|
||||
|
||||
await browser.close()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Skyvern } from "@skyvern/client";
|
||||
|
||||
async function main() {
|
||||
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
|
||||
// Navigate
|
||||
await page.goto("https://vendor-portal.example.com");
|
||||
|
||||
// Login with stored credentials
|
||||
await page.agent.login("skyvern", { credentialId: "cred_abc123" });
|
||||
|
||||
// Extract data using a mix of Playwright and AI
|
||||
await page.click("#billing-tab");
|
||||
const invoices = await page.extract({
|
||||
prompt: "Extract all invoice numbers, dates, and amounts",
|
||||
schema: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
invoice_number: { type: "string" },
|
||||
date: { type: "string" },
|
||||
amount: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Download a file
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the latest monthly statement",
|
||||
{ downloadSuffix: ".pdf" },
|
||||
);
|
||||
|
||||
// Check results
|
||||
console.log(`Found ${invoices.length} invoices`);
|
||||
for (const inv of invoices) {
|
||||
console.log(` ${inv.invoice_number}: ${inv.amount}`);
|
||||
}
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
console.log(`Downloaded: ${file.url}`);
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Run and get results
|
||||
|
||||
Run the script:
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python
|
||||
python your_automation.py
|
||||
```
|
||||
|
||||
```bash TypeScript
|
||||
npx tsx your_automation.ts
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
You'll see the browser session URL in the console output. Open it in your browser to watch the automation run in real time.
|
||||
|
||||
### Example output
|
||||
|
||||
Here's what the Complete Example prints, grouped by the call that produced each block:
|
||||
|
||||
```text wrap
|
||||
# skyvern.launch_cloud_browser()
|
||||
[Skyvern] Launched new cloud browser session url=https://app.skyvern.com/browser-session/pbs_519895987620976102
|
||||
|
||||
# page.agent.login(...)
|
||||
[Skyvern] AI login workflow finished run_id=wr_519896041203554782 status=completed
|
||||
|
||||
# page.extract(...)
|
||||
[Skyvern] AI extract prompt=Extract all invoice numbers, dates, and amounts
|
||||
|
||||
# page.agent.download_files(...)
|
||||
[Skyvern] Starting AI file download workflow navigation_goal=Download the latest monthly statement
|
||||
[Skyvern] AI file download workflow is running, this may take a while run_id=wr_519896107880060430
|
||||
[Skyvern] AI file download workflow finished run_id=wr_519896107880060430 status=completed
|
||||
|
||||
# print(f"Found {len(invoices)} invoices") + for inv in invoices: print(...)
|
||||
Found 3 invoices
|
||||
INV-2025-042: $2,340.00
|
||||
INV-2025-043: $1,850.00
|
||||
INV-2025-044: $3,100.00
|
||||
|
||||
# for file in result.downloaded_files: print(f"Downloaded: {file.url}")
|
||||
Downloaded: https://skyvern-uploads.s3.amazonaws.com/downloads/production/o_510.../wr_519.../statement.pdf?AWS...
|
||||
```
|
||||
|
||||
The `[Skyvern] ...` lines come from the SDK's built-in logger and stream in real time as each call runs. Your own `print` output appears after the awaited call returns.
|
||||
|
||||
For the full response shape, see [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) and [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse).
|
||||
|
||||
### View results in the Cloud UI
|
||||
|
||||
Every run appears in the [Runs page](https://app.skyvern.com/runs). Click any run to see:
|
||||
- **Recording** - video of the browser session
|
||||
- **Actions** - step-by-step timeline with screenshots and AI reasoning
|
||||
- **Output** - extracted data as JSON
|
||||
- **Artifacts** - screenshots, HAR files, generated code
|
||||
|
||||
### Artifacts
|
||||
|
||||
Every run captures recordings, screenshots, AI reasoning logs, network HAR files, and downloaded files. Access them via the Cloud UI or programmatically:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
artifacts = await skyvern.get_run_artifacts(result.run_id)
|
||||
for artifact in artifacts:
|
||||
print(f"{artifact.artifact_type}: {artifact.uri}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const artifacts = await skyvern.getRunArtifacts(result.run_id);
|
||||
for (const artifact of artifacts) {
|
||||
console.log(`${artifact.artifact_type}: ${artifact.uri}`);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
For the full artifact type reference and debugging workflows, see [Using Artifacts](/developers/debugging/using-artifacts).
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Actions Reference"
|
||||
icon="list"
|
||||
href="/developers/browser-automations/actions-reference"
|
||||
>
|
||||
Every page action and agent method with parameters and return types
|
||||
</Card>
|
||||
<Card
|
||||
title="Managing Browsers"
|
||||
icon="browser"
|
||||
href="/developers/browser-automations/handle-browsers"
|
||||
>
|
||||
Launch options, multiple tabs, proxies, connecting to local browsers
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Store Credentials"
|
||||
icon="key"
|
||||
href="/sdk-reference/credentials/create-credential"
|
||||
>
|
||||
Set up credentials for automated login with the agent
|
||||
</Card>
|
||||
<Card
|
||||
title="SDK Reference"
|
||||
icon="code"
|
||||
href="/sdk-reference/complete-reference"
|
||||
>
|
||||
Every SDK method, parameter, and type on one page (Python + TypeScript)
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="API Reference"
|
||||
icon="plug"
|
||||
href="/api-reference"
|
||||
>
|
||||
Full OpenAPI spec for every REST endpoint
|
||||
</Card>
|
||||
<Card
|
||||
title="llms.txt"
|
||||
icon="file-lines"
|
||||
href="https://skyvern.com/docs/llms.txt"
|
||||
>
|
||||
Machine-readable index of the entire documentation for AI coding agents
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: Work with Files
|
||||
subtitle: Download files from websites during browser automations
|
||||
description: Use agent.download_files to navigate websites, find download links, and retrieve files. Access downloaded files via presigned URLs.
|
||||
slug: developers/browser-automations/work-with-files
|
||||
keywords:
|
||||
- download_files
|
||||
- downloaded_files
|
||||
- presigned URL
|
||||
- PDF
|
||||
- invoice
|
||||
- download_suffix
|
||||
- download_timeout
|
||||
- FileInfo
|
||||
---
|
||||
|
||||
In a browser automation, `agent.download_files` navigates a page, finds the download link, and captures the file. Downloaded files are stored in Skyvern's cloud storage and returned as presigned URLs in the response.
|
||||
|
||||
If you're building workflows in the Cloud UI instead, use the File Download block. See [Block Types and Configuration](/cloud/building-workflows/configure-blocks).
|
||||
|
||||
---
|
||||
|
||||
## Download a file
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
browser = await skyvern.launch_cloud_browser()
|
||||
page = await browser.get_working_page()
|
||||
|
||||
await page.goto("https://portal.example.com")
|
||||
await page.agent.login(credential_type="skyvern", credential_id="cred_123")
|
||||
|
||||
result = await page.agent.download_files(
|
||||
"Download the Q4 2025 financial report",
|
||||
download_suffix=".pdf",
|
||||
download_timeout=30,
|
||||
)
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
print(f"File: {file.filename}")
|
||||
print(f"URL: {file.url}")
|
||||
print(f"Checksum: {file.checksum}")
|
||||
|
||||
await browser.close()
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const browser = await skyvern.launchCloudBrowser();
|
||||
const page = await browser.getWorkingPage();
|
||||
|
||||
await page.goto("https://portal.example.com");
|
||||
await page.agent.login("skyvern", { credentialId: "cred_123" });
|
||||
|
||||
const result = await page.agent.downloadFiles(
|
||||
"Download the Q4 2025 financial report",
|
||||
{ downloadSuffix: ".pdf", downloadTimeout: 30 },
|
||||
);
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
console.log(`File: ${file.filename}`);
|
||||
console.log(`URL: ${file.url}`);
|
||||
console.log(`Checksum: ${file.checksum}`);
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `prompt` | `str` / `string` | Yes | Describe what to download. The agent navigates the page to find and click the download link. |
|
||||
| `url` | `str` / `string` | No | URL to navigate to before downloading. Defaults to the current page URL. |
|
||||
| `download_suffix` | `str` / `string` | No | Filename hint prepended to the saved file (e.g., `"invoice"` → `invoice.pdf`). **Not a validator**; mismatched extensions don't fail the run. Omit this to get a system-generated filename like `download-<timestamp>-<random>.pdf`. |
|
||||
| `download_timeout` | `float` / `number` | No | Soft hint (seconds) for how long to wait for a download to start. Not a hard cap; the overall `timeout` below governs failure. |
|
||||
| `max_steps_per_run` | `int` / `number` | No | Cap AI steps for the download navigation. |
|
||||
| `timeout` | `float` / `number` | No | Total timeout in seconds (default: 1800). |
|
||||
|
||||
---
|
||||
|
||||
## Response
|
||||
|
||||
`agent.download_files` returns a `WorkflowRunResponse`. The downloaded files are in the `downloaded_files` field.
|
||||
|
||||
### Response fields
|
||||
|
||||
Most-used fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `run_id` | `str` | Run identifier (prefix: `wr_`) |
|
||||
| `status` | `str` | `completed`, `failed`, `terminated`, `timed_out`, or `canceled` |
|
||||
| `downloaded_files` | `list[FileInfo]` | Files captured during the run |
|
||||
| `output` | `dict \| None` | Any extracted data (may be `None` even on `completed`) |
|
||||
| `app_url` | `str` | Link to view this run in the Cloud UI |
|
||||
| `recording_url` | `str \| None` | Video recording of the download session |
|
||||
| `failure_reason` | `str \| None` | Error description if the download failed |
|
||||
| `step_count` | `int` | Number of AI steps taken |
|
||||
|
||||
See the [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) reference for the full field list.
|
||||
|
||||
### FileInfo fields
|
||||
|
||||
Each file in `downloaded_files` has:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `url` | `str` | Presigned URL to download the file. Valid for a limited time. |
|
||||
| `filename` | `str \| None` | Saved filename. Reflects `download_suffix` if you set one, otherwise system-generated. |
|
||||
| `checksum` | `str \| None` | SHA-256 checksum for integrity verification |
|
||||
| `file_size` | `int \| None` | Size of the file in bytes |
|
||||
| `modified_at` | `datetime \| None` | Last-modified timestamp if the source provides one |
|
||||
|
||||
---
|
||||
|
||||
## Where files are stored
|
||||
|
||||
Files are stored in Skyvern's managed cloud storage (S3). You access them through the presigned URLs returned in `downloaded_files`. Files are not saved to your local machine automatically.
|
||||
|
||||
To save a file locally:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import requests
|
||||
|
||||
for file in result.downloaded_files or []:
|
||||
response = requests.get(file.url)
|
||||
with open(file.filename or "download.pdf", "wb") as f:
|
||||
f.write(response.content)
|
||||
print(f"Saved {file.filename}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import fs from "fs";
|
||||
|
||||
for (const file of result.downloadedFiles ?? []) {
|
||||
const response = await fetch(file.url);
|
||||
const buffer = await response.arrayBuffer();
|
||||
fs.writeFileSync(file.filename ?? "download.pdf", Buffer.from(buffer));
|
||||
console.log(`Saved ${file.filename}`);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Set `download_suffix`** to get a predictable filename (e.g., `"invoice-q4"` → `invoice-q4.pdf`). Without it, files are saved with a system-generated name like `download-<timestamp>-<random>.pdf`. It does **not** validate or filter by extension.
|
||||
|
||||
**Raise the overall `timeout`** for large files. `download_timeout` is a soft hint; `timeout` is what actually fails the run.
|
||||
|
||||
**Verify with checksums.** The `checksum` field contains a SHA-256 hash. Compare it against expected values to verify file integrity.
|
||||
|
||||
**Login first.** Most download portals require authentication. Call `agent.login` before `agent.download_files` - the agent reuses the authenticated session.
|
||||
|
||||
---
|
||||
|
||||
## File operations in workflows
|
||||
|
||||
If you build workflows in the Cloud UI, file operations use dedicated blocks instead of `agent.download_files`:
|
||||
|
||||
| Block | Purpose |
|
||||
|-------|---------|
|
||||
| **File Download** | Download files during workflow execution |
|
||||
| **File Parser** | Parse PDFs, CSVs, and Excel files |
|
||||
| **Download to S3** | Save files from URLs to Skyvern's S3 |
|
||||
| **Upload to S3** | Upload workflow files to S3 |
|
||||
| **File Upload** | Upload to your own S3 or Azure Blob Storage |
|
||||
|
||||
Files downloaded during a workflow accumulate in a temporary directory and can be passed between blocks using workflow parameters. See [Workflow Blocks Reference](/cloud/building-workflows/configure-blocks) for block configuration details.
|
||||
|
||||
---
|
||||
|
||||
## Full reference
|
||||
|
||||
- [agent.download_files](/sdk-reference/browser-automation/agent-download-files) - SDK reference with all parameter options
|
||||
- [Using Artifacts](/developers/debugging/using-artifacts) - access recordings, screenshots, and downloaded files from any run
|
||||
Reference in New Issue
Block a user