Skip to main content

​
Overview

The Skyvern Python SDK provides a Playwright-compatible interface with AI-powered browser automation capabilities. It combines traditional browser automation with AI-powered task execution, allowing you to use natural language prompts alongside standard Playwright methods.

​
Installation

pip install skyvern

​
Initialization

​
Remote Mode (Skyvern Cloud)

Connect to Skyvern Cloud or a self-hosted instance: 
from skyvern import Skyvern

skyvern = Skyvern(api_key="your-api-key")
Parameters:
  • api_key (str, required): API key for authenticating with Skyvern. Get yours at app.skyvern.com/settings
  • environment (SkyvernEnvironment, optional): The Skyvern environment to connect to
    • SkyvernEnvironment.CLOUD (default) - Skyvern Cloud
    • SkyvernEnvironment.STAGING - Staging environment
    • SkyvernEnvironment.PRODUCTION - Self-hosted production
  • base_url (str, optional): Override the base URL for the Skyvern API
  • timeout (float, optional): Timeout in seconds for API requests
  • follow_redirects (bool, optional): Whether to follow HTTP redirects (default: True)
  • httpx_client (httpx.AsyncClient, optional): Custom httpx client for API requests

​
Local/Embedded Mode

Run Skyvern locally in-process: 
from skyvern import Skyvern

# Uses LLM_KEY from your .env file
skyvern = Skyvern.local()
Prerequisites: Run skyvern quickstart first to set up your environment and create a .env file. Parameters:
  • llm_config (LLMRouterConfig | LLMConfig, optional): Custom LLM configuration. If provided, overrides the LLM_KEY setting from .env
  • settings (dict[str, Any], optional): Dictionary of settings to override from .env (e.g., {"MAX_STEPS_PER_RUN": 100})
Custom LLM Configuration Examples: 
from skyvern import Skyvern
from skyvern.forge.sdk.api.llm.models import LLMConfig, LiteLLMParams

# Using environment variables
skyvern = Skyvern.local(
    llm_config=LLMConfig(
        model_name="gpt-4o",
        required_env_vars=["OPENAI_API_KEY"],
        supports_vision=True,
        add_assistant_prefix=False,
    )
)

# Explicitly providing credentials
skyvern = Skyvern.local(
    llm_config=LLMConfig(
        model_name="gpt-4o",
        required_env_vars=[],
        supports_vision=True,
        add_assistant_prefix=False,
        litellm_params=LiteLLMParams(
            api_base="https://api.openai.com/v1",
            api_key="sk-...",
        ),
    )
)

​
Browser Management

​
Launch Cloud Browser

Launch a new cloud-hosted browser session: 
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
Parameters:
  • timeout (int, optional): Timeout in minutes for the session (between 5-1440, default: 60)
  • proxy_location (ProxyLocation, optional): Geographic proxy location for browser traffic (Skyvern Cloud only)

​
Use Cloud Browser

Get or create a cloud browser session (reuses existing session if available): 
browser = await skyvern.use_cloud_browser()
page = await browser.get_working_page()
Parameters: Same as launch_cloud_browser()

​
Connect to Existing Cloud Session

Connect to an existing cloud browser session by ID: 
browser = await skyvern.connect_to_cloud_browser_session("browser_session_id")
page = await browser.get_working_page()
Parameters:
  • browser_session_id (str, required): The ID of the cloud browser session

​
Launch Local Browser

Launch a new local Chromium browser with CDP enabled: 
browser = await skyvern.launch_local_browser(headless=False)
page = await browser.get_working_page()
Parameters:
  • headless (bool, optional): Run browser in headless mode (default: False)
  • port (int, optional): CDP endpoint port (default: 9222)
  • args (list[str], optional): Additional Chromium command-line arguments
  • user_data_dir (str, optional): Custom user data directory path

​
Connect to Browser via CDP

Connect to an existing browser via Chrome DevTools Protocol: 
browser = await skyvern.connect_to_browser_over_cdp("http://localhost:9222")
page = await browser.get_working_page()
Parameters:
  • cdp_url (str, required): The CDP WebSocket URL

​
Task Execution

​
Run Task

Execute a one-off AI-powered browser automation task: 
task_run = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
    url="https://news.ycombinator.com",
    wait_for_completion=True,
)

print(task_run.status)  # "completed", "failed", etc.
print(task_run.extracted_information)  # Extracted data
Parameters:
  • prompt (str, required): Natural language description of the task
  • engine (RunEngine, optional): Execution engine (default: RunEngine.skyvern_v2)
  • model (dict[str, Any], optional): LLM model configuration options
  • url (str, optional): Starting URL for the task
  • webhook_url (str, optional): URL for webhook notifications
  • totp_identifier (str, optional): TOTP identifier for 2FA
  • totp_url (str, optional): URL to fetch TOTP codes
  • title (str, optional): Human-readable title for the task
  • error_code_mapping (dict[str, str], optional): Custom error code mappings
  • data_extraction_schema (dict[str, Any] | str, optional): Schema for extracted data
  • proxy_location (ProxyLocation, optional): Geographic proxy location
  • max_steps (int, optional): Maximum number of steps
  • wait_for_completion (bool, optional): Wait for task to complete (default: False)
  • timeout (float, optional): Timeout in seconds (default: 1800)
  • browser_session_id (str, optional): Use existing browser session
  • user_agent (str, optional): Custom user agent
  • extra_http_headers (dict[str, str], optional): Additional HTTP headers
  • publish_workflow (bool, optional): Publish as workflow (default: False)
  • include_action_history_in_verification (bool, optional): Include action history
  • max_screenshot_scrolls (int, optional): Maximum screenshot scrolls
  • browser_address (str, optional): Custom browser address
