Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
skyvern-cli: clarify skill guidance on workflow-level session toggles (#6111)
Marc Kelechava67a92e480f5d
diff --git a/skyvern/cli/mcp_tools/blocks.py b/skyvern/cli/mcp_tools/blocks.pyindex 0ef8741f4..9e1c6d4b6 100644--- a/skyvern/cli/mcp_tools/blocks.py+++ b/skyvern/cli/mcp_tools/blocks.py@@ -130,7 +130,6 @@ BLOCK_EXAMPLES: dict[str, dict[str, Any]] = {"title": "Search and Open Result","navigation_goal": "Search for {{ query }} and click the first result","parameter_keys": ["query"],- "max_retries": 2,},"extraction": {"block_type": "extraction",@@ -212,14 +211,12 @@ BLOCK_EXAMPLES: dict[str, dict[str, Any]] = {"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",diff --git a/skyvern/cli/mcp_tools/workflow.py b/skyvern/cli/mcp_tools/workflow.pyindex 7e87c1531..af26f080b 100644--- a/skyvern/cli/mcp_tools/workflow.py+++ b/skyvern/cli/mcp_tools/workflow.py@@ -910,6 +910,13 @@ async def skyvern_workflow_create(Defaults to AI agent execution (run_with="agent"). For JSON definitions, code_version=2 is alsoinjected (YAML definitions go through the backend schema, which currently leaves code_version unset).Pass run_with="code" to opt into cached script execution. Blocks share a browser session automatically.++ Leave optional toggles and overrides unset unless the user explicitly asks for them. This+ applies to workflow-level fields (persist_browser_session, extra_http_headers,+ totp_verification_url, totp_identifier, etc.) AND block-level overrides (max_retries,+ max_steps_per_run, totp_identifier, complete_criterion, error_code_mapping,+ continue_on_failure, engine, model, etc.). The schema defaults are intentional; silently+ flipping them changes behavior the user did not request."""if format not in ("json", "yaml", "auto"):return make_result(diff --git a/skyvern/cli/skills/skyvern/references/sessions.md b/skyvern/cli/skills/skyvern/references/sessions.mdindex ecdf6e333..5730d5b08 100644--- a/skyvern/cli/skills/skyvern/references/sessions.md+++ b/skyvern/cli/skills/skyvern/references/sessions.md@@ -1,10 +1,21 @@# Session Reuse-## When to reuse a session+This guidance is about **runtime session reuse** — passing a `pbs_*` ID as `browser_session_id`+to `skyvern_workflow_run` or `skyvern_run_task` so a one-off run continues a browser that is+already open.-- Multiple actions on one authenticated site.-- Workflow chains that depend on retained state.-- Follow-up extraction immediately after login.+It is NOT about the workflow-level "Save & Reuse Session" toggle (`persist_browser_session`).+Leave that toggle unset unless the user explicitly asks for cross-run state retention — it+defaults to off and should stay off.++Blocks inside a single workflow already share one browser session automatically — do NOT+pass `browser_session_id` to keep state between blocks of the same run. Reach for runtime+session reuse only across separate runs.++## When to reuse a runtime session++- A follow-up task that depends on state from a session you just opened.+- Chained workflow runs where a later run needs the authenticated state from the first.## When to start freshdiff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.pyindex 062e9d765..2724ce72f 100644--- a/skyvern/forge/agent.py+++ b/skyvern/forge/agent.py@@ -1,5 +1,6 @@import asyncioimport base64+import contextlibimport hashlibimport jsonimport os@@ -299,6 +300,20 @@ def _schedule_summary_shadow_check_for_hit()+def _discard_background_task_result(task: asyncio.Task) -> None:+ # Retrieve the exception so asyncio does not warn about an unretrieved task failure.+ if not task.cancelled():+ task.exception()+++async def _cancel_pending_prefetch_task(task: asyncio.Task | None) -> None:+ if task is None or task.done():+ return+ task.cancel()+ with contextlib.suppress(asyncio.CancelledError):+ await task++async def _build_open_tabs_context(browser_state: BrowserState,working_page: Page | None,@@ -1283,6 +1298,20 @@ class ForgeAgent:actions_and_results=None,cua_response=None,)+ prefetched_summary_task: asyncio.Task[dict[str, Any]] | None = None+ current_artifact_task: asyncio.Task | None = None++ async def await_background_artifact_task() -> None:+ nonlocal current_artifact_task+ if current_artifact_task is None:+ return+ task = current_artifact_task+ current_artifact_task = None+ try:+ await task+ except Exception:+ LOG.warning("Background artifact task failed, continuing", exc_info=True)+try:LOG.info("Starting agent step",@@ -1322,6 +1351,7 @@ class ForgeAgent:speculative_plan: SpeculativePlan | None = Nonereuse_speculative_llm_response = Falsespeculative_llm_metadata: SpeculativeLLMMetadata | None = None+ is_extraction_task = not task.navigation_goal and not isinstance(task_block, ValidationBlock)if context:speculative_plan = context.speculative_plans.pop(step.step_id, None)@@ -1341,6 +1371,12 @@ class ForgeAgent:context=context,)else:+ if is_extraction_task and engine not in CUA_ENGINES and injected_actions is None:+ prefetched_summary_task = asyncio.create_task(+ self._fetch_data_extraction_summary_response(task, step)+ )+ prefetched_summary_task.add_done_callback(_discard_background_task_result)+(scraped_page,extract_action_prompt,@@ -1399,8 +1435,15 @@ class ForgeAgent:)else:- if not task.navigation_goal and not isinstance(task_block, ValidationBlock):- actions = [await self.create_extract_action(task, step, scraped_page)]+ if is_extraction_task:+ actions = [+ await self.create_extract_action(+ task,+ step,+ scraped_page,+ prefetched_summary_task=prefetched_summary_task,+ )+ ]else:llm_key_override = task.llm_key# FIXME: Redundant engine check?@@ -1623,6 +1666,8 @@ class ForgeAgent:element_id_to_last_action: dict[str, int] = dict()for action_idx, action_node in enumerate(action_linked_list):+ await await_background_artifact_task()+context = skyvern_context.ensure_context()if context.refresh_working_page:LOG.warning(@@ -1646,7 +1691,9 @@ class ForgeAgent:)detailed_agent_step_output.actions_and_results[action_idx] = (action, [action_result])action.action_id = (await app.DATABASE.workflow_params.create_action(action=action)).action_id- await self.record_artifacts_after_action(task, step, browser_state, engine, action)+ current_artifact_task = asyncio.create_task(+ self.record_artifacts_after_action(task, step, browser_state, engine, action)+ )breakaction = action_node.action@@ -1759,7 +1806,9 @@ class ForgeAgent:)await asyncio.sleep(wait_time)if not is_page_level_scroll:- await self.record_artifacts_after_action(task, step, browser_state, engine, action)+ current_artifact_task = asyncio.create_task(+ self.record_artifacts_after_action(task, step, browser_state, engine, action)+ )else:LOG.info("Skipping post-action artifacts for page-level scroll",@@ -1841,6 +1890,8 @@ class ForgeAgent:)return failed_step, detailed_agent_step_output.get_clean_detailed_output()+ await await_background_artifact_task()+LOG.info("Actions executed successfully, marking step as completed",step_order=step.order,@@ -1952,6 +2003,9 @@ class ForgeAgent:output=detailed_agent_step_output.to_agent_step_output(),)return failed_step, detailed_agent_step_output.get_clean_detailed_output()+ finally:+ await _cancel_pending_prefetch_task(prefetched_summary_task)+ await await_background_artifact_task()async def _generate_cua_actions(self,@@ -5757,11 +5811,10 @@ class ForgeAgent:)@staticmethod- async def create_extract_action(task: Task, step: Step, scraped_page: ScrapedPage) -> ExtractAction:+ async def _fetch_data_extraction_summary_response(task: Task, step: Step) -> dict[str, Any]:context = skyvern_context.ensure_context()local_datetime_str = datetime.now(context.tz_info).isoformat()capped_schema = truncate_extraction_schema(task.extracted_information_schema)- # generate reasoning by prompt llm to think briefly what data to extractsummary_kwargs: dict[str, Any] = {"data_extraction_goal": task.data_extraction_goal,"data_extraction_schema": capped_schema,@@ -5775,25 +5828,11 @@ class ForgeAgent:kwargs=summary_kwargs,)- # Cache the summary LLM call — the inputs (goal, schema) are identical- # across loop iterations that share an extraction configuration, even- # when each iteration navigates to a different URL. The `try` is- # narrowed to just compute_cache_key + lookup so a downstream log- # failure can't double-count as a lookup_error.workflow_run_id = context.workflow_run_id if context else None- # task.workflow_permanent_id is unset on most fetch paths — fall back to context.wpid_for_cache = task.workflow_permanent_id or (context.workflow_permanent_id if context else None)cache_key: str | None = Nonelookup_result: extraction_cache.LookupResult | None = Nonetry:- # data-extraction-summary plans *what* will be extracted from- # goal + schema; only those inputs, plus the date (via datetime),- # affect the rendered prompt, so everything else is intentionally- # omitted. Hash the post-ceiling value for `data_extraction_schema`- # — when the rendered prompt exceeds PROMPT_HARD_CEILING_TOKENS the- # ceiling drops that field to None, so two oversized-schema requests- # that both get dropped produce an identical LLM prompt and must- # share a cache key.cache_key = extraction_cache.compute_cache_key(call_path="agent",data_extraction_goal=task.data_extraction_goal,@@ -5814,8 +5853,6 @@ class ForgeAgent:cache_path="agent",exc_info=True,)- # Preserve cache_key so the store() below can still warm the cache- # for subsequent identical calls even when lookup() fails transiently.if lookup_result is not None and lookup_result.hit and isinstance(lookup_result.value, dict):LOG.info(@@ -5839,8 +5876,6 @@ class ForgeAgent:cache_path="agent",)elif lookup_result is not None:- # Genuine miss only — non-dict hits are logged as a warning above and- # must NOT also emit a miss log (would double-count in Datadog).LOG.info("data-extraction-summary cache miss",workflow_run_id=workflow_run_id,@@ -5940,6 +5975,27 @@ class ForgeAgent:"data_extraction_summary_resp unexpectedly None after cache/LLM block "f"(workflow_run_id={workflow_run_id!r}, cache_key={cache_key!r})")+ return data_extraction_summary_resp++ @staticmethod+ async def create_extract_action(+ task: Task,+ step: Step,+ scraped_page: ScrapedPage,+ prefetched_summary_task: asyncio.Task[dict[str, Any]] | None = None,+ ) -> ExtractAction:+ if prefetched_summary_task is not None:+ try:+ data_extraction_summary_resp = await prefetched_summary_task+ except Exception as exc:+ LOG.warning(+ "Prefetched extraction summary failed, falling back to inline call",+ error_type=type(exc).__name__,+ exc_info=True,+ )+ data_extraction_summary_resp = await ForgeAgent._fetch_data_extraction_summary_response(task, step)+ else:+ data_extraction_summary_resp = await ForgeAgent._fetch_data_extraction_summary_response(task, step)return ExtractAction(reasoning=data_extraction_summary_resp.get("summary", "Extracting information from the page"),data_extraction_goal=task.data_extraction_goal,diff --git a/tests/unit/test_data_extraction_summary_schema_cap.py b/tests/unit/test_data_extraction_summary_schema_cap.pyindex 312d721d0..be2d9848f 100644--- a/tests/unit/test_data_extraction_summary_schema_cap.py+++ b/tests/unit/test_data_extraction_summary_schema_cap.py@@ -77,3 +77,103 @@ def test_create_extract_action_passes_small_schema_unchanged(monkeypatch) -> Noncaptured = _run_create_extract_action(monkeypatch, small_schema)assert captured["data_extraction_schema"] == small_schema+++def test_create_extract_action_uses_prefetched_summary_task(monkeypatch) -> None:+ import asyncio+ from unittest.mock import MagicMock++ from skyvern.forge import agent as agent_module++ llm_called = False++ async def fake_handler(*, prompt, step, prompt_name, **_ignored):+ nonlocal llm_called+ llm_called = True+ return {"summary": "inline"}++ monkeypatch.setattr(agent_module.app, "EXTRACTION_LLM_API_HANDLER", fake_handler)++ task = MagicMock()+ task.data_extraction_goal = "Extract documents"+ task.extracted_information_schema = {"type": "object"}+ task.task_id = "tsk_test"+ task.workflow_run_id = "wr_test"+ task.organization_id = "o_test"+ task.workflow_system_prompt = None++ step = MagicMock(step_id="stp_test", order=0)+ scraped_page = MagicMock(url="https://example.test")++ async def _run() -> None:+ prefetched: asyncio.Task[dict[str, str]] = asyncio.create_task(+ asyncio.sleep(0, result={"summary": "prefetched"})+ )+ action = await agent_module.ForgeAgent.create_extract_action(+ task=task,+ step=step,+ scraped_page=scraped_page,+ prefetched_summary_task=prefetched,+ )+ assert action.reasoning == "prefetched"+ assert llm_called is False++ asyncio.run(_run())+++def test_create_extract_action_prefetch_failure_falls_back_to_inline(monkeypatch) -> None:+ import asyncio+ from unittest.mock import MagicMock++ from skyvern.forge import agent as agent_module++ llm_called = False++ async def fake_handler(*, prompt, step, prompt_name, **_ignored):+ nonlocal llm_called+ llm_called = True+ return {"summary": "inline"}++ monkeypatch.setattr(agent_module.app, "EXTRACTION_LLM_API_HANDLER", fake_handler)+ monkeypatch.setattr(+ agent_module.skyvern_context,+ "ensure_context",+ lambda: MagicMock(tz_info=None, workflow_run_id="wr_test"),+ )+ monkeypatch.setattr(+ agent_module.extraction_cache,+ "compute_cache_key",+ lambda **_: None,+ )+ monkeypatch.setattr(+ agent_module.extraction_cache,+ "lookup",+ lambda *a, **k: None,+ )++ task = MagicMock()+ task.data_extraction_goal = "Extract documents"+ task.extracted_information_schema = {"type": "object"}+ task.task_id = "tsk_test"+ task.workflow_run_id = "wr_test"+ task.organization_id = "o_test"+ task.workflow_system_prompt = None++ step = MagicMock(step_id="stp_test", order=0)+ scraped_page = MagicMock(url="https://example.test")++ async def failing_prefetch() -> dict[str, str]:+ raise RuntimeError("prefetch failed")++ async def _run() -> None:+ prefetched = asyncio.create_task(failing_prefetch())+ action = await agent_module.ForgeAgent.create_extract_action(+ task=task,+ step=step,+ scraped_page=scraped_page,+ prefetched_summary_task=prefetched,+ )+ assert action.reasoning == "inline"+ assert llm_called is True++ asyncio.run(_run())