vodorod/Dorod-Sky
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

doc update - add run tasks page (#2425)

Browse Source
This commit is contained in:
Shuchang Zheng
2025-05-24 23:46:31 -07:00
committed by GitHub
parent 601cd099f7
commit 6f83978937
27 changed files with 1168 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
fern/browser-sessions/introduction.mdx Normal file
View File

@@ -0,0 +1,33 @@
---
title: Introduction
subtitle: Run continuous tasks and workflows with a long-lived browser session
slug: browser-sessions/introduction
---
## Why Browser Sessions?
Skyvern Browser Session is a way to persist the real-time state of the browser, so that any run can continue from where the previous run left off. Here are some scenarios when Skyvern Browser Session comes in handy:
- You have multiple continuous tasks that need to interact with the browser in real-time without much delay. For example, you are developing a phone agent for your customer support center and your agent needs access to real time information in the browser.
- You have several related tasks that may need to be executed but with interruptions in between. For example, you are developing an shopping agent that needs human in the loop to help fulfill the purchase.
Skyvern Browser Sessions is currently is only available via [API & SDK](/api-reference/api-reference/browser-session/create-browser-session).
## Create a Browser Session
```python
from skyvern import Skyvern
skyvern = Skyvern(api_key="YOUR_API_KEY")
browser_session = await skyvern.browser_sessions.create_browser_session(
timeout=60,
)
```
The `timeout` parameter (`>=5, <=10080`) is the max time in minutes that the browser session can run.
## Get Information Of A Browser Session
[API doc](/api-reference/api-reference/browser-session/get-browser-session)
## Close a Browser Session
[API doc](/api-reference/api-reference/browser-session/close-browser-session)

0
fern/credentials/credit_cards.mdx → fern/credentials/credit-cards.mdx
View File

10
fern/credentials/totp.mdx
View File

@@ -15,7 +15,7 @@ Save your username and password in [Skyvern Credential](https://app.skyvern.com/
See [Password Management](/credentials/passwords#manage-passwords-in-skyvern-cloud) for more details.
## Option 2: Get Code From Your Endpoint
You can pass `totp_verification_url` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). Inside this endpoint hosted by you, you have to conform to the following schema:
You can pass `totp_url` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). Inside this endpoint hosted by you, you have to conform to the following schema:
### Set Up Your TOTP Endpoint
For websites that requires a verification code to complete a task, you have to set up a TOTP endpoint for Skyvern to fetch the verification code.
@@ -47,10 +47,12 @@ def validate_skyvern_request_headers(request: Request) -> bool:
return header_skyvern_signature == client_generated_signature
```
SKYVERN_API_KEY: this is the [api key](/running-tasks/introduction) specific to your organization
SKYVERN_API_KEY: you can get the API KEY from [Skyvern Settings](https://app.skyvern.com/settings).
## Option 3: Push Code To Skyvern
You can pass `totp_identifier` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). When the TOTP code arrives at your inbox or as a text message, all you need to do is to send the email/message (Gmail + Zapier integration can be a good solution to set up email forwarding) to Skyvern's TOTP receiver endpoint. See the [TOTP API for more details](https://docs.skyvern.com/api-reference/api-reference/credentials/send-totp-code).
Find TOTP API doc [here](/api-reference/api-reference/credentials/send-totp-code).
You can pass `totp_identifier` when running [a task](/api-reference/api-reference/agent/run-task) or a [workflow](/api-reference/api-reference/agent/run-workflow). When the TOTP code arrives at your inbox, all you need to do is to send the email/message (Gmail + Zapier integration can be a good solution to set up email forwarding) to Skyvern's TOTP endpoint.
### Forwarding Your Email To Skyvern (Gmail + Zapier)
This setup requires a Zapier pro plan account.
@@ -98,7 +100,7 @@ In the Setup, choose “POST” under the `Action event` selection. Then click
In the “Configure”, set up these in order to make a POST request to Skyvern’s TOTP API:
- URL: [`https://api.skyvern.com/api/v1/totp`](https://api.skyvern.com/api/v1/totp)
- URL: [`https://api.skyvern.com/v1/credentials/totp`](https://api.skyvern.com/v1/credentials/totp)
- Payload Type: json
- Data:
- totp_identifier: choose `Raw To Email` after clicking the “+” sign

16
fern/docs.yml
View File

@@ -74,14 +74,16 @@ navigation:
path: getting-started/prompting-guide.mdx
- section: Tasks
contents:
- page: Tasks API
path: running-tasks/api-spec.mdx
- page: Webhooks FAQ
path: running-tasks/webhooks-faq.mdx
- page: Task Features
path: running-tasks/run-tasks.mdx
- page: Visualizing Results
path: running-tasks/visualizing-results.mdx
- page: Webhooks FAQ
path: running-tasks/webhooks-faq.mdx
- page: Advanced Settings for tasks
path: running-tasks/advanced-features.mdx
- page: Legacy Task APIs
path: running-tasks/api-spec.mdx
- section: Workflows
contents:
- page: Introduction
@@ -103,11 +105,15 @@ navigation:
- page: Password Management
path: credentials/passwords.mdx
- page: Credit Card Management
path: credentials/credit_cards.mdx
path: credentials/credit-cards.mdx
- page: TOTP (2FA/MFA/Verification Code)
path: credentials/totp.mdx
- page: Bitwarden
path: credentials/bitwarden.mdx
- section: Browser Sessions (Beta)
contents:
- page: Introduction
path: browser-sessions/introduction.mdx
- section: Integrations
contents:
- page: Skyvern MCP

2
fern/fern.config.json
View File

@@ -1,4 +1,4 @@
{
"organization": "skyvern",
"version": "0.57.15"
"version": "0.63.6"
}

4
fern/getting-started/quickstart.mdx
View File

@@ -6,7 +6,7 @@ slug: getting-started/quickstart
## Skyvern Cloud
Sign up on https://app.skyvern.com/ to get $5 free credits.
Ask the Skyvern agent to run a task and see it in action live! Here are some examples you can try:
Ask the Skyvern agent to run a task and see it in action! Here are some examples you can try:
- `Navigate to the Hacker News homepage and get the top 3 posts.`
- `Go to google finance and find the "AAPL" stock price. COMPLETE when the search results for "AAPL" are displayed and the stock price is extracted.`
@@ -40,7 +40,7 @@ More API & SDK information can be found in the [API Reference](/api-reference) s
### Run Task Locally
You can also run browser tasks locally in your python code but it takes a bit more effort to set up the environment:
1. **Configure Skyvern** Run the setup wizard which will guide you through the configuration process, including Skyvern [MCP](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md) integration. This will generate a `.env` as the configuration settings file.
1. **Configure Skyvern** Run the setup wizard which will guide you through the configuration process, including Skyvern [MCP](/integrations/mcp) integration. This will generate a `.env` as the configuration settings file.
```bash
skyvern init
```

BIN
fern/images/run_tasks/ui_run_task.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 324 KiB

443
fern/openapi/skyvern_openapi.json
View File

@@ -463,6 +463,134 @@
]
}
]
},
"get": {
"tags": [
"Workflows"
],
"summary": "Get Workflows",
"description": "Get all workflows with the latest version for the organization.",
"operationId": "get_workflows_v1_workflows_get",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 1,
"title": "Page"
}
},
{
"name": "page_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 10,
"title": "Page Size"
}
},
{
"name": "only_saved_tasks",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Only Saved Tasks"
}
},
{
"name": "only_workflows",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Only Workflows"
}
},
{
"name": "title",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "",
"title": "Title"
}
},
{
"name": "template",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Template"
}
},
{
"name": "x-api-key",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "API key for authentication",
"title": "X-Api-Key"
},
"description": "API key for authentication"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Workflow"
},
"title": "Response Get Workflows V1 Workflows Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-fern-sdk-group-name": "workflows",
"x-fern-sdk-method-name": "get_workflows",
"x-fern-examples": [
{
"code-samples": [
{
"sdk": "python",
"code": "from skyvern import Skyvern\n\nskyvern = Skyvern(api_key=\"YOUR_API_KEY\")\nworkflows = await skyvern.workflows.get_workflows()\nprint(workflows)\n"
}
]
}
]
}
},
"/v1/workflows/{workflow_id}": {
@@ -628,6 +756,151 @@
]
}
},
"/v1/artifacts/{artifact_id}": {
"get": {
"tags": [
"Artifacts"
],
"summary": "Get an artifact",
"description": "Get an artifact",
"operationId": "get_artifact_v1_artifacts__artifact_id__get",
"parameters": [
{
"name": "artifact_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Artifact Id"
}
},
{
"name": "x-api-key",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "API key for authentication",
"title": "X-Api-Key"
},
"description": "API key for authentication"
}
],
"responses": {
"200": {
"description": "Successfully retrieved artifact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Artifact"
}
}
}
},
"404": {
"description": "Artifact not found"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-fern-sdk-group-name": "artifacts",
"x-fern-sdk-method-name": "get_artifact"
}
},
"/v1/runs/{run_id}/retry_webhook": {
"post": {
"tags": [
"Agent"
],
"summary": "Retry run webhook",
"description": "Retry sending the webhook for a run",
"operationId": "retry_run_webhook_v1_runs__run_id__retry_webhook_post",
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "The id of the task run or the workflow run.",
"examples": [
"tsk_123",
"wr_123"
],
"title": "Run Id"
},
"description": "The id of the task run or the workflow run."
},
{
"name": "x-api-key",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "API key for authentication",
"title": "X-Api-Key"
},
"description": "API key for authentication"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-fern-sdk-group-name": "agent",
"x-fern-sdk-method-name": "retry_run_webhook",
"x-fern-examples": [
{
"code-samples": [
{
"sdk": "python",
"code": "from skyvern import Skyvern\n\nskyvern = Skyvern(api_key=\"YOUR_API_KEY\")\nawait skyvern.agent.retry_run_webhook(run_id=\"tsk_v2_123\")\n"
}
]
}
]
}
},
"/v1/browser_sessions": {
"post": {
"tags": [
@@ -1823,6 +2096,176 @@
],
"title": "ActionBlockYAML"
},
"Artifact": {
"properties": {
"created_at": {
"type": "string",
"title": "Created At",
"description": "The creation datetime of the task.",
"examples": [
"2023-01-01T00:00:00Z"
]
},
"modified_at": {
"type": "string",
"title": "Modified At",
"description": "The modification datetime of the task.",
"examples": [
"2023-01-01T00:00:00Z"
]
},
"artifact_id": {
"type": "string",
"title": "Artifact Id"
},
"artifact_type": {
"$ref": "#/components/schemas/ArtifactType"
},
"uri": {
"type": "string",
"title": "Uri"
},
"task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Task Id"
},
"step_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Step Id"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Workflow Run Id"
},
"workflow_run_block_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Workflow Run Block Id"
},
"observer_cruise_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observer Cruise Id"
},
"observer_thought_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observer Thought Id"
},
"ai_suggestion_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ai Suggestion Id"
},
"signed_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signed Url"
},
"organization_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Organization Id"
}
},
"type": "object",
"required": [
"created_at",
"modified_at",
"artifact_id",
"artifact_type",
"uri"
],
"title": "Artifact"
},
"ArtifactType": {
"type": "string",
"enum": [
"recording",
"browser_console_log",
"skyvern_log",
"skyvern_log_raw",
"screenshot",
"screenshot_llm",
"screenshot_action",
"screenshot_final",
"llm_prompt",
"llm_request",
"llm_response",
"llm_response_parsed",
"llm_response_rendered",
"visible_elements_id_css_map",
"visible_elements_id_frame_map",
"visible_elements_tree",
"visible_elements_tree_trimmed",
"visible_elements_tree_in_prompt",
"hashed_href_map",
"visible_elements_id_xpath_map",
"html",
"html_scrape",
"html_action",
"trace",
"har"
],
"title": "ArtifactType"
},
"BitwardenCreditCardDataParameter": {
"properties": {
"parameter_type": {

2
fern/running-tasks/advanced-features.mdx
View File

@@ -3,7 +3,7 @@ title: Advanced Settings for tasks
subtitle: How to use advanced settings for tasks
slug: running-tasks/advanced-features
---
<Warning> DEPRECATION ALERT: the content in this page including endpoints mentioned here is being deprecated. Last supported date: Jan 1, 2026. If you're looking for TOTP (2FA/MFA) information, move to the new [TOTP](/credentials/totp) page.</Warning>
## Overriding the max_steps paramter in the task
If you want the task to execute for a specific number of steps, you can use the `x-max-steps-override` header in the request. This will override the default `max_steps` parameter set in the task.

8
fern/running-tasks/api-spec.mdx
View File

@@ -1,10 +1,14 @@
---
title: Tasks API
title: Legacy Task APIs
subtitle: The core building block in Skyvern
slug: running-tasks/api-spec
---
Tasks are the building block of Skyvern. They represent a single instruction (goal) to the browser to go do something using language models. Ex. "Go to alibaba and extract this information"
<Warning>
DEPRECATION ALERT: the APIs in this page are being deprecated. Last supported date: Jan 1, 2026. Please use the [Run Task](/running-tasks/run-tasks) API and migrated to the new API.
</Warning>
Tasks are the building block of Skyvern. They represent a single instruction (goal) to the browser to go do something using language models. Ex. "Search for Skyvern on googgle.com and summarize the information about Skyvern."
## Request - Initiate a task
Request type: `POST`

85
fern/running-tasks/run-tasks.mdx Normal file
View File

@@ -0,0 +1,85 @@
---
title: Task Features
slug: running-tasks/run-tasks
---
## Run A Task
- See the [Quickstart](/getting-started/quickstart) to run a simple task.
- See the [Run Task API and SDK](/api-reference/api-reference/agent/run-task).
There are many features to help automate and improve your task experience. Check out the features along with its parameter name below.
All the features are enabled through API & SDK. Some features are enabled through [Skyvern's Discover page](https://app.skyvern.com/discover) as well.
<Frame caption="Run Task UI">
<img src="../images/run_tasks/ui_run_task.png" alt="Configure advanced settings in the UI" width="400" />
</Frame>
### [Engine](/api-reference/api-reference/agent/run-task#request.body.engine)
Parameter: `engine`
This parameter defines the engine that powers the agent task.
- `skyvern-2.0`: this is the default engine. It's the latest Skyvern agent that performs really well with complex and multi-step tasks. It scores **state of the art** 85.85% on the [WebVoyager benchmark](https://blog.skyvern.com/skyvern-2-0-state-of-the-art-web-navigation-with-85-8-on-webvoyager-eval/).
- `skyvern-1.0`: performs really well for tasks with a simple goal, like filling a form, or searching for information on Google.
- `openai-cua`: uses OpenAI's CUA model.
- `anthropic-cua`: uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.
### [Data Extraction Schema](/api-reference/api-reference/agent/run-task#request.body.data_extraction_schema)
Parameter: `data_extraction_schema`
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/.
### [Send Webhook](/api-reference/api-reference/agent/run-task#request.body.webhook_url)
Parameter: `webhook_url`
You can set the `webhook_url` to receive the update when the task is done. Check [Webhooks FAQ](/running-tasks/webhooks-faq) for more details.
### [Max Steps](/api-reference/api-reference/agent/run-task#request.body.max_steps)
Parameter: `max_steps`
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.
### [Error Code Mapping](/api-reference/api-reference/agent/run-task#request.body.error_code_mapping)
Parameter: `error_code_mapping`
Custom mapping of error codes to error messages if Skyvern encounters an error.
For example:
```json
[
{"login_failed": "The login credentials are incorrect or the account is locked"},
{"maintenance_mode": "The website is down for maintenance"},
]
```
With this mapping, if Skyvern encounters a login failure, the task output will show `{"error": "login_failed"}`, which makes it easy to codify error handling.
### [Proxy Location](/api-reference/api-reference/agent/run-task#request.body.proxy_location)
Parameter: `proxy_location`
Some websites block requests from certain countries. You can set a proxy location to route the browser traffic through.
### TOTP (2FA/MFA/Verification) Code
- [totp_identifier](/api-reference/api-reference/agent/run-task#request.body.totp_identifier): Skyvern can receive the TOTP code and use this identifier to identify the code for authentication.
- [totp_url](/api-reference/api-reference/agent/run-task#request.body.totp_url): Skyvern makes a request to this URL to fetch the TOTP code when needed.
More details can be found in the [TOTP section](/credentials/totp).
### [Run Task in a Persistent Browser Session](/api-reference/api-reference/agent/run-task#request.body.browser_session_id) (`browser_session_id`)
You can set a browser session to use for the task. 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.
See the [Browser Sessions](/browser-sessions/introduction) section to see how to create a browser session.
## View A Task
Skyvern has a rich feature for you to understand what's happening with your task. See [Visualizing Results](/running-tasks/visualizing-results).
The [GET Run](/api-reference/api-reference/agent/get-run) endpoint shows the status of the task.
## Cancel A Task
A task that has not started or is in the running state can be cancelled through the UI. It can also be done with the [Cancel Run](/api-reference/api-reference/agent/cancel-run) endpoint.

44
fern/running-tasks/webhooks-faq.mdx
View File

@@ -3,12 +3,40 @@ title: Webhooks FAQ
subtitle: How Skyvern notifies you when its done
slug: running-tasks/webhooks-faq
---
# FAQ
## Webhooks vs HTTP requests?
We use Webhooks for executing tasks as the expected runtime of these jobs can exceed default HTTP timeouts (1 minute)
Expected runtime of Skyvern's tasks and workflows can exceed default HTTP timeouts (1 minute). So we recommend using receiving webhook notifications you when it's done.
To set up webhook callback:
- Set [webhook_url in Run Task](api-reference/api-reference/agent/run-task#request.body.webhook_url) to receive the update when the task is done.
- Set [webhook_url in Run Workflow](https://docs.skyvern.com/api-reference/api-reference/agent/run-workflow#request.body.webhook_url) to receive the update when a workflow run is done.
To fetch the status of a run:
- Use the [Get Run](/api-reference/api-reference/agent/get-run) endpoint for the status of a task or workflow run
## Webhook payload schema
The webhook request body is a JSON object with the following fields:
```json
{
"run_id": "The ID of the task or the workflow run. For examples: tsk_123, tsk_v2_123, wr_123",
"run_type": "The type of the run. Examples: task_v1, task_v2, workflow_run, openai_cua, anthropic_cua.",
"status": "The status of the run",
"output": "The output of the run",
"downloaded_files": "A list of download file objects",
"recording_url": "The URL of the recording",
"screenshot_urls": "URLs of the last three screenshots. The first one in the list is the latest screenshot.",
"failure_reason": "The reason for the failure if any",
"app_url": "The URL to the run in the Skyvern app",
"created_at": "The timestamp when the run was created",
"modified_at": "The timestamp when the run was last modified",
}
```
For detailed schema, please refer to the [Run Response](/api-reference/api-reference/agent/get-run#response).
Notes:
- The webhook payload won't contain the `run_request` field as the [Run Response](/api-reference/api-reference/agent/get-run#response) does.
- There are legacy fields in the actual payload for backward compatibility, which are not listed here and will be removed in the future. Please use the fields above.
## How do we handle webhook authentication? (ie how can we handle callbacks?)
@@ -40,10 +68,6 @@ function validateSkyvernRequestHeaders(req) {
</CodeGroup>
SKYVERN_API_KEY: this is the [api key](/running-tasks/introduction) specific to your organization
## Can I Replay Webhook?
# Webhook common parameters
| Parameter | Type | Required? | Sample Value | Description |
| --- | --- | --- | --- | --- |
| webhook_callback_url | String | yes | … | |
Yes, you can replay a webhook by using the [Retry Webhook](/api-reference/api-reference/agent/retry-webhook) endpoint.