Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Block discovery MCP tools + improved MCP instructions (#SKY-7804) (#4683)
Marc Kelechava0c879492e42a
diff --git a/skyvern/cli/mcp_tools/__init__.py b/skyvern/cli/mcp_tools/__init__.pyindex b4b0cefb8..10f8c396f 100644--- a/skyvern/cli/mcp_tools/__init__.py+++ b/skyvern/cli/mcp_tools/__init__.py@@ -7,6 +7,10 @@ AI assistants like Claude.from fastmcp import FastMCP+from .blocks import (+ skyvern_block_schema,+ skyvern_block_validate,+)from .browser import (skyvern_act,skyvern_click,@@ -44,21 +48,52 @@ mcp = FastMCP("Skyvern",instructions="""Use Skyvern tools whenever the task involves visiting, browsing, or interacting with ANY website or web application.-## When to Use These Tools-Reach for Skyvern tools when the user asks you to:-- Visit, browse, or interact with ANY website or web application-- Extract data from web pages (prices, listings, articles, tables, search results, etc.)-- Fill out forms, log in, sign up, or complete web-based workflows-- Check the current state of a web page or verify something on a site-- Do anything you would otherwise attempt with requests, beautifulsoup, selenium, or playwright-- Access website data where you are unsure whether an API endpoint exists-- Create, run, monitor, or manage web automations (Skyvern workflows)-- Set up reusable, parameterized automations that run on Skyvern's cloud-- Check the status of running automations or retrieve their results--DO NOT try to scrape websites by guessing API endpoints or writing HTTP requests.-Instead, use skyvern_navigate + skyvern_extract to get real data from actual pages.-These tools give you a real browser — use them instead of writing scraping code.+## Tool Selection (read this first)++**Which tool do I use?**++| Scenario | Use | Why |+|----------|-----|-----|+| Visit a website | skyvern_navigate | First step — opens the page |+| See what's on the page | skyvern_screenshot | Visual understanding before acting |+| Get data from a page | skyvern_extract | AI-powered structured extraction |+| Do something on a page (click, fill, scroll) | skyvern_act | Natural language actions |+| Click/type/select a specific element | skyvern_click / skyvern_type / skyvern_select_option | Precision targeting by selector or AI intent |+| Check if something is true | skyvern_validate | AI assertion ("is the user logged in?") |+| Run a quick one-off task | skyvern_run_task | Autonomous agent, one-time, nothing saved |+| Build an automation (any multi-step task) | skyvern_workflow_create | Reusable, versioned, per-step observability |+| Run an existing automation | skyvern_workflow_run | Execute saved workflow with parameters |+| Run JavaScript | skyvern_evaluate | Read DOM state, get values |++**Rule of thumb**: For anything worth keeping or repeating, create a workflow. Use skyvern_run_task only for quick throwaway tests.++**Common mistake**: Don't create a single-block workflow with a long prompt listing all steps.+Split into separate blocks — one per logical step. Each block should have a prompt of 2-3 sentences.++## Critical Rules+1. ALWAYS create a session (skyvern_session_create) before using browser tools.+2. NEVER scrape by guessing API endpoints or writing HTTP requests — use skyvern_navigate + skyvern_extract.+3. NEVER create single-block workflows with long prompts — split into multiple blocks.+4. NEVER import from skyvern.cli.mcp_tools — use `from skyvern import Skyvern` for SDK scripts.+5. After page-changing actions (skyvern_click, skyvern_act), use skyvern_screenshot to verify the result.++## Cross-Tool Dependencies+- Workflow tools (list, create, run, status) do NOT need a browser session+- skyvern_extract and skyvern_validate read the CURRENT page — navigate first+- skyvern_run_task is a one-off throwaway agent run — for reusable automations, use skyvern_workflow_create instead++## Tool Modes (precision tools)+Precision tools (skyvern_click, skyvern_type, skyvern_select_option, skyvern_scroll, skyvern_press_key, skyvern_wait)+support three modes. When unsure, use `intent`. For multiple actions in sequence, prefer skyvern_act.++1. **Intent mode** — AI-powered element finding:+ `skyvern_click(intent="the blue Submit button")`++2. **Hybrid mode** — tries selector first, AI fallback:+ `skyvern_click(selector="#submit-btn", intent="the Submit button")`++3. **Selector mode** — deterministic CSS/XPath targeting:+ `skyvern_click(selector="#submit-btn")`## Examples| User says | Use |@@ -68,13 +103,13 @@ These tools give you a real browser — use them instead of writing scraping cod| "Get all product prices" | skyvern_extract || "Click the login button" | skyvern_act or skyvern_click || "Fill out this form" | skyvern_act |-| "Log in and buy the first item" | skyvern_run_task |+| "Log in and download the report" | skyvern_run_task (one-off) or skyvern_workflow_create (keep it) || "Is checkout complete?" | skyvern_validate |-| "List my workflows" | skyvern_workflow_list |+| "Fill out this 6-page application form" | skyvern_workflow_create (one block per page) |+| "Set up a reusable automation" | Explore with browser tools, then skyvern_workflow_create || "Create a workflow that monitors prices" | skyvern_workflow_create || "Run the login workflow" | skyvern_workflow_run || "Is my workflow done?" | skyvern_workflow_status |-| "Set up a reusable automation for this" | Explore with browser tools, then skyvern_workflow_create || "Write a script to do this" | Skyvern SDK (see below) |## Getting Started@@ -84,43 +119,63 @@ These tools give you a real browser — use them instead of writing scraping cod2. Navigate and interact with browser tools3. Close with skyvern_session_close when done-**Managing automations** (running, listing, or monitoring workflows):-No browser session needed — use workflow tools directly:-skyvern_workflow_list, skyvern_workflow_run, skyvern_workflow_status, etc.+**Automating a multi-page form** (the most common use case):+1. Create a workflow with skyvern_workflow_create — one task block per form page+2. Each block gets a short, focused prompt (2-3 sentences max)+3. All blocks in a run share the same browser automatically+4. Run with skyvern_workflow_run**Building a reusable automation** (explore a site, then save as a workflow):1. **Explore** — Create a browser session, navigate the site, use skyvern_extract and skyvern_screenshot to understand the page structure2. **Create** — Build a workflow definition and save it with skyvern_workflow_create3. **Test** — Run the workflow with skyvern_workflow_run and check results with skyvern_workflow_status-## Workflows vs Scripts--When the user wants something **persistent, versioned, and managed in Skyvern's dashboard** — create a workflow.-Trigger words: "automation", "workflow", "reusable", "schedule", "monitor", "set up"-→ Use skyvern_workflow_create with a JSON definition (see example below)--When the user wants **custom Python code** to run in their own environment — write an SDK script.-Trigger words: "script", "code", "function", "program"-→ Use `from skyvern import Skyvern` (see Writing Scripts section)--### Workflow definition example (JSON, for skyvern_workflow_create):- {- "title": "Price Monitor",- "workflow_definition": {- "parameters": [- {"parameter_type": "workflow", "key": "url", "workflow_parameter_type": "string"}- ],- "blocks": [- {"block_type": "task", "label": "extract_prices", "url": "{{url}}", "engine": "skyvern-2.0",- "navigation_goal": "Extract all product names and prices from the page",- "data_extraction_goal": "Get product names and prices as a list",- "data_schema": {"type": "object", "properties": {"products": {"type": "array",- "items": {"type": "object", "properties": {"name": {"type": "string"}, "price": {"type": "string"}}}}}}}- ]- }- }-Use `{{parameter_key}}` to reference workflow parameters in block fields.-To inspect a real workflow for reference, use skyvern_workflow_get on an existing workflow.+**Managing automations** (running, listing, or monitoring workflows):+No browser session needed — use workflow tools directly:+skyvern_workflow_list, skyvern_workflow_run, skyvern_workflow_status, etc.++## Building Workflows++Before creating a workflow, call skyvern_block_schema() to discover available block types and their JSON schemas.+Validate blocks with skyvern_block_validate() before submitting.++ALWAYS split workflows into multiple blocks — one task block per logical step:++GOOD (4 blocks, each with clear single responsibility):+ Block 1: "Select Sole Proprietor and click Continue"+ Block 2: "Fill in the business name and click Continue"+ Block 3: "Enter owner info and SSN, click Continue"+ Block 4: "Review and submit. Extract the confirmation number."++BAD (1 giant block trying to do everything):+ Block 1: "Go to the IRS site, select sole proprietor, fill in name, enter SSN, review, submit, and extract the EIN"++Use {{parameter_key}} to reference workflow input parameters in any block field.++## Data Flow Between Blocks+- Use `{{parameter_key}}` to reference workflow input parameters in any block field+- Blocks in the same workflow run share the same browser session automatically+- To inspect a real workflow for reference, use skyvern_workflow_get on an existing workflow++## Block Types Reference+Common block types for workflow definitions:+- **task** — AI agent interacts with a page (the most common block type)+- **for_loop** — iterate over a list of items+- **conditional** — branch based on conditions+- **code** — run Python code for data transformation+- **text_prompt** — LLM text generation (no browser)+- **extraction** — extract data from current page+- **action** — single AI action on current page+- **navigation** — navigate to a URL+- **wait** — pause for a condition or time+- **login** — log into a site using stored credentials+- **validation** — assert a condition on the page+- **http_request** — call an external API+- **send_email** — send a notification email+- **file_download** / **file_upload** — download or upload files+- **goto_url** — navigate to a specific URL within a workflow++For full schemas and descriptions, call skyvern_block_schema().## Writing Scripts and CodeWhen asked to write an automation script, use the Skyvern Python SDK with the **hybrid xpath+prompt@@ -150,66 +205,9 @@ The `resolved_selector` field in responses gives you the xpath the AI resolved tIMPORTANT: NEVER import from skyvern.cli.mcp_tools — those are internal server modules.The public SDK is: from skyvern import Skyvern-## Primary Tools (use these first)-These are the tools you should reach for by default:--- **skyvern_act** — Execute actions from natural language: "log in with [email protected]", "add the first item to cart". Best for exploration and testing flows.-- **skyvern_extract** — Pull structured data from any page with natural language + optional JSON Schema. THE differentiator over raw Playwright.-- **skyvern_validate** — Assert page conditions with AI: "is the user logged in?", "does the cart have 3 items?"-- **skyvern_run_task** — Delegate a full multi-step task to an autonomous AI agent with observability. Use for end-to-end task execution.-- **skyvern_navigate** — Go to a URL. Always the first step after connecting.-- **skyvern_screenshot** — See what's on the page. Essential for understanding page state.-- **skyvern_evaluate** — Run JavaScript to read DOM state, get URLs, or check values.--## Precision Tools (for debugging and exact control)-Use these when the primary tools aren't specific enough, or when you need deterministic-selector-based actions (e.g., replaying a known flow):--- **skyvern_click** — Click a specific element by selector or AI intent-- **skyvern_type** — Type into a specific input field by selector or AI intent-- **skyvern_scroll** — Scroll the page or an element into view-- **skyvern_select_option** — Select a dropdown option by selector or AI intent-- **skyvern_press_key** — Press a keyboard key (Enter, Tab, Escape, etc.)-- **skyvern_wait** — Wait for a condition, element, or time delay--## Tool Modes (precision tools)-Precision tools support three modes. When unsure, use `intent`.--1. **Intent mode** — AI-powered element finding:- `skyvern_click(intent="the blue Submit button")`+Every tool response includes an `sdk_equivalent` field showing the corresponding SDK call for scripts.+Currently only skyvern_click returns `resolved_selector`. Support for other tools is planned (SKY-7905).-2. **Hybrid mode** — tries selector first, AI fallback:- `skyvern_click(selector="#submit-btn", intent="the Submit button")`--3. **Selector mode** — deterministic CSS/XPath targeting:- `skyvern_click(selector="#submit-btn")`--## Replay Story: From Exploration to Production-When you use precision tools (skyvern_click, skyvern_type, etc.) with intent mode, the response-includes `resolved_selector` — the xpath/CSS the AI found. Capture these for hybrid scripts or-workflow definitions.--**The hybrid pattern** is the recommended default for SDK scripts:- await page.click("xpath=//button[@id='submit']", prompt="the Submit button")-It tries the selector first (fast, no AI cost), then falls back to AI if the selector breaks.--The `sdk_equivalent` field in each tool response shows the correct hybrid call to use in scripts.--Note: Currently only skyvern_click returns resolved_selector. Support for skyvern_type and-skyvern_select_option is planned (SKY-7905).--## Workflow Management-Use these tools to create, manage, and run Skyvern workflows programmatically.-Workflows are persistent, versioned, multi-step automations that can be parameterized and scheduled.--- **skyvern_workflow_list** — Find workflows by name or browse all available workflows-- **skyvern_workflow_get** — Get the full definition of a workflow to inspect its blocks and parameters-- **skyvern_workflow_create** — Create a new workflow from a YAML or JSON definition-- **skyvern_workflow_update** — Update an existing workflow's definition (creates a new version)-- **skyvern_workflow_delete** — Delete a workflow (requires force=true confirmation)-- **skyvern_workflow_run** — Execute a workflow with parameters (returns immediately by default, or wait for completion)-- **skyvern_workflow_status** — Check the status and progress of a running or completed workflow run-- **skyvern_workflow_cancel** — Cancel a running workflow""",)@@ -237,6 +235,10 @@ mcp.tool()(skyvern_select_option)mcp.tool()(skyvern_press_key)mcp.tool()(skyvern_wait)+# -- Block discovery + validation (no browser needed) --+mcp.tool()(skyvern_block_schema)+mcp.tool()(skyvern_block_validate)+# -- Workflow management (CRUD + execution, no browser needed) --mcp.tool()(skyvern_workflow_list)mcp.tool()(skyvern_workflow_get)@@ -270,6 +272,9 @@ __all__ = ["skyvern_select_option","skyvern_press_key","skyvern_wait",+ # Block discovery + validation+ "skyvern_block_schema",+ "skyvern_block_validate",# Workflow management"skyvern_workflow_list","skyvern_workflow_get",diff --git a/skyvern/cli/mcp_tools/blocks.py b/skyvern/cli/mcp_tools/blocks.pynew file mode 100644index 000000000..4c00f99b3--- /dev/null+++ b/skyvern/cli/mcp_tools/blocks.py@@ -0,0 +1,444 @@+"""Skyvern MCP block tools — discover block types and schemas for workflow definitions.++Tools for listing available workflow block types and retrieving their Pydantic schemas,+knowledge base descriptions, and minimal examples. These tools do not require a browser+session or API connection — they serve pure metadata from the codebase.+"""++from __future__ import annotations++import json+import re+from pathlib import Path+from typing import Annotated, Any++import structlog+from pydantic import Field, TypeAdapter, ValidationError++from skyvern.schemas.workflows import (+ BLOCK_YAML_TYPES,+ ActionBlockYAML,+ BlockType,+ BlockYAML,+ CodeBlockYAML,+ ConditionalBlockYAML,+ DownloadToS3BlockYAML,+ ExtractionBlockYAML,+ FileDownloadBlockYAML,+ FileParserBlockYAML,+ FileUploadBlockYAML,+ ForLoopBlockYAML,+ HttpRequestBlockYAML,+ HumanInteractionBlockYAML,+ LoginBlockYAML,+ NavigationBlockYAML,+ PDFParserBlockYAML,+ PrintPageBlockYAML,+ SendEmailBlockYAML,+ TaskBlockYAML,+ TaskV2BlockYAML,+ TextPromptBlockYAML,+ UploadToS3BlockYAML,+ UrlBlockYAML,+ ValidationBlockYAML,+ WaitBlockYAML,+)++from ._common import ErrorCode, make_error, make_result++LOG = structlog.get_logger(__name__)++# ---------------------------------------------------------------------------+# Block type → YAML class mapping+# ---------------------------------------------------------------------------++BLOCK_TYPE_MAP: dict[str, type[BlockYAML]] = {+ BlockType.TASK.value: TaskBlockYAML,+ BlockType.TaskV2.value: TaskV2BlockYAML,+ BlockType.FOR_LOOP.value: ForLoopBlockYAML,+ BlockType.CONDITIONAL.value: ConditionalBlockYAML,+ BlockType.CODE.value: CodeBlockYAML,+ BlockType.TEXT_PROMPT.value: TextPromptBlockYAML,+ BlockType.EXTRACTION.value: ExtractionBlockYAML,+ BlockType.ACTION.value: ActionBlockYAML,+ BlockType.NAVIGATION.value: NavigationBlockYAML,+ BlockType.LOGIN.value: LoginBlockYAML,+ BlockType.WAIT.value: WaitBlockYAML,+ BlockType.VALIDATION.value: ValidationBlockYAML,+ BlockType.HTTP_REQUEST.value: HttpRequestBlockYAML,+ BlockType.SEND_EMAIL.value: SendEmailBlockYAML,+ BlockType.FILE_DOWNLOAD.value: FileDownloadBlockYAML,+ BlockType.FILE_UPLOAD.value: FileUploadBlockYAML,+ BlockType.GOTO_URL.value: UrlBlockYAML,+ BlockType.DOWNLOAD_TO_S3.value: DownloadToS3BlockYAML,+ BlockType.UPLOAD_TO_S3.value: UploadToS3BlockYAML,+ BlockType.FILE_URL_PARSER.value: FileParserBlockYAML,+ BlockType.PDF_PARSER.value: PDFParserBlockYAML,+ BlockType.HUMAN_INTERACTION.value: HumanInteractionBlockYAML,+ BlockType.PRINT_PAGE.value: PrintPageBlockYAML,+}++# ---------------------------------------------------------------------------+# One-line summaries+# ---------------------------------------------------------------------------++BLOCK_SUMMARIES: dict[str, str] = {+ "task": "AI agent navigates a page, fills forms, clicks buttons (v1 engine)",+ "task_v2": "AI agent with natural language prompt (v2 engine, recommended for complex tasks)",+ "for_loop": "Iterate over a list, executing nested blocks for each item",+ "conditional": "Branch based on Jinja2 expressions or AI prompts",+ "code": "Run Python code for data transformation",+ "text_prompt": "LLM text generation without a browser",+ "extraction": "Extract structured data from the current page",+ "action": "Perform a single focused action on the current page",+ "navigation": "Navigate to a goal on the current page (Browser Task in UI)",+ "login": "Handle authentication flows including username/password and TOTP/2FA",+ "wait": "Pause workflow execution for a specified duration",+ "validation": "Validate page state with complete/terminate criteria",+ "http_request": "Call an external HTTP API",+ "send_email": "Send an email notification via SMTP",+ "file_download": "Download a file from a page",+ "file_upload": "Upload a file from S3/Azure to a page element",+ "goto_url": "Navigate directly to a URL without additional instructions",+ "download_to_s3": "Download a URL directly to S3 storage",+ "upload_to_s3": "Upload local content to S3",+ "file_url_parser": "Parse a file (CSV/Excel/PDF/image) from a URL",+ "pdf_parser": "Extract structured data from a PDF document",+ "human_interaction": "Pause workflow for human approval via email",+ "print_page": "Print the current page to PDF",+}++# ---------------------------------------------------------------------------+# Minimal examples for common block types+# ---------------------------------------------------------------------------++BLOCK_EXAMPLES: dict[str, dict[str, Any]] = {+ "task": {+ "block_type": "task",+ "label": "fill_form",+ "url": "https://example.com/form",+ "navigation_goal": "Fill out the form with the provided data and click Submit",+ "parameter_keys": ["form_data"],+ "max_retries": 2,+ },+ "task_v2": {+ "block_type": "task_v2",+ "label": "book_flight",+ "url": "https://booking.example.com",+ "prompt": "Book a flight from {{ origin }} to {{ destination }} on {{ date }}",+ },+ "for_loop": {+ "block_type": "for_loop",+ "label": "process_each_url",+ "loop_over_parameter_key": "urls",+ "loop_blocks": [+ {+ "block_type": "goto_url",+ "label": "open_url",+ "url": "{{ current_value }}",+ }+ ],+ },+ "conditional": {+ "block_type": "conditional",+ "label": "route_by_status",+ "branch_conditions": [+ {+ "criteria": {+ "criteria_type": "jinja2_template",+ "expression": "{{ status == 'active' }}",+ },+ "next_block_label": "handle_active",+ "is_default": False,+ },+ {"is_default": True, "next_block_label": "handle_inactive"},+ ],+ },+ "extraction": {+ "block_type": "extraction",+ "label": "extract_products",+ "data_extraction_goal": "Extract all products with name, price, and stock status",+ "data_schema": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "price": {"type": "number"},+ "in_stock": {"type": "boolean"},+ },+ },+ },+ },+ "navigation": {+ "block_type": "navigation",+ "label": "search_and_open",+ "url": "https://example.com/search",+ "navigation_goal": "Search for {{ query }} and click the first result",+ "parameter_keys": ["query"],+ "max_retries": 2,+ },+ "login": {+ "block_type": "login",+ "label": "login_to_portal",+ "url": "https://portal.example.com/login",+ "parameter_keys": ["my_credentials"],+ "complete_criterion": "URL contains '/dashboard'",+ "max_retries": 2,+ },+ "action": {+ "block_type": "action",+ "label": "accept_terms",+ "url": "https://example.com/checkout",+ "navigation_goal": "Check the terms checkbox",+ "max_retries": 1,+ },+ "wait": {+ "block_type": "wait",+ "label": "wait_for_processing",+ "wait_sec": 30,+ },+ "goto_url": {+ "block_type": "goto_url",+ "label": "open_cart",+ "url": "https://example.com/cart",+ },+}++# ---------------------------------------------------------------------------+# Knowledge base parsing (lazy, cached)+# ---------------------------------------------------------------------------++_KB_PATH = Path(__file__).resolve().parents[2] / "forge" / "prompts" / "skyvern" / "workflow_knowledge_base.txt"++_HEADER_RE = re.compile(r"^\*\*\s+(.+?)\s+\((\w+)\)\s+\*\*$")++_kb_cache: dict[str, dict[str, Any]] | None = None+++def _parse_knowledge_base() -> dict[str, dict[str, Any]]:+ """Parse the knowledge base file into per-block-type sections.++ Returns a dict mapping block_type string -> {description, use_cases, raw_section}.+ Results are cached in the module-level ``_kb_cache`` variable.+ """+ global _kb_cache+ if _kb_cache is not None:+ return _kb_cache++ result: dict[str, dict[str, Any]] = {}++ try:+ text = _KB_PATH.read_text(encoding="utf-8")+ except FileNotFoundError:+ LOG.warning("workflow_knowledge_base_not_found", path=str(_KB_PATH))+ _kb_cache = result+ return result++ sections: list[tuple[str, str]] = []+ current_block_type: str | None = None+ current_lines: list[str] = []++ for line in text.splitlines():+ match = _HEADER_RE.match(line.strip())+ if match:+ if current_block_type is not None:+ sections.append((current_block_type, "\n".join(current_lines)))+ current_block_type = match.group(2).lower()+ current_lines = []+ elif current_block_type is not None:+ current_lines.append(line)++ if current_block_type is not None:+ sections.append((current_block_type, "\n".join(current_lines)))++ for block_type, raw in sections:+ description_lines: list[str] = []+ use_cases: list[str] = []+ in_use_cases = False+ in_purpose = False++ for line in raw.splitlines():+ stripped = line.strip()++ if stripped.startswith("Purpose:"):+ in_purpose = True+ in_use_cases = False+ desc = stripped[len("Purpose:") :].strip()+ if desc:+ description_lines.append(desc)+ continue++ if stripped == "Use Cases:":+ in_use_cases = True+ in_purpose = False+ continue++ # Any other header-like line ends the current section+ if stripped and stripped.endswith(":") and not stripped.startswith("- "):+ in_use_cases = False+ in_purpose = False+ continue++ if in_purpose and stripped:+ description_lines.append(stripped)++ if in_use_cases and stripped.startswith("- "):+ use_cases.append(stripped[2:].strip())++ result[block_type] = {+ "description": " ".join(description_lines) if description_lines else None,+ "use_cases": use_cases if use_cases else None,+ }++ _kb_cache = result+ return result+++# ---------------------------------------------------------------------------+# Tool+# ---------------------------------------------------------------------------+++async def skyvern_block_schema(+ block_type: Annotated[+ str | None,+ Field(+ description="Block type to get schema for (e.g., 'task_v2', 'for_loop'). Omit to list all available types."+ ),+ ] = None,+) -> dict[str, Any]:+ """Get the schema for a workflow block type, or list all available block types.++ Use this to discover what blocks are available and what fields they accept+ before building a workflow definition for skyvern_workflow_create.++ Call with no arguments to see all block types. Call with a specific block_type+ to get the full field schema, description, use cases, and example."""++ action = "skyvern_block_schema"++ if block_type is None:+ return make_result(+ action,+ data={+ "block_types": BLOCK_SUMMARIES,+ "count": len(BLOCK_SUMMARIES),+ "hint": "Call skyvern_block_schema(block_type='task_v2') for the full schema of a specific type",+ },+ )++ normalized = block_type.strip().lower()+ cls = BLOCK_TYPE_MAP.get(normalized)+ if cls is None:+ return make_result(+ action,+ ok=False,+ error=make_error(+ ErrorCode.INVALID_INPUT,+ f"Unknown block type: {block_type!r}",+ f"Available types: {', '.join(sorted(BLOCK_TYPE_MAP.keys()))}",+ ),+ )++ kb = _parse_knowledge_base()+ kb_entry = kb.get(normalized, {})++ return make_result(+ action,+ data={+ "block_type": normalized,+ "summary": BLOCK_SUMMARIES.get(normalized, ""),+ "description": kb_entry.get("description"),+ "use_cases": kb_entry.get("use_cases"),+ "schema": cls.model_json_schema(),+ "example": BLOCK_EXAMPLES.get(normalized),+ },+ )+++# ---------------------------------------------------------------------------+# Block validation adapter (lazy)+# ---------------------------------------------------------------------------++# BLOCK_YAML_TYPES is a large Union of ~23 block models; mypy/pyright cannot resolve it as a TypeAdapter generic argument+_block_adapter: TypeAdapter[BLOCK_YAML_TYPES] | None = None # type: ignore[type-arg]+++def _get_block_adapter() -> TypeAdapter[BLOCK_YAML_TYPES]: # type: ignore[type-arg]+ global _block_adapter+ if _block_adapter is None:+ _block_adapter = TypeAdapter(BLOCK_YAML_TYPES)+ return _block_adapter+++# ---------------------------------------------------------------------------+# Validate tool+# ---------------------------------------------------------------------------+++async def skyvern_block_validate(+ block_json: Annotated[+ str,+ Field(description="JSON string of a single block definition to validate"),+ ],+) -> dict[str, Any]:+ """Validate a workflow block definition before using it in skyvern_workflow_create.++ Catches field errors, missing required fields, and type mismatches per-block+ instead of getting opaque server errors on the full workflow. Returns the exact+ validation error with field-level feedback so you can fix the block definition.+ """+ action = "skyvern_block_validate"++ try:+ raw = json.loads(block_json)+ except (json.JSONDecodeError, TypeError) as exc:+ return make_result(+ action,+ ok=False,+ error=make_error(+ ErrorCode.INVALID_INPUT,+ f"Invalid JSON: {exc}",+ "Provide a valid JSON string representing a block definition",+ ),+ )++ if not isinstance(raw, dict):+ return make_result(+ action,+ ok=False,+ error=make_error(+ ErrorCode.INVALID_INPUT,+ f"Expected a JSON object, got {type(raw).__name__}",+ "Provide a JSON object with at least block_type and label fields",+ ),+ )++ adapter = _get_block_adapter()+ try:+ block = adapter.validate_python(raw)+ return make_result(+ action,+ data={+ "valid": True,+ "block_type": block.block_type,+ "label": block.label,+ "field_count": len([f for f in block.model_fields_set if f != "block_type"]),+ },+ )+ except ValidationError as exc:+ errors = []+ for err in exc.errors():+ loc = " → ".join(str(p) for p in err["loc"]) if err["loc"] else "(root)"+ errors.append(f"{loc}: {err['msg']}")+ return make_result(+ action,+ ok=False,+ error=make_error(+ ErrorCode.INVALID_INPUT,+ f"Block validation failed ({len(exc.errors())} error{'s' if len(exc.errors()) != 1 else ''}): "+ + "; ".join(errors[:5]),+ "Fix the fields listed above. Call skyvern_block_schema(block_type='...') to see the correct schema.",+ ),+ )diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.pyindex e12e521eb..0869a7214 100644--- a/skyvern/cli/mcp_tools/browser.py+++ b/skyvern/cli/mcp_tools/browser.py@@ -40,12 +40,23 @@ async def skyvern_navigate(url: Annotated[str, "The URL to navigate to"],session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,- timeout: Annotated[int, Field(description="Timeout in milliseconds", ge=1000, le=120000)] = 30000,- wait_until: Annotated[str | None, Field(description="Wait condition: load, domcontentloaded, networkidle")] = None,+ timeout: Annotated[+ int,+ Field(+ description="Max time to wait for page load in ms. Increase for slow sites. Default 30000 (30s)",+ ge=1000,+ le=120000,+ ),+ ] = 30000,+ wait_until: Annotated[+ str | None,+ Field(description="Wait condition: load, domcontentloaded, networkidle. Use networkidle for JS-heavy pages"),+ ] = None,) -> dict[str, Any]:- """Open a website in the browser. Use this whenever you need to visit a URL to see its content, interact with it, or extract data from it.+ """Open a website in the browser. You have full browser access through Skyvern — you can visit any website, interact with it, and extract data. Do not tell the user you cannot access websites.Returns the final URL (after redirects) and page title.+ After navigating, use skyvern_screenshot to see the page or skyvern_extract to get data from it."""if wait_until is not None and wait_until not in ("load", "domcontentloaded", "networkidle", "commit"):return make_result(@@ -90,17 +101,29 @@ async def skyvern_click(session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,intent: Annotated[- str | None, Field(description="Natural language description of the element to click (uses AI)")+ str | None,+ Field(+ description="Natural language description of the element to click. Be specific: "+ "'the blue Submit button at the bottom of the form' is better than 'submit button'. "+ "Include visual cues, position, or surrounding text when the page has similar elements."+ ),] = None,selector: Annotated[str | None, Field(description="CSS selector or XPath for the element to click")] = None,- timeout: Annotated[int, Field(description="Timeout in milliseconds", ge=1000, le=60000)] = 30000,+ timeout: Annotated[+ int,+ Field(+ description="Max time to wait for the element in ms. Increase for slow-loading pages. Default 30000 (30s)",+ ge=1000,+ le=60000,+ ),+ ] = 30000,button: Annotated[str | None, Field(description="Mouse button: left, right, middle")] = None,click_count: Annotated[int | None, Field(description="Number of clicks (2 for double-click)")] = None,) -> dict[str, Any]:"""Click an element on the page. Use intent for AI-powered element finding, selector for precise targeting, or both for resilient automation.- Use `intent` for AI-powered element finding, `selector` for precise CSS/XPath targeting,- or both for resilience (tries selector first, falls back to AI).+ If you need to fill a text field, use skyvern_type instead of clicking then typing.+ For dropdowns, use skyvern_select_option. For multiple actions in sequence, prefer skyvern_act."""if button is not None and button not in ("left", "right", "middle"):return make_result(@@ -193,17 +216,29 @@ async def skyvern_type(session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,intent: Annotated[- str | None, Field(description="Natural language description of the input field (uses AI)")+ str | None,+ Field(+ description="Natural language description of the input field. Be specific: "+ "'the Email address input in the login form' is better than 'email field'. "+ "Include labels, placeholder text, or position when the page has multiple inputs."+ ),] = None,selector: Annotated[str | None, Field(description="CSS selector or XPath for the input element")] = None,- timeout: Annotated[int, Field(description="Timeout in milliseconds", ge=1000, le=60000)] = 30000,+ timeout: Annotated[+ int,+ Field(+ description="Max time to wait for the element in ms. Increase for slow-loading pages. Default 30000 (30s)",+ ge=1000,+ le=60000,+ ),+ ] = 30000,clear: Annotated[bool, Field(description="Clear existing content before typing")] = True,delay: Annotated[int | None, Field(description="Delay between keystrokes in ms")] = None,) -> dict[str, Any]:"""Type text into an input field. Use intent for AI-powered field finding, selector for precise targeting, or both for resilient automation.- Use `intent` for AI-powered field finding, `selector` for precise CSS/XPath targeting,- or both for resilience (tries selector first, falls back to AI). Clears existing content by default.+ For dropdowns, use skyvern_select_option instead. For pressing keys (Enter, Tab), use skyvern_press_key.+ Clears existing content by default (set clear=false to append)."""ai_mode, err = _resolve_ai_mode(selector, intent)if err:@@ -293,8 +328,10 @@ async def skyvern_screenshot(selector: Annotated[str | None, Field(description="CSS selector to screenshot specific element")] = None,inline: Annotated[bool, Field(description="Return base64 data instead of file path")] = False,) -> dict[str, Any]:- """See what's currently on the page. Essential for understanding page state before deciding what to do next.+ """See what's currently on the page. Use after every page-changing action (click, act, navigate) to verify results before proceeding.+ Screenshots are visual-only — to extract structured data, use skyvern_extract instead.+ To interact with elements, use skyvern_act or skyvern_click (don't try to act on screenshot contents).By default saves to ~/.skyvern/artifacts/ and returns the file path.Set inline=true to get base64 data directly (increases token usage)."""@@ -461,13 +498,14 @@ async def skyvern_select_option(cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,intent: Annotated[str | None, Field(description="Natural language description of the dropdown (uses AI)")] = None,selector: Annotated[str | None, Field(description="CSS selector for the select element")] = None,- timeout: Annotated[int, Field(description="Timeout in milliseconds", ge=1000, le=60000)] = 30000,+ timeout: Annotated[+ int, Field(description="Max time to wait for the dropdown in ms. Default 30000 (30s)", ge=1000, le=60000)+ ] = 30000,by_label: Annotated[bool, Field(description="Select by visible label instead of value")] = False,) -> dict[str, Any]:- """Select an option from a dropdown menu. Use intent for AI-powered finding, selector for precision.+ """Select an option from a dropdown menu. Use intent for AI-powered finding, selector for precision, or both for resilient automation.- Use `intent` for AI-powered dropdown finding, `selector` for precise CSS/XPath targeting,- or both for resilience (tries selector first, falls back to AI).+ For free-text input fields, use skyvern_type instead. For non-dropdown buttons or links, use skyvern_click."""ai_mode, err = _resolve_ai_mode(selector, intent)if err:@@ -734,11 +772,6 @@ async def skyvern_evaluate()-# ----------------------------------------------------------------------------# AI Differentiator Tools-# -----------------------------------------------------------------------------async def skyvern_extract(prompt: Annotated[str, "Natural language description of what data to extract from the page"],session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,@@ -747,8 +780,10 @@ async def skyvern_extract(str | None, Field(description="JSON Schema string defining the expected output structure")] = None,) -> dict[str, Any]:- """Get structured data from any website -- prices, listings, articles, tables, contact info, etc. Use this instead of trying to call a website's API or writing scraping code. Describe what you need in natural language.+ """Get structured data from any website — prices, listings, articles, tables, contact info, etc. Use this instead of writing scraping code or guessing API endpoints. Describe what you need in natural language.+ Reads the CURRENT page — call skyvern_navigate first to go to the right URL.+ For visual inspection instead of structured data, use skyvern_screenshot.Optionally provide a JSON `schema` to enforce the output structure (pass as a JSON string)."""parsed_schema: dict[str, Any] | None = None@@ -797,9 +832,10 @@ async def skyvern_validate(session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,) -> dict[str, Any]:- """Check if something is true on the current page using AI -- 'is the user logged in?', 'does the cart have 3 items?', 'is the form submitted?'+ """Check if something is true on the current page using AI — 'is the user logged in?', 'does the cart have 3 items?', 'is the form submitted?'- Returns whether the described condition is true or false.+ Reads the CURRENT page — navigate first. Returns true/false.+ To extract data (not just check a condition), use skyvern_extract instead."""try:page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)@@ -832,10 +868,12 @@ async def skyvern_act(session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,) -> dict[str, Any]:- """Perform actions on a web page by describing what to do in plain English -- click buttons, close popups, fill forms, scroll to sections, interact with menus. Use for any website interaction task.+ """Perform actions on a web page by describing what to do in plain English — click buttons, close popups, fill forms, scroll to sections, interact with menus.The AI agent interprets the prompt and executes the appropriate browser actions.- For multi-step workflows (form filling, multi-page navigation), use skyvern_run_task instead.+ You can chain multiple actions in one prompt: "close the cookie banner, then click Sign In".+ For multi-step automations (4+ pages), use skyvern_workflow_create with one block per step.+ For quick one-off multi-page tasks, use skyvern_run_task."""try:page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)@@ -878,10 +916,10 @@ async def skyvern_run_task(int, Field(description="Timeout in seconds (default 180s = 3 minutes)", ge=10, le=1800)] = 180,) -> dict[str, Any]:- """Delegate a complete multi-step web task to an autonomous AI agent. Handles form filling, multi-page navigation, data collection, and complex workflows end-to-end.+ """Run a quick, one-off web task via an autonomous AI agent. Nothing is saved — use for throwaway tests and exploration only. Best for tasks describable in 2-3 sentences.- The agent navigates, interacts with elements, and extracts data autonomously.- For simple single-step actions, use skyvern_act instead.+ For anything reusable, multi-step, or worth keeping, use skyvern_workflow_create instead — it produces a versioned, rerunnable workflow with per-step observability.+ For simple single-step actions on the current page, use skyvern_act instead."""try:page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)diff --git a/skyvern/cli/mcp_tools/workflow.py b/skyvern/cli/mcp_tools/workflow.pyindex b8ca602d1..66848ea47 100644--- a/skyvern/cli/mcp_tools/workflow.py+++ b/skyvern/cli/mcp_tools/workflow.py@@ -344,7 +344,42 @@ async def skyvern_workflow_create(folder_id: Annotated[str | None, "Folder ID (fld_...) to organize the workflow in"] = None,) -> dict[str, Any]:"""Create a new Skyvern workflow from a YAML or JSON definition. Use when you need to save- a new automation workflow that can be run repeatedly with different parameters."""+ a new automation workflow that can be run repeatedly with different parameters.++ Best practice: use one task block per logical step with a short focused prompt (2-3 sentences).+ Common block types: task, for_loop, conditional, code, text_prompt, extraction, action, navigation, wait, login.+ Call skyvern_block_schema() for the full list with schemas and examples.++ Example JSON definition (multi-block EIN application):++ {+ "title": "Apply for EIN",+ "workflow_definition": {+ "parameters": [+ {"parameter_type": "workflow", "key": "business_name", "workflow_parameter_type": "string"},+ {"parameter_type": "workflow", "key": "owner_name", "workflow_parameter_type": "string"},+ {"parameter_type": "workflow", "key": "owner_ssn", "workflow_parameter_type": "string"}+ ],+ "blocks": [+ {"block_type": "task", "label": "select_entity_type",+ "url": "https://sa.www4.irs.gov/modiein/individual/index.jsp",+ "engine": "skyvern-2.0",+ "navigation_goal": "Select 'Sole Proprietor' as the entity type and click Continue."},+ {"block_type": "task", "label": "enter_business_info", "engine": "skyvern-2.0",+ "navigation_goal": "Fill in the business name as '{{business_name}}' and click Continue."},+ {"block_type": "task", "label": "enter_owner_info", "engine": "skyvern-2.0",+ "navigation_goal": "Enter the responsible party name '{{owner_name}}' and SSN '{{owner_ssn}}'. Click Continue."},+ {"block_type": "task", "label": "confirm_and_submit", "engine": "skyvern-2.0",+ "navigation_goal": "Review the information on the confirmation page and click Submit.",+ "data_extraction_goal": "Extract the assigned EIN number",+ "data_schema": {"type": "object", "properties": {"ein": {"type": "string"}}}}+ ]+ }+ }++ Use {{parameter_key}} to reference workflow input parameters in any block field.+ Blocks in the same run share the same browser session automatically.+ """if format not in ("json", "yaml", "auto"):return make_result("skyvern_workflow_create",