275 lines
9.0 KiB
Plaintext
275 lines
9.0 KiB
Plaintext
---
|
|
title: Workflows
|
|
subtitle: Create and run multi-step browser automations
|
|
slug: sdk-reference/workflows
|
|
---
|
|
|
|
A workflow chains multiple steps (blocks) into a single automation. Workflows support loops, conditionals, data passing between steps, and code-based re-execution.
|
|
|
|
For conceptual background, see [Build a Workflow](/multi-step-automations/build-a-workflow).
|
|
|
|
---
|
|
|
|
## `run_workflow`
|
|
|
|
Execute a workflow by its permanent ID. Skyvern opens a cloud browser and runs each block in sequence.
|
|
|
|
```python
|
|
result = await client.run_workflow(
|
|
workflow_id="wpid_abc123",
|
|
wait_for_completion=True,
|
|
)
|
|
print(result.output)
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| `workflow_id` | `str` | Yes | — | The workflow's permanent ID (`wpid_...`). |
|
|
| `parameters` | `dict` | No | `None` | Input parameters defined in the workflow. Keys must match parameter names. |
|
|
| `wait_for_completion` | `bool` | No | `False` | Block until the workflow finishes. |
|
|
| `timeout` | `float` | No | `1800` | Max wait time in seconds when `wait_for_completion=True`. |
|
|
| `run_with` | `str` | No | `None` | Force execution mode: `"code"` (use cached Playwright code) or `"agent"` (use AI). |
|
|
| `ai_fallback` | `bool` | No | `None` | Fall back to AI if the cached code fails. |
|
|
| `browser_session_id` | `str` | No | `None` | Run inside an existing [browser session](/optimization/browser-sessions). |
|
|
| `browser_profile_id` | `str` | No | `None` | Load a [browser profile](/optimization/browser-profiles) (cookies, storage) into the session. |
|
|
| `proxy_location` | `ProxyLocation` | No | `None` | Route the browser through a geographic proxy. |
|
|
| `max_steps_override` | `int` | No | `None` | Cap total AI steps across all blocks. |
|
|
| `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
|
|
| `title` | `str` | No | `None` | Display name for this run in the dashboard. |
|
|
| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
|
|
| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
|
|
| `template` | `bool` | No | `None` | Run a template workflow. |
|
|
| `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
|
|
| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |
|
|
| `max_screenshot_scrolls` | `int` | No | `None` | Number of scrolls for post-action screenshots. |
|
|
| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address. |
|
|
|
|
### Returns `WorkflowRunResponse`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `run_id` | `str` | Unique identifier. Starts with `wr_` for workflow runs. |
|
|
| `status` | `str` | `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. |
|
|
| `output` | `dict \| None` | Extracted data from the workflow's output block. |
|
|
| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
|
|
| `recording_url` | `str \| None` | URL to the session recording. |
|
|
| `failure_reason` | `str \| None` | Error description if the run failed. |
|
|
| `app_url` | `str \| None` | Link to view this run in the Cloud UI. |
|
|
| `step_count` | `int \| None` | Total AI steps taken across all blocks. |
|
|
| `run_with` | `str \| None` | Whether the run used `"code"` or `"agent"`. |
|
|
| `ai_fallback` | `bool \| None` | Whether AI fallback was configured. |
|
|
| `script_run` | `ScriptRunResponse \| None` | Code execution result. Contains `ai_fallback_triggered` if code was used. |
|
|
|
|
### Examples
|
|
|
|
**Pass parameters to a workflow:**
|
|
|
|
```python
|
|
result = await client.run_workflow(
|
|
workflow_id="wpid_invoice_extraction",
|
|
parameters={
|
|
"company_name": "Acme Corp",
|
|
"date_range": "2025-01-01 to 2025-12-31",
|
|
},
|
|
wait_for_completion=True,
|
|
)
|
|
```
|
|
|
|
**Run with cached code (skip AI, use generated Playwright scripts):**
|
|
|
|
```python
|
|
result = await client.run_workflow(
|
|
workflow_id="wpid_daily_report",
|
|
run_with="code",
|
|
ai_fallback=True, # Fall back to AI if code fails
|
|
wait_for_completion=True,
|
|
)
|
|
```
|
|
|
|
**Run with a browser profile (skip login):**
|
|
|
|
```python
|
|
result = await client.run_workflow(
|
|
workflow_id="wpid_daily_report",
|
|
browser_profile_id="bpf_abc123",
|
|
wait_for_completion=True,
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## `create_workflow`
|
|
|
|
Create a new workflow from a JSON or YAML definition.
|
|
|
|
```python
|
|
workflow = await client.create_workflow(
|
|
json_definition={
|
|
"blocks": [
|
|
{
|
|
"block_type": "task",
|
|
"label": "extract_data",
|
|
"prompt": "Extract the top 3 products",
|
|
"url": "https://example.com/products",
|
|
}
|
|
],
|
|
"parameters": [],
|
|
},
|
|
)
|
|
print(workflow.workflow_permanent_id)
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `json_definition` | `WorkflowCreateYamlRequest` | No | Workflow definition as a JSON object. |
|
|
| `yaml_definition` | `str` | No | Workflow definition as a YAML string. |
|
|
| `folder_id` | `str` | No | Folder to organize the workflow in. |
|
|
|
|
You must provide either `json_definition` or `yaml_definition`.
|
|
|
|
### Returns `Workflow`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `workflow_id` | `str` | Unique ID for this version. |
|
|
| `workflow_permanent_id` | `str` | Stable ID across all versions. Use this to run workflows. |
|
|
| `version` | `int` | Version number. |
|
|
| `title` | `str` | Workflow title. |
|
|
| `workflow_definition` | `WorkflowDefinition` | The full definition including blocks and parameters. |
|
|
| `status` | `str \| None` | Workflow status. |
|
|
| `created_at` | `datetime` | When the workflow was created. |
|
|
|
|
---
|
|
|
|
## `get_workflows`
|
|
|
|
List all workflows. Supports filtering and pagination.
|
|
|
|
```python
|
|
workflows = await client.get_workflows()
|
|
for wf in workflows:
|
|
print(f"{wf.title} ({wf.workflow_permanent_id})")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| `page` | `int` | No | `None` | Page number for pagination. |
|
|
| `page_size` | `int` | No | `None` | Number of results per page. |
|
|
| `only_saved_tasks` | `bool` | No | `None` | Only return saved tasks. |
|
|
| `only_workflows` | `bool` | No | `None` | Only return workflows (not saved tasks). |
|
|
| `only_templates` | `bool` | No | `None` | Only return templates. |
|
|
| `title` | `str` | No | `None` | Filter by exact title. |
|
|
| `search_key` | `str` | No | `None` | Search by title. |
|
|
| `folder_id` | `str` | No | `None` | Filter by folder. |
|
|
| `status` | `WorkflowStatus \| list[WorkflowStatus]` | No | `None` | Filter by status. |
|
|
|
|
### Returns `list[Workflow]`
|
|
|
|
---
|
|
|
|
## `get_workflow`
|
|
|
|
<Info>
|
|
Requires `skyvern` version 1.1.0 or later. Run `pip install --upgrade skyvern` to update.
|
|
</Info>
|
|
|
|
Get a specific workflow by its permanent ID.
|
|
|
|
```python
|
|
workflow = await client.get_workflow("wpid_abc123")
|
|
print(workflow.title, f"v{workflow.version}")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `workflow_permanent_id` | `str` | Yes | The workflow's permanent ID. |
|
|
| `version` | `int` | No | Specific version to retrieve. Defaults to latest. |
|
|
| `template` | `bool` | No | Whether to fetch a template workflow. |
|
|
|
|
### Returns `Workflow`
|
|
|
|
---
|
|
|
|
## `get_workflow_versions`
|
|
|
|
<Info>
|
|
Requires `skyvern` version 1.1.0 or later. Run `pip install --upgrade skyvern` to update.
|
|
</Info>
|
|
|
|
List all versions of a workflow.
|
|
|
|
```python
|
|
versions = await client.get_workflow_versions("wpid_abc123")
|
|
for v in versions:
|
|
print(f"v{v.version} — {v.modified_at}")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `workflow_permanent_id` | `str` | Yes | The workflow's permanent ID. |
|
|
| `template` | `bool` | No | Whether to fetch template versions. |
|
|
|
|
### Returns `list[Workflow]`
|
|
|
|
---
|
|
|
|
## `update_workflow`
|
|
|
|
Update an existing workflow's definition.
|
|
|
|
```python
|
|
updated = await client.update_workflow(
|
|
"wf_abc123",
|
|
json_definition={
|
|
"blocks": [
|
|
{
|
|
"block_type": "task",
|
|
"label": "extract_data",
|
|
"prompt": "Extract the top 5 products",
|
|
"url": "https://example.com/products",
|
|
}
|
|
],
|
|
"parameters": [],
|
|
},
|
|
)
|
|
print(f"Updated to v{updated.version}")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `workflow_id` | `str` | Yes | The workflow version ID (not the permanent ID). |
|
|
| `json_definition` | `WorkflowCreateYamlRequest` | No | Updated workflow definition as JSON. |
|
|
| `yaml_definition` | `str` | No | Updated workflow definition as YAML. |
|
|
|
|
### Returns `Workflow`
|
|
|
|
Creates a new version of the workflow.
|
|
|
|
---
|
|
|
|
## `delete_workflow`
|
|
|
|
Delete a workflow.
|
|
|
|
```python
|
|
await client.delete_workflow("wf_abc123")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `workflow_id` | `str` | Yes | The workflow version ID to delete. |
|