doc update - add run tasks page (#2425)
This commit is contained in:
Shuchang Zheng
@@ -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.
|
||||
|
||||
@@ -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
85
fern/running-tasks/run-tasks.mdx
Normal 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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user