--- title: Core Concepts subtitle: The building blocks of Skyvern automations slug: getting-started/core-concepts --- Skyvern has eight core concepts. Master these and you can build any browser automation. --- ## Tasks A **Task** is a single automation job—think of it as asking Skyvern to do one thing. You provide a prompt describing the goal, and Skyvern navigates the browser to complete it. ```python from skyvern import Skyvern skyvern = Skyvern(api_key="YOUR_API_KEY") result = await skyvern.run_task( prompt="Find the top 3 posts on the front page", url="https://news.ycombinator.com", data_extraction_schema={ "type": "object", "properties": { "posts": { "type": "array", "items": {"type": "string"} } } } ) print(result.output) # {"posts": ["Post 1", "Post 2", "Post 3"]} ``` **Key properties:** | Property | Description | |----------|-------------| | `prompt` | Natural language description of the goal (required) | | `url` | Starting URL for the task | | `data_extraction_schema` | JSON Schema defining expected output structure | | `max_steps` | Maximum steps allowed (controls cost) | | `engine` | AI model to use (see [Engines](#engines) below) | | `browser_session_id` | Run in an existing browser session | | `webhook_url` | Callback URL for async completion | **Use Tasks for:** one-off automations, quick data extraction, prototyping before building a workflow. When you need reusable, multi-step automations, use **Workflows** instead. --- ## Workflows A **Workflow** is a reusable template composed of blocks. Unlike tasks, workflows can be versioned, shared across your team, and executed repeatedly with different parameters. ``` ┌─────────────────────────────────────────────────────────────┐ │ WORKFLOW │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Navigate │ → │ Login │ → │ Extract │ → │ Download │ │ │ │ Block │ │ Block │ │ Block │ │ Block │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ Parameters: {{search_query}}, {{max_price}} │ │ Each block can reference outputs from previous blocks │ └─────────────────────────────────────────────────────────────┘ ``` ```python result = await skyvern.run_workflow( workflow_id="wpid_abc123", parameters={ "search_query": "wireless headphones", "max_price": 100 } ) print(result.output) ``` Workflows support Jinja templating: - Reference parameters: `{{search_query}}` - Reference previous block outputs: `{{extract_block.product_name}}` **Use Workflows for:** repeatable automations, multi-step processes, team-shared templates, complex logic with loops or conditionals. See [Workflow Blocks](/workflows/workflow-blocks-details) for the full block reference. --- ## Blocks Blocks are the building units of workflows. Each block performs one specific task, and blocks execute sequentially—each can reference outputs from previous blocks. ### Navigation & Interaction | Block | Purpose | |-------|---------| | **Navigation** | AI-guided navigation toward a goal—Skyvern figures out the clicks and inputs | | **Action** | Perform a single specific action (click, type, select, upload) | | **Go to URL** | Navigate directly to a specific URL | | **Login** | Authenticate using stored credentials | | **Wait** | Pause execution for a specified duration | | **Human Interaction** | Pause for manual intervention (CAPTCHA, approval, etc.) | ### Data & Files | Block | Purpose | |-------|---------| | **Extract** | Pull structured data from a page into JSON | | **File Download** | Download files from websites | | **File Upload** | Upload files to form fields | | **File Parser** | Process PDFs, CSVs, and Excel files | | **PDF Parser** | Specialized PDF text extraction | ### Logic & Control Flow | Block | Purpose | |-------|---------| | **Conditional** | Branch workflow based on conditions (if/else) | | **For Loop** | Repeat a sequence of blocks over a list | | **Validation** | Assert conditions; halt workflow on failure | | **Code** | Execute custom Python/Playwright scripts | ### Communication & Integration | Block | Purpose | |-------|---------| | **HTTP Request** | Make API calls to external services | | **Text Prompt** | Text-only LLM prompt (no browser interaction) | | **Send Email** | Send email messages | For detailed block configuration, see [Workflow Blocks](/workflows/workflow-blocks-details). --- ## Runs Every time you execute a task or workflow, Skyvern creates a **Run** to track progress and store outputs. ``` ┌→ completed │ ├→ failed │ created → queued → running ─┼→ timed_out │ ├→ terminated │ └→ canceled ``` ```python result = await skyvern.run_task( prompt="Extract the main heading", url="https://example.com" ) print(result.run_id) # "tsk_abc123" print(result.status) # "completed" print(result.output) # {"heading": "Welcome"} ``` **Run identifiers:** - Task runs: `tsk_*` prefix - Workflow runs: `wr_*` prefix **Run response fields:** | Field | Description | |-------|-------------| | `run_id` | Unique identifier | | `status` | Current lifecycle state | | `output` | Extracted data (matches your schema) | | `recording_url` | Video of the execution | | `screenshot_urls` | Screenshots captured during execution | | `downloaded_files` | Files retrieved (with URLs and checksums) | | `failure_reason` | Error details if failed | | `step_count` | Number of steps taken | **Billing:** You're billed per step. A step is one AI decision + action cycle. Use `max_steps` to cap costs during development. --- ## Credentials Credentials provide secure storage for authentication data. Skyvern encrypts credentials at rest and in transit, and injects them directly into the browser—**credentials are never sent to or seen by the LLM**. ``` ┌─────────────────────────────────────────────────────────────┐ │ SECURITY MODEL │ │ │ │ You store credentials Skyvern encrypts & stores │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────────┐ │ │ │ Skyvern UI │ │ Encrypted Vault │ │ │ │ or API │ ─────────── │ (or Bitwarden, │ │ │ └─────────────┘ │ 1Password) │ │ │ └────────┬────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ Login Block │ │ │ │ injects into │ │ │ │ browser fields │ │ │ └─────────────────┘ │ │ │ │ │ LLM sees: "login happened" │ │ LLM never sees: actual credentials │ └─────────────────────────────────────────────────────────────┘ ``` **Supported credential types:** - Usernames and passwords - TOTP codes (authenticator apps) - Credit cards **Credential sources:** - **Skyvern** — Native encrypted storage - **Bitwarden** — Sync from your Bitwarden vault - **1Password** — Sync from your 1Password vault - **Azure Key Vault** — Enterprise secret management See [Credentials](/credentials/introduction) for setup instructions. --- ## Browser Sessions & Profiles Skyvern offers two ways to manage browser state across runs: ``` ┌─────────────────────────────────────────────────────────────┐ │ │ │ BROWSER SESSION BROWSER PROFILE │ │ (live, temporary) (saved, reusable) │ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Active │ ──save──▶ │ Snapshot │ │ │ │ Browser │ │ of state │ │ │ │ Instance │ ◀──restore── │ (cookies, │ │ │ └─────────────┘ │ storage) │ │ │ └─────────────┘ │ │ • Expires after timeout • Persists indefinitely │ │ • For real-time chaining • For skipping login │ │ • Max 24 hours • Shared across team │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Browser Sessions A live browser instance that maintains state across multiple tasks. Use sessions when you need to chain tasks in real-time or allow human intervention. ```python # Create a session (default: 60 minutes, max: 24 hours) session = await skyvern.create_browser_session(timeout=120) # Run tasks in the same session await skyvern.run_task( prompt="Log in with the test account", url="https://example.com/login", browser_session_id=session.browser_session_id ) # Second task reuses the authenticated state await skyvern.run_task( prompt="Extract the account balance", url="https://example.com/dashboard", browser_session_id=session.browser_session_id ) # Clean up await skyvern.close_browser_session( browser_session_id=session.browser_session_id ) ``` **Session limits:** 5 to 1,440 minutes (24 hours max). Default: 60 minutes. ### Browser Profiles A saved snapshot of browser state. Unlike sessions, profiles persist indefinitely and can be reused across days or weeks—perfect for skipping login on repeated runs. ```python # Create a profile from a completed run profile = await skyvern.browser_profiles.create_browser_profile( name="my-authenticated-profile", workflow_run_id=run.run_id ) # Future runs restore the authenticated state await skyvern.run_workflow( workflow_id="wpid_extract_data", browser_profile_id=profile.browser_profile_id ) ``` **What's saved:** Cookies, authentication tokens, local storage, session storage. See [Browser Sessions](/browser-sessions/introduction) for details. --- ## Artifacts Every run generates artifacts for observability, debugging, and audit trails. ```python result = await skyvern.run_task( prompt="Download the quarterly report", url="https://example.com" ) print(result.recording_url) # Full video of execution print(result.screenshot_urls) # List of screenshot URLs print(result.downloaded_files) # [{"url": "...", "checksum": "..."}] ``` | Artifact | Description | |----------|-------------| | **Recordings** | End-to-end video of the entire run | | **Screenshots** | Captured after each action | | **Downloaded files** | Files retrieved during execution | | **Logs** | JSON-structured logs at step, task, and workflow levels | | **HAR files** | HTTP Archive data for network debugging | In the Skyvern UI, go to **Runs** → click a run → view the **Actions** and **Recording** tabs. --- ## Engines Skyvern supports multiple AI engines for task execution: | Engine | Description | |--------|-------------| | `skyvern-2.0` | Latest Skyvern model (default, recommended) | | `skyvern-1.0` | Previous Skyvern model | | `openai-cua` | OpenAI Computer Use Agent | | `anthropic-cua` | Anthropic Computer Use Agent | | `ui-tars` | UI-TARS model | Specify the engine when running a task: ```python result = await skyvern.run_task( prompt="Extract pricing data", url="https://example.com", engine="skyvern-2.0" ) ``` --- ## Quick Reference | I want to... | Use | |--------------|-----| | Run a one-off automation | [Task](#tasks) | | Build a reusable multi-step process | [Workflow](#workflows) | | Keep a browser open between tasks | [Browser Session](#browser-sessions) | | Skip login on repeated runs | [Browser Profile](#browser-profiles) | | Store secrets securely | [Credentials](#credentials) | | Debug a failed run | [Artifacts](#artifacts) | --- ## Next Steps Run your first task in 5 minutes Create multi-step automations Full reference for all block types Complete API documentation