Skip to content

Automate browser based workflows with AI

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.py
index 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.py
index 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 also
injected (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.md
index 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 fresh
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index 062e9d765..2724ce72f 100644
--- a/skyvern/forge/agent.py
+++ b/skyvern/forge/agent.py
@@ -1,5 +1,6 @@
import asyncio
import base64
+import contextlib
import hashlib
import json
import 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 = None
reuse_speculative_llm_response = False
speculative_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)
+ )
break
action = 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 extract
summary_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 = None
lookup_result: extraction_cache.LookupResult | None = None
try:
- # 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.py
index 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) -> Non
captured = _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())