Returns: TaskRunResponse with execution results Data Extraction Example: 
task_run = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
    url="https://news.ycombinator.com",
    data_extraction_schema={
        "type": "object",
        "properties": {
            "title": {"type": "string", "description": "Post title"},
            "url": {"type": "string", "description": "Post URL"},
            "points": {"type": "integer", "description": "Post points"},
        },
    },
    wait_for_completion=True,
)

print(task_run.extracted_information)

​
Run Workflow

Execute a pre-defined workflow: 
workflow_run = await skyvern.run_workflow(
    workflow_id="wkfl_123",
    parameters={"user_email": "[email protected]"},
    wait_for_completion=True,
)

print(workflow_run.status)
Parameters:
  • workflow_id (str, required): ID of the workflow to execute
  • parameters (dict[str, Any], optional): Workflow parameters
  • template (bool, optional): Whether this is a template
  • title (str, optional): Human-readable title
  • proxy_location (ProxyLocation, optional): Geographic proxy location
  • webhook_url (str, optional): Webhook notification URL
  • totp_url (str, optional): TOTP URL
  • totp_identifier (str, optional): TOTP identifier
  • browser_session_id (str, optional): Use existing browser session
  • max_steps_override (int, optional): Override max steps
  • user_agent (str, optional): Custom user agent
  • browser_profile_id (str, optional): Browser profile ID
  • max_screenshot_scrolls (int, optional): Maximum screenshot scrolls
  • extra_http_headers (dict[str, str], optional): Additional headers
  • browser_address (str, optional): Custom browser address
  • ai_fallback (bool, optional): Enable AI fallback
  • run_with (str, optional): Run with specific configuration
  • wait_for_completion (bool, optional): Wait for completion (default: False)
  • timeout (float, optional): Timeout in seconds (default: 1800)
Returns: WorkflowRunResponse with execution results

​
Login

Execute a login workflow with stored credentials: 
from skyvern.schemas.run_blocks import CredentialType

workflow_run = await skyvern.login(
    credential_type=CredentialType.skyvern,
    credential_id="cred_123",
    url="https://example.com/login",
    wait_for_completion=True,
)
Parameters:
  • credential_type (CredentialType, required): Type of credential
    • CredentialType.skyvern - Skyvern-stored credentials
    • CredentialType.bitwarden - Bitwarden credentials
    • CredentialType.onepassword - 1Password credentials
    • CredentialType.azure_vault - Azure Key Vault credentials
  • url (str, optional): Login page URL
  • credential_id (str, optional): Skyvern credential ID (for CredentialType.skyvern)
  • bitwarden_collection_id (str, optional): Bitwarden collection ID
  • bitwarden_item_id (str, optional): Bitwarden item ID
  • onepassword_vault_id (str, optional): 1Password vault ID
  • onepassword_item_id (str, optional): 1Password item ID
  • azure_vault_name (str, optional): Azure vault name
  • azure_vault_username_key (str, optional): Azure username key
  • azure_vault_password_key (str, optional): Azure password key
  • azure_vault_totp_secret_key (str, optional): Azure TOTP secret key
  • prompt (str, optional): Custom login instructions
  • webhook_url (str, optional): Webhook notification URL
  • proxy_location (ProxyLocation, optional): Geographic proxy location
  • totp_identifier (str, optional): TOTP identifier
  • totp_url (str, optional): TOTP URL
  • browser_session_id (str, optional): Use existing browser session
  • browser_address (str, optional): Custom browser address
  • extra_http_headers (dict[str, str], optional): Additional headers
  • max_screenshot_scrolling_times (int, optional): Max screenshot scrolls
  • wait_for_completion (bool, optional): Wait for completion (default: False)
  • timeout (float, optional): Timeout in seconds (default: 1800)
Returns: WorkflowRunResponse with execution results

​
Resource Management

​
Close Resources

Close Playwright and release resources: 
await skyvern.aclose()

​
Properties

​
environment

Get the current Skyvern environment: 
env = skyvern.environment
# Returns: SkyvernEnvironment.CLOUD, .STAGING, .LOCAL, or None

​
Complete Example

import asyncio
from skyvern import Skyvern
from skyvern.schemas.run_blocks import CredentialType

async def main():
    # Initialize Skyvern
    skyvern = Skyvern(api_key="your-api-key")
    
    # Create credentials
    credential = await skyvern.create_credential(
        name="my_user",
        credential_type="password",
        credential={"username": "[email protected]", "password": "secret"},
    )
    
    # Launch cloud browser
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    
    # Mix traditional Playwright with AI
    await page.goto("https://example.com")
    
    # AI-powered login
    await page.agent.login(
        credential_type=CredentialType.skyvern,
        credential_id=credential.credential_id,
    )
    
    # Traditional browser control
    await page.click("#invoices-button")
    await page.fill("#search", "my invoice")
    
    # Take screenshot
    await page.screenshot(path="screenshot.png", full_page=True)
    
    # Close browser
    await browser.close()
    await skyvern.aclose()

asyncio.run(main())

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us