Skip to content

Automate browser based workflows with AI

Skyvern SDK Prototype (#3624)

Stanislav Novosadfb2464121286
diff --git a/skyvern/client/client.py b/skyvern/client/client.py
index 7f6183635..3bfc49de2 100644
--- a/skyvern/client/client.py
+++ b/skyvern/client/client.py
@@ -1959,6 +1959,7 @@ class AsyncSkyvern:
totp_identifier: typing.Optional[str] = OMIT,
totp_url: typing.Optional[str] = OMIT,
browser_session_id: typing.Optional[str] = OMIT,
+ browser_address: typing.Optional[str] = OMIT,
model: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = OMIT,
extra_http_headers: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
publish_workflow: typing.Optional[bool] = OMIT,
@@ -2041,6 +2042,9 @@ class AsyncSkyvern:
Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.
+ browser_address : typing.Optional[str]
+ The CDP address for the task
+
model : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
Optional model configuration.
@@ -2103,6 +2107,7 @@ class AsyncSkyvern:
"totp_identifier": totp_identifier,
"totp_url": totp_url,
"browser_session_id": browser_session_id,
+ "browser_address": browser_address,
"model": model,
"extra_http_headers": extra_http_headers,
"publish_workflow": publish_workflow,
@@ -2163,6 +2168,7 @@ class AsyncSkyvern:
totp_url: typing.Optional[str] = OMIT,
totp_identifier: typing.Optional[str] = OMIT,
browser_session_id: typing.Optional[str] = OMIT,
+ browser_address: typing.Optional[str] = OMIT,
max_screenshot_scrolls: typing.Optional[int] = OMIT,
extra_http_headers: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
request_options: typing.Optional[RequestOptions] = None,
@@ -2226,6 +2232,9 @@ class AsyncSkyvern:
browser_session_id : typing.Optional[str]
ID of a Skyvern browser session to reuse, having it continue from the current screen state
+ browser_address : typing.Optional[str]
+ The CDP address for the workflow
+
max_screenshot_scrolls : typing.Optional[int]
The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.
@@ -2275,6 +2284,7 @@ class AsyncSkyvern:
"totp_url": totp_url,
"totp_identifier": totp_identifier,
"browser_session_id": browser_session_id,
+ "browser_address": browser_address,
"max_screenshot_scrolls": max_screenshot_scrolls,
"extra_http_headers": extra_http_headers,
},
@@ -3757,6 +3767,7 @@ class AsyncSkyvern:
totp_identifier: typing.Optional[str] = OMIT,
totp_url: typing.Optional[str] = OMIT,
browser_session_id: typing.Optional[str] = OMIT,
+ browser_address: typing.Optional[str] = OMIT,
extra_http_headers: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
max_screenshot_scrolling_times: typing.Optional[int] = OMIT,
credential_id: typing.Optional[str] = OMIT,
@@ -3795,6 +3806,9 @@ class AsyncSkyvern:
browser_session_id : typing.Optional[str]
ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456`
+ browser_address : typing.Optional[str]
+ The CDP address for the task
+
extra_http_headers : typing.Optional[typing.Dict[str, typing.Optional[str]]]
Additional HTTP headers to include in requests
@@ -3856,6 +3870,7 @@ class AsyncSkyvern:
"totp_identifier": totp_identifier,
"totp_url": totp_url,
"browser_session_id": browser_session_id,
+ "browser_address": browser_address,
"extra_http_headers": extra_http_headers,
"max_screenshot_scrolling_times": max_screenshot_scrolling_times,
"credential_id": credential_id,
diff --git a/skyvern/client/environment.py b/skyvern/client/environment.py
index a20011843..15a2b4214 100644
--- a/skyvern/client/environment.py
+++ b/skyvern/client/environment.py
@@ -6,4 +6,4 @@ import enum
class SkyvernEnvironment(enum.Enum):
PRODUCTION = "https://api.skyvern.com"
STAGING = "https://api-staging.skyvern.com"
- DEVELOPMENT = "http://localhost:8000"
+ LOCAL = "http://localhost:8000"
diff --git a/skyvern/forge/sdk/routes/run_blocks.py b/skyvern/forge/sdk/routes/run_blocks.py
index 7b68b0a4f..652863de6 100644
--- a/skyvern/forge/sdk/routes/run_blocks.py
+++ b/skyvern/forge/sdk/routes/run_blocks.py
@@ -194,6 +194,7 @@ async def login(
totp_identifier=login_request.totp_identifier,
totp_verification_url=login_request.totp_url,
browser_session_id=login_request.browser_session_id,
+ browser_address=login_request.browser_address,
max_screenshot_scrolls=login_request.max_screenshot_scrolling_times,
extra_http_headers=login_request.extra_http_headers,
)
diff --git a/skyvern/library/constants.py b/skyvern/library/constants.py
index 7a0e6ab3e..c4b697081 100644
--- a/skyvern/library/constants.py
+++ b/skyvern/library/constants.py
@@ -1,2 +1,3 @@
DEFAULT_AGENT_TIMEOUT = 1800 # 30 minutes
DEFAULT_AGENT_HEARTBEAT_INTERVAL = 10 # 10 seconds
+DEFAULT_CDP_PORT = 9222
diff --git a/skyvern/library/skyvern_browser.py b/skyvern/library/skyvern_browser.py
new file mode 100644
index 000000000..8c763b5c1
--- /dev/null
+++ b/skyvern/library/skyvern_browser.py
@@ -0,0 +1,77 @@
+from playwright.async_api import BrowserContext, Page
+
+from skyvern.client import AsyncSkyvern
+from skyvern.library.skyvern_browser_page import SkyvernBrowserPage, SkyvernPageRun
+
+
+class SkyvernBrowser:
+ """A browser context wrapper that creates Skyvern-enabled pages.
+
+ This class wraps a Playwright BrowserContext and provides methods to create
+ SkyvernBrowserPage instances that combine traditional browser automation with
+ AI-powered task execution capabilities. It manages browser session state and
+ enables persistent browser sessions across multiple pages.
+
+ Example:
+ ```python
+ sdk = SkyvernSdk()
+ browser = await sdk.launch_local_browser()
+
+ # Get or create the working page
+ page = await browser.get_working_page()
+
+ # Create a new page
+ new_page = await browser.new_page()
+ ```
+
+ Attributes:
+ _browser_context: The underlying Playwright BrowserContext.
+ _browser_session_id: Optional session ID for persistent browser sessions.
+ _browser_address: Optional address for remote browser connections.
+ _client: The AsyncSkyvern client for API communication.
+ """
+
+ def __init__(
+ self,
+ browser_context: BrowserContext,
+ client: AsyncSkyvern,
+ *,
+ browser_session_id: str | None = None,
+ browser_address: str | None = None,
+ ):
+ self._browser_context = browser_context
+ self._browser_session_id = browser_session_id
+ self._browser_address = browser_address
+ self._client = client
+
+ async def get_working_page(self) -> SkyvernBrowserPage:
+ """Get the most recent page or create a new one if none exists.
+
+ This method returns the last page in the browser context, or creates a new page
+ if the context has no pages. This is useful for continuing work on an existing
+ page without creating unnecessary new tabs.
+
+ Returns:
+ SkyvernBrowserPage: The most recent page wrapped with Skyvern capabilities.
+ """
+ if self._browser_context.pages:
+ page = self._browser_context.pages[-1]
+ else:
+ page = await self._browser_context.new_page()
+ return await self._create_skyvern_page(page)
+
+ async def new_page(self) -> SkyvernBrowserPage:
+ """Create a new page (tab) in the browser context.
+
+ This method always creates a new page, similar to opening a new tab in a browser.
+ The new page will have both Playwright's standard API and Skyvern's AI capabilities.
+
+ Returns:
+ SkyvernBrowserPage: A new page wrapped with Skyvern capabilities.
+ """
+ page = await self._browser_context.new_page()
+ return await self._create_skyvern_page(page)
+
+ async def _create_skyvern_page(self, page: Page) -> SkyvernBrowserPage:
+ page_ai = SkyvernPageRun(page, self._browser_session_id, self._browser_address, self._client)
+ return SkyvernBrowserPage(page, page_ai)
diff --git a/skyvern/library/skyvern_browser_page.py b/skyvern/library/skyvern_browser_page.py
new file mode 100644
index 000000000..8179e942f
--- /dev/null
+++ b/skyvern/library/skyvern_browser_page.py
@@ -0,0 +1,296 @@
+import asyncio
+from typing import Any
+
+from playwright.async_api import Page
+
+from skyvern.client import AsyncSkyvern, GetRunResponse
+from skyvern.client.types.workflow_run_response import WorkflowRunResponse
+from skyvern.library.constants import DEFAULT_AGENT_HEARTBEAT_INTERVAL, DEFAULT_AGENT_TIMEOUT
+from skyvern.schemas.run_blocks import CredentialType
+from skyvern.schemas.runs import RunEngine, RunStatus, TaskRunResponse
+
+
+class SkyvernPageRun:
+ """Provides methods to run Skyvern tasks and workflows in the context of a browser page.
+
+ This class enables executing AI-powered browser automation tasks while sharing the
+ context of an existing browser page. It supports running custom tasks, login workflows,
+ and pre-defined workflows with automatic waiting for completion.
+ """
+
+ def __init__(
+ self, page: Page, browser_session_id: str | None, browser_address: str | None, client: AsyncSkyvern
+ ) -> None:
+ self._page = page
+ self._browser_session_id = browser_session_id
+ self._browser_address = browser_address
+ self._client = client
+
+ async def run_task(
+ self,
+ prompt: str,
+ engine: RunEngine = RunEngine.skyvern_v2,
+ model: dict[str, Any] | None = None,
+ url: str | None = None,
+ webhook_url: str | None = None,
+ totp_identifier: str | None = None,
+ totp_url: str | None = None,
+ title: str | None = None,
+ error_code_mapping: dict[str, str] | None = None,
+ data_extraction_schema: dict[str, Any] | str | None = None,
+ max_steps: int | None = None,
+ timeout: float = DEFAULT_AGENT_TIMEOUT,
+ user_agent: str | None = None,
+ ) -> TaskRunResponse:
+ """Run a task in the context of this page and wait for it to finish.
+
+ Args:
+ prompt: Natural language description of the task to perform.
+ engine: The execution engine to use. Defaults to skyvern_v2.
+ model: LLM model configuration options.
+ url: URL to navigate to. If not provided, uses the current page URL.
+ webhook_url: URL to receive webhook notifications about task progress.
+ totp_identifier: Identifier for TOTP (Time-based One-Time Password) authentication.
+ totp_url: URL to fetch TOTP codes from.
+ title: Human-readable title for this task run.
+ error_code_mapping: Mapping of error codes to custom error messages.
+ data_extraction_schema: Schema defining what data to extract from the page.
+ max_steps: Maximum number of steps the agent can take.
+ timeout: Maximum time in seconds to wait for task completion.
+ user_agent: Custom user agent string to use.
+
+ Returns:
+ TaskRunResponse containing the task execution results.
+ """
+
+ task_run = await self._client.run_task(
+ prompt=prompt,
+ engine=engine,
+ model=model,
+ url=url or self._get_page_url(),
+ webhook_url=webhook_url,
+ totp_identifier=totp_identifier,
+ totp_url=totp_url,
+ title=title,
+ error_code_mapping=error_code_mapping,
+ data_extraction_schema=data_extraction_schema,
+ max_steps=max_steps,
+ browser_session_id=self._browser_session_id,
+ browser_address=self._browser_address,
+ user_agent=user_agent,
+ )
+
+ task_run = await self._wait_for_run_completion(task_run.run_id, timeout)
+ return TaskRunResponse.model_validate(task_run.model_dump())
+
+ async def login(
+ self,
+ credential_type: CredentialType,
+ *,
+ url: str | None = None,
+ credential_id: str | None = None,
+ bitwarden_collection_id: str | None = None,
+ bitwarden_item_id: str | None = None,
+ onepassword_vault_id: str | None = None,
+ onepassword_item_id: str | None = None,
+ prompt: str | None = None,
+ webhook_url: str | None = None,
+ totp_identifier: str | None = None,
+ totp_url: str | None = None,
+ extra_http_headers: dict[str, str] | None = None,
+ timeout: float = DEFAULT_AGENT_TIMEOUT,
+ ) -> WorkflowRunResponse:
+ """Run a login task in the context of this page and wait for it to finish.
+
+ Args:
+ credential_type: Type of credential store to use (e.g., bitwarden, onepassword).
+ url: URL to navigate to for login. If not provided, uses the current page URL.
+ credential_id: ID of the credential to use.
+ bitwarden_collection_id: Bitwarden collection ID containing the credentials.
+ bitwarden_item_id: Bitwarden item ID for the credentials.
+ onepassword_vault_id: 1Password vault ID containing the credentials.
+ onepassword_item_id: 1Password item ID for the credentials.
+ prompt: Additional instructions for the login process.
+ webhook_url: URL to receive webhook notifications about login progress.
+ totp_identifier: Identifier for TOTP authentication.
+ totp_url: URL to fetch TOTP codes from.
+ extra_http_headers: Additional HTTP headers to include in requests.
+ timeout: Maximum time in seconds to wait for login completion.
+
+ Returns:
+ WorkflowRunResponse containing the login workflow execution results.
+ """
+
+ workflow_run = await self._client.login(
+ credential_type=credential_type,
+ url=url or self._get_page_url(),
+ credential_id=credential_id,
+ bitwarden_collection_id=bitwarden_collection_id,
+ bitwarden_item_id=bitwarden_item_id,
+ onepassword_vault_id=onepassword_vault_id,
+ onepassword_item_id=onepassword_item_id,
+ prompt=prompt,
+ webhook_url=webhook_url,
+ totp_identifier=totp_identifier,
+ totp_url=totp_url,
+ browser_session_id=self._browser_session_id,
+ browser_address=self._browser_address,
+ extra_http_headers=extra_http_headers,
+ )
+
+ workflow_run = await self._wait_for_run_completion(workflow_run.run_id, timeout)
+ return WorkflowRunResponse.model_validate(workflow_run.model_dump())
+
+ async def run_workflow(
+ self,
+ workflow_id: str,
+ parameters: dict[str, Any] | None = None,
+ template: bool | None = None,
+ title: str | None = None,
+ webhook_url: str | None = None,
+ totp_url: str | None = None,
+ totp_identifier: str | None = None,
+ timeout: float = DEFAULT_AGENT_TIMEOUT,
+ ) -> WorkflowRunResponse:
+ """Run a workflow in the context of this page and wait for it to finish.
+
+ Args:
+ workflow_id: ID of the workflow to execute.
+ parameters: Dictionary of parameters to pass to the workflow.
+ template: Whether this is a workflow template.
+ title: Human-readable title for this workflow run.
+ webhook_url: URL to receive webhook notifications about workflow progress.
+ totp_url: URL to fetch TOTP codes from.
+ totp_identifier: Identifier for TOTP authentication.
+ timeout: Maximum time in seconds to wait for workflow completion.
+
+ Returns:
+ WorkflowRunResponse containing the workflow execution results.
+ """
+ workflow_run = await self._client.run_workflow(
+ workflow_id=workflow_id,
+ parameters=parameters,
+ template=template,
+ title=title,
+ webhook_url=webhook_url,
+ totp_url=totp_url,
+ totp_identifier=totp_identifier,
+ browser_session_id=self._browser_session_id,
+ browser_address=self._browser_address,
+ )
+
+ workflow_run = await self._wait_for_run_completion(workflow_run.run_id, timeout)
+ return WorkflowRunResponse.model_validate(workflow_run.model_dump())
+
+ async def _wait_for_run_completion(self, run_id: str, timeout: float) -> GetRunResponse:
+ async with asyncio.timeout(timeout):
+ while True:
+ task_run = await self._client.get_run(run_id)
+ if RunStatus(task_run.status).is_final():
+ break
+ await asyncio.sleep(DEFAULT_AGENT_HEARTBEAT_INTERVAL)
+ return task_run
+
+ def _get_page_url(self) -> str | None:
+ url = self._page.url
+ if url == "about:blank":
+ return None
+ return url
+
+
+class SkyvernBrowserPage:
+ """A browser page wrapper that combines Playwright's page API with Skyvern's AI capabilities.
+
+ This class provides a unified interface for both traditional browser automation (via Playwright)
+ and AI-powered task execution (via Skyvern). It exposes standard page methods like click, fill,
+ goto, etc., while also providing access to Skyvern's task and workflow execution through the
+ `run` attribute.
+
+ Example:
+ ```python
+ # Use standard Playwright methods
+ await page.goto("https://example.com")
+ await page.fill("#username", "[email protected]")
+ await page.click("#login-button")
+
+ # Or use Skyvern's AI capabilities
+ await page.run.run_task("Fill out the contact form and submit it")
+ ```
+
+ Attributes:
+ run: SkyvernPageRun instance for executing AI-powered tasks and workflows.
+ """
+
+ def __init__(self, page: Page, run: SkyvernPageRun):
+ self.run = run
+ self._playwright_page = page
+
+ async def click(self, selector: str, **kwargs: Any) -> None:
+ """Click an element matching the selector.
+
+ Args:
+ selector: A selector to search for an element to click.
+ **kwargs: Additional options like timeout, force, position, etc.
+ """
+ await self._playwright_page.click(selector, **kwargs)
+
+ async def fill(self, selector: str, value: str, **kwargs: Any) -> None:
+ """Fill an input field with the given value.
+
+ Args:
+ selector: A selector to search for an element to fill.
+ value: Value to fill for the input field.
+ **kwargs: Additional options like timeout, force, no_wait_after, etc.
+ """
+ await self._playwright_page.fill(selector, value, **kwargs)
+
+ async def goto(self, url: str, **kwargs: Any) -> None:
+ """Navigate to the given URL.
+
+ Args:
+ url: URL to navigate page to.
+ **kwargs: Additional options like timeout, wait_until, referer, etc.
+ """
+ await self._playwright_page.goto(url, **kwargs)
+
+ async def type(self, selector: str, text: str, **kwargs: Any) -> None:
+ """Type text into an element character by character.
+
+ Args:
+ selector: A selector to search for an element to type into.
+ text: Text to type into the element.
+ **kwargs: Additional options like delay, timeout, no_wait_after, etc.
+ """
+ await self._playwright_page.type(selector, text, **kwargs)
+
+ async def select_option(self, selector: str, value: Any = None, **kwargs: Any) -> list[str]:
+ """Select option(s) in a <select> element.
+
+ Args:
+ selector: A selector to search for a select element.
+ value: Option value(s) to select. Can be a string, list of strings, or dict with value/label/index.
+ **kwargs: Additional options like timeout, force, no_wait_after, etc.
+
+ Returns:
+ List of option values that have been successfully selected.
+ """
+ return await self._playwright_page.select_option(selector, value, **kwargs)
+
+ async def reload(self, **kwargs: Any) -> None:
+ """Reload the current page.
+
+ Args:
+ **kwargs: Additional options like timeout, wait_until, etc.
+ """
+ await self._playwright_page.reload(**kwargs)
+
+ async def screenshot(self, **kwargs: Any) -> bytes:
+ """Take a screenshot of the page.
+
+ Args:
+ **kwargs: Additional options like path, full_page, clip, type, quality, etc.
+
+ Returns:
+ bytes: The screenshot as bytes (unless path is specified, then saves to file).
+ """
+ return await self._playwright_page.screenshot(**kwargs)
diff --git a/skyvern/library/skyvern_sdk.py b/skyvern/library/skyvern_sdk.py
new file mode 100644
index 000000000..6eda680fd
--- /dev/null
+++ b/skyvern/library/skyvern_sdk.py
@@ -0,0 +1,222 @@
+import os
+
+import httpx
+from dotenv import load_dotenv
+from playwright.async_api import Playwright, async_playwright
+
+from skyvern.client import AsyncSkyvern, BrowserSessionResponse, SkyvernEnvironment
+from skyvern.library.constants import DEFAULT_CDP_PORT
+from skyvern.library.skyvern_browser import SkyvernBrowser
+
+
+class SkyvernSdk:
+ """Main entry point for the Skyvern SDK.
+
+ This class provides methods to launch and connect to browsers (both local and cloud-hosted),
+ and access the Skyvern API client for task and workflow management. It combines browser
+ automation capabilities with AI-powered task execution.
+
+ Example:
+ ```python
+ # Initialize with environment and API key
+ skyvern = SkyvernSdk(environment=SkyvernEnvironment.PRODUCTION, api_key="your-api-key")
+
+ # Launch a local browser
+ browser = await skyvern.launch_local_browser(headless=False)
+ page = await browser.get_working_page()
+
+ # Or use a cloud browser
+ browser = await skyvern.use_cloud_browser()
+ page = await browser.get_working_page()
+
+ # Execute AI-powered tasks
+ await page.run.run_task("Fill out the form and submit it")
+ ```
+
+ You can also mix AI-powered tasks with direct browser control in the same session:
+ ```python
+
+ # Create credentials via API
+ credential = await skyvern.api.create_credential(
+ name="my_user",
+ credential_type="password",
+ credential=NonEmptyPasswordCredential(username="[email protected]",password="secure_password"),
+ )
+
+ # Get a browser page
+ browser = await skyvern.launch_cloud_browser()
+ page = await browser.get_working_page()
+
+ # Navigate manually
+ await page.goto("https://example.com")
+
+ # Use AI to handle login
+ await page.run.login(
+ credential_type=CredentialType.skyvern,
+ credential_id=credential.credential_id,
+ )
+
+ # Continue with manual browser control
+ await page.click("#invoices-button")
+ await page.fill("#search", "my invoice")
+ await page.screenshot(path="screenshot.png", full_page=True)
+ ```
+ """
+
+ def __init__(
+ self,
+ *,
+ environment: SkyvernEnvironment = SkyvernEnvironment.LOCAL,
+ base_url: str | None = None,
+ api_key: str | None = None,
+ timeout: float | None = None,
+ follow_redirects: bool | None = True,
+ httpx_client: httpx.AsyncClient | None = None,
+ ):
+ """Initialize the Skyvern SDK client.
+
+ Args:
+ environment: The Skyvern environment to connect to (LOCAL or PRODUCTION).
+ base_url: Custom base URL for the Skyvern API. Overrides environment setting.
+ api_key: Skyvern API key. If not provided, loads from SKYVERN_API_KEY environment variable.
+ timeout: HTTP request timeout in seconds.
+ follow_redirects: Whether to follow HTTP redirects. Defaults to True.
+ httpx_client: Custom httpx.AsyncClient instance for HTTP requests.
+
+ Raises:
+ Exception: If no API key is provided and no .env file exists.
+ """
+
+ if api_key is None:
+ if os.path.exists(".env"):
+ load_dotenv(".env")
+
+ env_key = os.getenv("SKYVERN_API_KEY")
+ if not env_key:
+ raise ValueError(
+ "SKYVERN_API_KEY is not set. Provide api_key or set SKYVERN_API_KEY in environment/.env."
+ )
+ self._api_key = env_key
+ else:
+ self._api_key = api_key
+
+ self._api = AsyncSkyvern(
+ environment=environment,
+ base_url=base_url,
+ api_key=self._api_key,
+ x_api_key=self._api_key,
+ timeout=timeout,
+ follow_redirects=follow_redirects,
+ httpx_client=httpx_client,
+ )
+
+ self._playwright: Playwright | None = None
+
+ @property
+ def api(self) -> AsyncSkyvern:
+ """Get the AsyncSkyvern API client for direct API access."""
+ return self._api
+
+ async def launch_local_browser(self, *, headless: bool = False, port: int = DEFAULT_CDP_PORT) -> SkyvernBrowser:
+ """Launch a new local Chromium browser with Chrome DevTools Protocol (CDP) enabled.
+
+ This method launches a browser on your local machine with remote debugging enabled,
+ allowing Skyvern to control it via CDP. Useful for development and debugging.
+
+ Args:
+ headless: Whether to run the browser in headless mode. Defaults to False.
+ port: The port number for the CDP endpoint. Defaults to DEFAULT_CDP_PORT.
+
+ Returns:
+ SkyvernBrowser: A browser instance with Skyvern capabilities.
+ """
+ playwright = await self._get_playwright()
+ browser = await playwright.chromium.launch(
+ headless=headless,
+ args=[f"--remote-debugging-port={port}"],
+ )
+ browser_address = f"http://localhost:{port}"
+ browser_context = browser.contexts[0] if browser.contexts else await browser.new_context()
+ return SkyvernBrowser(browser_context, self._api, browser_address=browser_address)
+
+ async def connect_to_browser_over_cdp(self, cdp_url: str) -> SkyvernBrowser:
+ """Connect to an existing browser instance via Chrome DevTools Protocol (CDP).
+
+ Use this to connect to a browser that's already running with CDP enabled,
+ whether local or remote.
+
+ Args:
+ cdp_url: The CDP WebSocket URL (e.g., "http://localhost:9222").
+
+ Returns:
+ SkyvernBrowser: A browser instance connected to the existing browser.
+ """
+ playwright = await self._get_playwright()
+ browser = await playwright.chromium.connect_over_cdp(cdp_url)
+ browser_context = browser.contexts[0] if browser.contexts else await browser.new_context()
+ return SkyvernBrowser(browser_context, self._api, browser_address=cdp_url)
+
+ async def connect_to_cloud_browser_session(self, browser_session_id: str) -> SkyvernBrowser:
+ """Connect to an existing cloud-hosted browser session by ID.
+
+ Args:
+ browser_session_id: The ID of the cloud browser session to connect to.
+
+ Returns:
+ SkyvernBrowser: A browser instance connected to the cloud session.
+ """
+ browser_session = await self._api.get_browser_session(browser_session_id)
+ return await self._connect_to_cloud_browser_session(browser_session)
+
+ async def launch_cloud_browser(self) -> SkyvernBrowser:
+ """Launch a new cloud-hosted browser session.
+
+ This creates a new browser session in Skyvern's cloud infrastructure and connects to it.
+
+ Returns:
+ SkyvernBrowser: A browser instance connected to the new cloud session.
+ """
+ browser_session = await self._api.create_browser_session()
+ return await self._connect_to_cloud_browser_session(browser_session)
+
+ async def use_cloud_browser(self) -> SkyvernBrowser:
+ """Get or create a cloud browser session.
+
+ This method attempts to reuse the most recent available cloud browser session.
+ If no session exists, it creates a new one. This is useful for cost efficiency
+ and session persistence.
+
+ Returns:
+ SkyvernBrowser: A browser instance connected to an existing or new cloud session.
+ """
+ browser_sessions = await self._api.get_browser_sessions()
+ browser_session = max(
+ (s for s in browser_sessions if s.runnable_id is None), key=lambda s: s.started_at, default=None
+ )
+ if browser_session is None:
+ browser_session = await self._api.create_browser_session()
+ return await self._connect_to_cloud_browser_session(browser_session)
+
+ async def _connect_to_cloud_browser_session(self, browser_session: BrowserSessionResponse) -> SkyvernBrowser:
+ if browser_session.browser_address is None:
+ raise Exception(f"Browser address is missing for session {browser_session.browser_session_id}")
+
+ playwright = await self._get_playwright()
+ browser = await playwright.chromium.connect_over_cdp(
+ browser_session.browser_address, headers={"x-api-key": self._api_key}
+ )
+ browser_context = browser.contexts[0] if browser.contexts else await browser.new_context()
+ return SkyvernBrowser(browser_context, self._api, browser_session_id=browser_session.browser_session_id)
+
+ async def _get_playwright(self) -> Playwright:
+ if self._playwright is None:
+ self._playwright = await async_playwright().start()
+ return self._playwright
+
+ async def aclose(self) -> None:
+ """Close Playwright and release resources."""
+ if self._playwright is not None:
+ try:
+ await self._playwright.stop()
+ finally:
+ self._playwright = None
diff --git a/skyvern/schemas/run_blocks.py b/skyvern/schemas/run_blocks.py
index 0db9315b1..c17a38e59 100644
--- a/skyvern/schemas/run_blocks.py
+++ b/skyvern/schemas/run_blocks.py
@@ -30,6 +30,11 @@ class LoginRequest(BaseModel):
description="ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456`",
examples=["pbs_123456"],
)
+ browser_address: str | None = Field(
+ default=None,
+ description="The CDP address for the task.",
+ examples=["http://127.0.0.1:9222", "ws://127.0.0.1:9222/devtools/browser/1234567890"],
+ )
extra_http_headers: dict[str, str] | None = Field(
default=None, description="Additional HTTP headers to include in requests"
)
diff --git a/skyvern/webeye/browser_factory.py b/skyvern/webeye/browser_factory.py
index c94d89e85..7cc98d3d1 100644
--- a/skyvern/webeye/browser_factory.py
+++ b/skyvern/webeye/browser_factory.py
@@ -419,6 +419,13 @@ async def _create_headless_chromium(
extra_http_headers: dict[str, str] | None = None,
**kwargs: dict,
) -> tuple[BrowserContext, BrowserArtifacts, BrowserCleanupFunc]:
+ if browser_address := kwargs.get("browser_address"):
+ return await _connect_to_cdp_browser(
+ playwright,
+ remote_browser_url=str(browser_address),
+ extra_http_headers=extra_http_headers,
+ )
+
user_data_dir = make_temp_directory(prefix="skyvern_browser_")
download_dir = initialize_download_dir()
BrowserContextFactory.update_chromium_browser_preferences(
@@ -447,6 +454,13 @@ async def _create_headful_chromium(
extra_http_headers: dict[str, str] | None = None,
**kwargs: dict,
) -> tuple[BrowserContext, BrowserArtifacts, BrowserCleanupFunc]:
+ if browser_address := kwargs.get("browser_address"):
+ return await _connect_to_cdp_browser(
+ playwright,
+ remote_browser_url=str(browser_address),
+ extra_http_headers=extra_http_headers,
+ )
+
user_data_dir = make_temp_directory(prefix="skyvern_browser_")
download_dir = initialize_download_dir()
BrowserContextFactory.update_chromium_browser_preferences(
@@ -503,6 +517,13 @@ async def _create_cdp_connection_browser(
extra_http_headers: dict[str, str] | None = None,
**kwargs: dict,
) -> tuple[BrowserContext, BrowserArtifacts, BrowserCleanupFunc]:
+ if browser_address := kwargs.get("browser_address"):
+ return await _connect_to_cdp_browser(
+ playwright,
+ remote_browser_url=str(browser_address),
+ extra_http_headers=extra_http_headers,
+ )
+
browser_type = settings.BROWSER_TYPE
browser_path = settings.CHROME_EXECUTABLE_PATH
@@ -550,13 +571,20 @@ async def _create_cdp_connection_browser(
else:
LOG.info("Port 9222 is in use, using existing browser")
+ return await _connect_to_cdp_browser(playwright, settings.BROWSER_REMOTE_DEBUGGING_URL, extra_http_headers)
+
+
+async def _connect_to_cdp_browser(
+ playwright: Playwright,
+ remote_browser_url: str,
+ extra_http_headers: dict[str, str] | None = None,
+) -> tuple[BrowserContext, BrowserArtifacts, BrowserCleanupFunc]:
browser_args = BrowserContextFactory.build_browser_args(extra_http_headers=extra_http_headers)
browser_artifacts = BrowserContextFactory.build_browser_artifacts(
har_path=browser_args["record_har_path"],
)
- remote_browser_url = settings.BROWSER_REMOTE_DEBUGGING_URL
LOG.info("Connecting browser CDP connection", remote_browser_url=remote_browser_url)
browser = await playwright.chromium.connect_over_cdp(remote_browser_url)
@@ -676,7 +704,7 @@ class BrowserState:
if not use_existing_page:
await self._close_all_other_pages()
- if url:
+ if url and page.url.rstrip("/") != url.rstrip("/"):
await self.navigate_to_url(page=page, url=url)
async def navigate_to_url(self, page: Page, url: str, retry_times: int = NAVIGATION_MAX_RETRY_TIME) -> None: