mirror of
https://github.com/Skyvern-AI/skyvern.git
synced 2025-04-23 16:09:08 +00:00
add missing docs for task v2 api (#2096)
This commit is contained in:
Shuchang Zheng
GitHub
parent
1150cf19b2
commit
b0b4862c2a
4 changed files with 181 additions and 13 deletions
docs/workflows
fern
|
|
@ -159,10 +159,10 @@ Supported integrations:
|
|||
- block_type: file_upload
|
||||
label: upload_downloaded_files_to_s3
|
||||
storage_type: s3
|
||||
aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
|
||||
aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
|
||||
s3_bucket: YOUR_S3_BUCKET
|
||||
region_name: us-east-1
|
||||
aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
|
||||
aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
|
||||
s3_bucket: YOUR_S3_BUCKET
|
||||
region_name: us-east-1
|
||||
```
|
||||
|
||||
### How to set up FileUploadBlock with AWS
|
||||
|
|
|
|||
|
|
@ -35,6 +35,8 @@ navigation:
|
|||
path: running-tasks/introduction.mdx
|
||||
- page: Tasks API
|
||||
path: running-tasks/api-spec.mdx
|
||||
- page: Tasks V2 API
|
||||
path: running-tasks/api-v2-spec.mdx
|
||||
- api: Endpoints
|
||||
paginated: true
|
||||
snippets:
|
||||
|
|
|
|||
133
fern/running-tasks/api-v2-spec.mdx
Normal file
133
fern/running-tasks/api-v2-spec.mdx
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
---
|
||||
title: Tasks API V2
|
||||
description: 'Powered by the latest version of Skyvern agent, with better reasoning and validation. State of the art web navigation with 85.8% on WebVoyager Eval.'
|
||||
---
|
||||
|
||||
## Request - Initiate a task
|
||||
Request type: `POST`
|
||||
|
||||
Production:`https://api.skyvern.com/api/v2/tasks/`
|
||||
|
||||
### Header
|
||||
|
||||
| Parameter | Type | Required? | Sample Value | Description |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| x-api-key | String | yes | [your-api-key-here] | Bearer token that gives your backend access to the Skyvern API. This will be manually provided by us |
|
||||
| x-max-iterations-override | Integer | no | 10 | The max number of iterations skyvern attempts to divide and conquer a complicated task. In each iteration, Skyvern does a "mini task" planning, mini task execution and validation. The default is 10. |
|
||||
| x-max-steps-override | Integer | no | 25 | The max number of steps skyvern can take. The default is 25. |
|
||||
|
||||
### Body
|
||||
|
||||
| Parameter | Type | Required? | Sample Value | Description |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| user_prompt | String | yes | Find a route between Chicago to Los Angeles on google maps, then print the route details. |
|
||||
| url | HttpUrl | no | https://www.google.com/maps/ | If you want to use a specific url, you can pass it here. It's optional since you can also tell skyvern which site to go to in the user_prompt. |
|
||||
| webhook_callback_url | HttpUrl | no | https://mywebsite.com/webhook | The callback URL once our system is finished processing this async task |
|
||||
| proxy_location | String | no | RESIDENTIAL | Proxy location for the web-browsing request. Please pass RESIDENTIAL as a value |
|
||||
| totp_verification_url | HttpUrl | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint. If this field is provided, Skyvern will call the url to fetch the TOTP/2FA/MFA code when needed |
|
||||
| totp_identifier | String | no | myemail@example.com / 4155558888 | The email address or the phone number which receives the TOTP/2FA/MFA code. If this field is provided, Skyvern will fetch the code that is pushed to [Skyvern's TOTP API](https://docs.skyvern.com/running-tasks/advanced-features#push-code-to-skyvern) |
|
||||
| extracted_information_schema | JSON object, list, string | no | `{"type": "object", "properties": {"title": {"type": "string", "descripption": "The title of the post"}, "url": {"type": "string", "description": "The url link to the post"}}}` | Use jsonschema to define the schema of the output. You can also describe the schema but it won't be as reliable as defining it in the jsonschema format |
|
||||
|
||||
## Example Request (Apply for a job)
|
||||
|
||||
```python
|
||||
POST https://api.skyvern.com/api/v2/tasks/
|
||||
|
||||
{
|
||||
"user_prompt": "Find a route between Chicago to Los Angeles on google maps, then print the route details.",
|
||||
"proxy_location": "RESIDENTIAL"
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
Each task has an associated `task_id` -- a unique identifier you can use to look up information about any task.
|
||||
|
||||
| Parameter | Type | Always returned? | Sample Value | Description |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| task_id | String | yes | t_123456 | The task id associated with this specific task |
|
||||
| status | String | yes | created | The status of the task |
|
||||
| prompt | String | yes | Find a route between Chicago to Los Angeles on google maps, then print the route details. |
|
||||
| url | HttpUrl | yes | https://www.google.com/maps/ | The url that skyvern starts browsing with |
|
||||
| organization_id | String | yes | o_123456 | The organization id associated with this task |
|
||||
| workflow_id | String | yes | wf_123456 | The workflow id created by this task |
|
||||
| workflow_run_id | String | yes | wr_123456 | The ID of the workflow run |
|
||||
| workflow_permanent_id | String | yes | wpid_123456 | The workflow permanent id |
|
||||
| summary | String | no | The user has successfully found routes between Chicago and Los Angeles on Google Maps. The extracted details include travel modes, travel times, distances, route descriptions, and additional information for each route. | The summary of what skyvern did. |
|
||||
| output | Object | no | `{ "routes": [{"travel_mode": "Driving", "travel_time": "30 hr", "distance": "2,015 miles", "route_description": "via I-80 W", "additional_info": ["28 hr without traffic", "This route has tolls", "Your destination is in a different time zone"]}] }` | The output of the task. This is the structured data that skyvern extracted from the website. |
|
||||
| webhook_callback_url | HttpUrl | no | https://mywebsite.com/webhook | The url of your webhook endpoint if sent to execute the task. |
|
||||
| totp_verification_url | HttpUrl | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint if sent to execute the task. |
|
||||
| totp_identifier | String | no | myemail@example.com / 4155558888 | The totp_identifier sent to execute the task.|
|
||||
| proxy_location | String | no | RESIDENTIAL | The proxy location used to execute the task. |
|
||||
| created_at | Timestamp | yes | 2022-11-22T22:55:55 | The timestamp when the task was created. |
|
||||
| modified_at | Timestamp | yes | 2022-11-22T22:55:55 | The timestamp when the task was last updated. |
|
||||
|
||||
|
||||
## Response Webhook - Task conclusion (POST)
|
||||
If a `webhook_callback_url` is specified within your task request, Skyvern will make a callback to your system letting you know that it has either finished, terminated or failed a task execution.
|
||||
|
||||
The following headers can be used to validate it's an authentic Skyvern request.
|
||||
|
||||
### Headers
|
||||
|
||||
| Parameter | Type | Required? | Sample Value | Description |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| x-skyvern-signature | String | yes | v0=a2114d57b48eac39b9ad189<br/>dd8316235a7b4a8d21a10bd275<br/>19666489c69b503 | Authentication token that allows our service to communicate with your backend service via callback / webhook <br/>We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |
|
||||
| x-skyvern-timestamp | String | yes | 1531420618 | Timestamp used to decode and validate the incoming webhook call<br/><br/>We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |
|
||||
|
||||
### Body
|
||||
These parameters are sent in the body of the request to `webhook_callback_url`.
|
||||
|
||||
Here's an example of the webhook body:
|
||||
```
|
||||
{
|
||||
"task_id": "oc_347318612592634222",
|
||||
"status": "completed",
|
||||
"organization_id": "o_123456",
|
||||
"workflow_run_id": "wr_123456",
|
||||
"workflow_id": "w_123456",
|
||||
"workflow_permanent_id": "wpid_123456",
|
||||
"prompt": "Find a route between Chicago to Los Angeles on google maps, then print the route details.",
|
||||
"url": "https://www.google.com/maps/",
|
||||
"summary": "The user has successfully found routes between Chicago and Los Angeles on Google Maps. The extracted details include travel modes, travel times, distances, route descriptions, and additional information for each route.",
|
||||
"output": {
|
||||
"routes": [
|
||||
{
|
||||
"travel_mode": "Driving",
|
||||
"travel_time": "30 hr",
|
||||
"distance": "2,015 miles",
|
||||
"route_description": "via I-80 W",
|
||||
"additional_info": [
|
||||
"28 hr without traffic",
|
||||
"This route has tolls.",
|
||||
"Your destination is in a different time zone."
|
||||
]
|
||||
},
|
||||
{
|
||||
"travel_mode": "Driving",
|
||||
"travel_time": "30 hr",
|
||||
"distance": "2,028 miles",
|
||||
"route_description": "via I-80 W and I-70 W",
|
||||
"additional_info": [
|
||||
"28 hr without traffic"
|
||||
]
|
||||
},
|
||||
{
|
||||
"travel_mode": "Flights",
|
||||
"travel_time": "4 hr 30 min",
|
||||
"distance": null,
|
||||
"route_description": "Chicago, IL—Los Angeles, CA",
|
||||
"additional_info": [
|
||||
"from $150"
|
||||
]
|
||||
}
|
||||
],
|
||||
"extraction_datetime": "2025-01-10T22:56:20.297774Z"
|
||||
},
|
||||
"totp_verification_url": null,
|
||||
"totp_identifier": null,
|
||||
"proxy_location": null,
|
||||
"webhook_callback_url": null,
|
||||
"created_at": "2025-01-10T22:53:36.297774Z",
|
||||
"modified_at": "2025-01-10T22:56:29.582779Z"
|
||||
}
|
||||
```
|
||||
|
|
@ -1,11 +1,9 @@
|
|||
---
|
||||
title: Workflow Blocks
|
||||
subtitle: Individual Blocks within Skyvern
|
||||
slug: workflows/workflow-blocks
|
||||
description: 'Individual Blocks within Skyvern'
|
||||
---
|
||||
|
||||
|
||||
|
||||
## TaskBlock
|
||||
|
||||
The magic block. Skyvern navigates through the websites to take actions and/or extract information.
|
||||
|
|
@ -151,18 +149,53 @@ Inputs:
|
|||
1. **Prompt *(required):*** Write a natural language prompt to be sent to the LLM to generate a text response
|
||||
2. **JSON Schema *(optional):*** Craft a JSON input that structures the LLM output for use in another programming task
|
||||
|
||||
## DownloadToS3Block / UploadToS3Block
|
||||
## FileUploadBlock
|
||||
|
||||
Persists files inside S3
|
||||
Persists files inside custom destinations.
|
||||
Supported integrations:
|
||||
- AWS S3
|
||||
|
||||
```
|
||||
- block_type: upload_to_s3
|
||||
- block_type: file_upload
|
||||
label: upload_downloaded_files_to_s3
|
||||
path: SKYVERN_DOWNLOAD_DIRECTORY
|
||||
storage_type: s3
|
||||
aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
|
||||
aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
|
||||
s3_bucket: YOUR_S3_BUCKET
|
||||
region_name: us-east-1
|
||||
```
|
||||
|
||||
### How to set up FileUploadBlock with AWS
|
||||
- Step 1. Create your bucket. (let’s say `YOUR-BUCKET-NAME` is the name)
|
||||
- Step 2. Create a limited IAM policy that only has GetObject and PutObject permissions to this s3 bucket, named `skyvern-s3-access-policy` (any name works):
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SkyvernS3Access",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:PutObject",
|
||||
"s3:GetObject"
|
||||
],
|
||||
"Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
- Step 3. Create an AWS IAM user for skyvern
|
||||
- Go to https://us-east-1.console.aws.amazon.com/iam/home
|
||||
- click "Create User" → do not check "Provide user access to the AWS Management Console" → input user name → click "Next"
|
||||
- At the the "Set Permissions" page, click "Attach policies directly" → pick the `skyvern-s3-access-policy` created in the previous step → click "Next" → click "Create user"
|
||||
- After the user is created, go to the new IAM user page → go to the "Security credentials" tab → click "create access key" → on the "Access key best practices & alternatives" page, click "Application running on an AWS compute service" → click "Next" → click "Create access key" → you will see the "Access Key" and the "Secret access key" at the end of user creation.
|
||||
- Step 4. Create a FileUploadBlock
|
||||
- Place this block after the file download has completed.
|
||||
- Copy the "Access Key" to the "AWS Access Key ID" field of the File Upload Block and "Secret access key".
|
||||
- Copy the "Access Key" to the "AWS Secret Access Key" field in the File Upload Block.
|
||||
- Add your s3 bucket name.
|
||||
- Add your AWS region.
|
||||
|
||||
* Since we’re in beta, this feature is unavailable right now, [contact us](https://meetings.hubspot.com/skyvern/demo?uuid=7c83865f-1a92-4c44-9e52-1ba0dbc04f7a) if you would like to use it.
|
||||
|
||||
## SendEmailBlock
|
||||
|
||||
|
|
@ -206,4 +239,4 @@ Downloads and parses a file to be used within other workflow blocks.
|
|||
Inputs:
|
||||
|
||||
1. **File URL *(required):*** This block allows you to use a CSV within your workflow.
|
||||
* Since we’re still in beta, you will need to [contact us](https://meetings.hubspot.com/skyvern/demo?uuid=7c83865f-1a92-4c44-9e52-1ba0dbc04f7a) to load a value into this block
|
||||
* Since we’re still in beta, you will need to [contact us](https://meetings.hubspot.com/skyvern/demo?uuid=7c83865f-1a92-4c44-9e52-1ba0dbc04f7a) to load a value into this block
|
||||
Loading…
Add table
Reference in a new issue