doc update - add run tasks page (#2425)

2025-05-24 23:46:31 -07:00
parent 601cd099f7
commit 6f83978937
27 changed files with 1168 additions and 48 deletions
--- a/skyvern/schemas/docs/init.py
+++ b/skyvern/schemas/docs/init.py
--- a/skyvern/schemas/docs/doc_examples.py
+++ b/skyvern/schemas/docs/doc_examples.py
@@ -0,0 +1,28 @@
+TASK_PROMPT_EXAMPLES = [
+    "Find the top 3 posts on Hacker News.",
+    'Go to google finance, extract the "AAPL" stock price for me with the date.',
+]
+
+TASK_URL_EXAMPLES = [
+    "https://www.hackernews.com",
+    "https://www.google.com/finance",
+]
+
+ERROR_CODE_MAPPING_EXAMPLES = [
+    {"login_failed": "The login credentials are incorrect or the account is locked"},
+    {"maintenance_mode": "The website is down for maintenance"},
+]
+
+TOTP_IDENTIFIER_EXAMPLES = [
+    "john.doe@example.com",
+    "4155555555",
+    "user_123",
+]
+
+TOTP_URL_EXAMPLES = [
+    "https://my-totp-service.com/totp",
+]
+
+BROWSER_SESSION_ID_EXAMPLES = [
+    "pbs_123",
+]
--- a/skyvern/schemas/docs/doc_strings.py
+++ b/skyvern/schemas/docs/doc_strings.py
@@ -0,0 +1,63 @@
+TASK_PROMPT_DOC_STRING = """
+The goal or task description for Skyvern to accomplish
+"""
+
+TASK_URL_DOC_STRING = """
+The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL
+"""
+
+TASK_ENGINE_DOC_STRING = """
+The engine that powers the agent task. The default value is `skyvern-2.0`, the latest Skyvern agent that performs pretty well with complex and multi-step tasks. `skyvern-1.0` is good for simple tasks like filling a form, or searching for information on Google. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.
+"""
+
+PROXY_LOCATION_DOC_STRING = """
+Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.
+
+Available geotargeting options:
+- RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
+- RESIDENTIAL_ES: Spain
+- RESIDENTIAL_IE: Ireland
+- RESIDENTIAL_GB: United Kingdom
+- RESIDENTIAL_IN: India
+- RESIDENTIAL_JP: Japan
+- RESIDENTIAL_FR: France
+- RESIDENTIAL_DE: Germany
+- RESIDENTIAL_NZ: New Zealand
+- RESIDENTIAL_ZA: South Africa
+- RESIDENTIAL_AR: Argentina
+- RESIDENTIAL_ISP: ISP proxy
+- US-CA: California
+- US-NY: New York
+- US-TX: Texas
+- US-FL: Florida
+- US-WA: Washington
+- NONE: No proxy
+"""
+
+DATA_EXTRACTION_SCHEMA_DOC_STRING = """
+The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/.
+"""
+
+ERROR_CODE_MAPPING_DOC_STRING = """
+Custom mapping of error codes to error messages if Skyvern encounters an error.
+"""
+
+MAX_STEPS_DOC_STRING = """
+Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.
+"""
+
+WEBHOOK_URL_DOC_STRING = """
+URL to send task status updates to after a run is finished. Refer to https://docs.skyvern.com/running-tasks/webhooks-faq for more details.
+"""
+
+TOTP_IDENTIFIER_DOC_STRING = """
+Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/credentials/totp#option-3-push-code-to-skyvern for more details.
+"""
+
+TOTP_URL_DOC_STRING = """
+URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/credentials/totp#option-2-get-code-from-your-endpoint for more details.
+"""
+
+BROWSER_SESSION_ID_DOC_STRING = """
+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.
+"""
--- a/skyvern/schemas/runs.py
+++ b/skyvern/schemas/runs.py
@@ -8,6 +8,27 @@ from zoneinfo import ZoneInfo
 from pydantic import BaseModel, Field, field_validator

 from skyvern.forge.sdk.schemas.files import FileInfo
+from skyvern.schemas.docs.doc_examples import (
+    BROWSER_SESSION_ID_EXAMPLES,
+    ERROR_CODE_MAPPING_EXAMPLES,
+    TASK_PROMPT_EXAMPLES,
+    TASK_URL_EXAMPLES,
+    TOTP_IDENTIFIER_EXAMPLES,
+    TOTP_URL_EXAMPLES,
+)
+from skyvern.schemas.docs.doc_strings import (
+    BROWSER_SESSION_ID_DOC_STRING,
+    DATA_EXTRACTION_SCHEMA_DOC_STRING,
+    ERROR_CODE_MAPPING_DOC_STRING,
+    MAX_STEPS_DOC_STRING,
+    PROXY_LOCATION_DOC_STRING,
+    TASK_ENGINE_DOC_STRING,
+    TASK_PROMPT_DOC_STRING,
+    TASK_URL_DOC_STRING,
+    TOTP_IDENTIFIER_DOC_STRING,
+    TOTP_URL_DOC_STRING,
+    WEBHOOK_URL_DOC_STRING,
+)
 from skyvern.utils.url_validators import validate_url


@@ -188,42 +209,59 @@ class RunStatus(StrEnum):


 class TaskRunRequest(BaseModel):
-    prompt: str = Field(description="The goal or task description for Skyvern to accomplish")
+    prompt: str = Field(
+        description=TASK_PROMPT_DOC_STRING,
+        examples=TASK_PROMPT_EXAMPLES,
+    )
    url: str | None = Field(
        default=None,
-        description="The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL",
+        description=TASK_URL_DOC_STRING,
+        examples=TASK_URL_EXAMPLES,
    )
    engine: RunEngine = Field(
        default=RunEngine.skyvern_v2,
-        description="The Skyvern engine version to use for this task. The default value is skyvern-2.0.",
+        description=TASK_ENGINE_DOC_STRING,
+    )
+    title: str | None = Field(
+        default=None, description="The title for the task", examples=["The title of my first skyvern task"]
    )
-    title: str | None = Field(default=None, description="The title for the task")
    proxy_location: ProxyLocation | None = Field(
-        default=ProxyLocation.RESIDENTIAL, description="Geographic Proxy location to route the browser traffic through"
+        default=ProxyLocation.RESIDENTIAL,
+        description=PROXY_LOCATION_DOC_STRING,
    )
    data_extraction_schema: dict | list | str | None = Field(
-        default=None, description="Schema defining what data should be extracted from the webpage"
+        default=None,
+        description=DATA_EXTRACTION_SCHEMA_DOC_STRING,
    )
    error_code_mapping: dict[str, str] | None = Field(
-        default=None, description="Custom mapping of error codes to error messages if Skyvern encounters an error"
+        default=None,
+        description=ERROR_CODE_MAPPING_DOC_STRING,
+        examples=ERROR_CODE_MAPPING_EXAMPLES,
    )
    max_steps: int | None = Field(
-        default=None, description="Maximum number of steps the task can take before timing out"
+        default=None,
+        description=MAX_STEPS_DOC_STRING,
+        examples=[10, 25],
    )
    webhook_url: str | None = Field(
-        default=None, description="URL to send task status updates to after a run is finished"
+        default=None,
+        description=WEBHOOK_URL_DOC_STRING,
+        examples=["https://my-site.com/webhook"],
    )
    totp_identifier: str | None = Field(
        default=None,
-        description="Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern",
+        description=TOTP_IDENTIFIER_DOC_STRING,
+        examples=TOTP_IDENTIFIER_EXAMPLES,
    )
    totp_url: str | None = Field(
        default=None,
-        description="URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes",
+        description=TOTP_URL_DOC_STRING,
+        examples=TOTP_URL_EXAMPLES,
    )
    browser_session_id: str | None = Field(
        default=None,
-        description="ID of an existing browser session to reuse, having it continue from the current screen state",
+        description=BROWSER_SESSION_ID_DOC_STRING,
+        examples=BROWSER_SESSION_ID_EXAMPLES,
    )
    publish_workflow: bool = Field(
        default=False,
@@ -258,7 +296,8 @@ class WorkflowRunRequest(BaseModel):
    parameters: dict[str, Any] = Field(default={}, description="Parameters to pass to the workflow")
    title: str | None = Field(default=None, description="The title for this workflow run")
    proxy_location: ProxyLocation | None = Field(
-        default=ProxyLocation.RESIDENTIAL, description="Location of proxy to use for this workflow run"
+        default=ProxyLocation.RESIDENTIAL,
+        description=PROXY_LOCATION_DOC_STRING,
    )
    webhook_url: str | None = Field(
        default=None,
@@ -266,11 +305,13 @@ class WorkflowRunRequest(BaseModel):
    )
    totp_url: str | None = Field(
        default=None,
-        description="URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/running-tasks/advanced-features#get-code-from-your-endpoint",
+        description=TOTP_URL_DOC_STRING,
+        examples=TOTP_URL_EXAMPLES,
    )
    totp_identifier: str | None = Field(
        default=None,
-        description="Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/running-tasks/advanced-features#time-based-one-time-password-totp",
+        description=TOTP_IDENTIFIER_DOC_STRING,
+        examples=TOTP_IDENTIFIER_EXAMPLES,
    )
    browser_session_id: str | None = Field(
        default=None,