mirror of
https://github.com/Skyvern-AI/skyvern.git
synced 2026-04-28 11:40:32 +00:00
docs: address Apr 26 feedback — URL parity, nav reorg, changelog backfill
- Move Developer-tab pages under /developers/* (getting-started/, features/, browser-automations/, credentials/, optimization/, going-to-production/, debugging/, self-hosted/) so URLs mirror Cloud's /cloud/* prefix; add wildcard redirects for the legacy paths and update existing legacy redirects to point at the new locations - Cloud UI nav: place Workflows above Tasks, promote Workflow Blocks to a top-level group, and add MCP under Integrations - Developers nav: also promote Workflow Blocks (actions-reference) to a top-level group - Rewrite cloud/getting-started/core-concepts as a UI tour (no code, dashboard screenshots) - Changelog: stable id anchors per Update so sidebar links work, and backfill v1.0.8–v1.0.14 plus v1.0.19/v1.0.20 from upstream release notes
This commit is contained in:
Ritik Sahni
Kunal Mishra
parent
56483c3be4
commit
5664f592bd
68 changed files with 850 additions and 290 deletions
|
|
@ -1,222 +0,0 @@
|
|||
---
|
||||
title: Using Artifacts
|
||||
subtitle: Access recordings, screenshots, logs, and network data for every run
|
||||
description: Retrieve and inspect artifacts from Skyvern runs including browser recordings, screenshots, AI reasoning logs, DOM element trees, network HAR files, and Playwright traces to debug failures and unexpected results.
|
||||
slug: debugging/using-artifacts
|
||||
keywords:
|
||||
- artifact
|
||||
- recording
|
||||
- screenshot
|
||||
- HAR file
|
||||
- Playwright trace
|
||||
- DOM tree
|
||||
- AI reasoning log
|
||||
- network data
|
||||
- generated code
|
||||
---
|
||||
|
||||
When a Skyvern run fails or produces unexpected results, artifacts are your debugging toolkit. Every run automatically captures what happened: recordings of the browser session, screenshots at each step, the AI's reasoning, and network traffic.
|
||||
|
||||
This page covers how to retrieve artifacts and what each type tells you.
|
||||
|
||||
<Tip>
|
||||
Looking for a specific artifact type? Jump to the [artifact types reference](#artifact-types-reference) to see all available types, then come back here to learn how to retrieve them.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Before you start
|
||||
|
||||
You need a `run_id` to retrieve artifacts. You get this when you [run a task](/running-automations/run-a-task) or workflow.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve artifacts
|
||||
|
||||
Use `get_run_artifacts` with the `run_id` from your task or workflow run:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
from skyvern import Skyvern
|
||||
|
||||
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
|
||||
|
||||
artifacts = await client.get_run_artifacts(run_id)
|
||||
|
||||
for artifact in artifacts:
|
||||
print(f"{artifact.artifact_type}: {artifact.signed_url}")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { SkyvernClient } from "@skyvern/client";
|
||||
|
||||
const client = new SkyvernClient({
|
||||
apiKey: process.env.SKYVERN_API_KEY,
|
||||
});
|
||||
|
||||
const artifacts = await client.getRunArtifacts(runId);
|
||||
|
||||
for (const artifact of artifacts) {
|
||||
console.log(`${artifact.artifact_type}: ${artifact.signed_url}`);
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
Signed URLs expire after 24 hours. If a URL has expired, call `get_run_artifacts` again to get fresh URLs. When running Skyvern locally, `signed_url` will be `null`. Access artifacts directly from your local file system instead.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Filter by artifact type
|
||||
|
||||
To get only specific artifact types, pass `artifact_type`:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
# Get only recordings and final screenshots
|
||||
artifacts = await client.get_run_artifacts(
|
||||
run_id,
|
||||
artifact_type=["recording", "screenshot_final"]
|
||||
)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const artifacts = await client.getRunArtifacts(runId, {
|
||||
artifact_type: ["recording", "screenshot_final"],
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts?artifact_type=recording&artifact_type=screenshot_final" \
|
||||
-H "x-api-key: $SKYVERN_API_KEY"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
---
|
||||
|
||||
## Artifact types reference
|
||||
|
||||
### Visual artifacts
|
||||
|
||||
These show you what the browser looked like at various points.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `recording` | Full video of the browser session (WebM) | Watch the entire run, see exactly what happened |
|
||||
| `screenshot` | Base screenshot capture | General page state capture |
|
||||
| `screenshot_final` | Screenshot when the run ended | Check the final state (did it end on the right page?) |
|
||||
| `screenshot_action` | Screenshot taken after each action | See the page state after each click, type, or navigation |
|
||||
| `screenshot_llm` | Screenshot sent to the LLM for decision-making | Understand what the AI "saw" when it made each decision |
|
||||
|
||||
**Debugging tip:** If the run failed, start with `screenshot_final` to see where it stopped, then watch the `recording` to see how it got there.
|
||||
|
||||
### AI reasoning artifacts
|
||||
|
||||
These show you why the AI made each decision.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `llm_prompt` | The prompt sent to the LLM | See exactly what instructions the AI received |
|
||||
| `llm_request` | Full request including context | Check if the right context was included |
|
||||
| `llm_response` | Raw LLM response | See the AI's unprocessed output |
|
||||
| `llm_response_parsed` | Parsed response (extracted actions) | Understand what actions the AI decided to take |
|
||||
| `llm_response_rendered` | Parsed response with real URLs | Debug URL targeting issues (see below) |
|
||||
|
||||
**Debugging tip:** If the AI did something unexpected, check `llm_prompt` to see if your prompt was interpreted correctly, then `llm_response_parsed` to see what action it extracted.
|
||||
|
||||
**About `llm_response_rendered`:** Skyvern hashes URLs before sending them to the LLM to reduce token usage and avoid confusing the model with long query strings. The `llm_response_parsed` artifact contains these hashed placeholders (like `{{_a1b2c3}}`), while `llm_response_rendered` shows the same response with actual URLs substituted back in. Use this when you need to verify which exact URL the AI targeted.
|
||||
|
||||
### Page structure artifacts
|
||||
|
||||
These show how Skyvern interpreted the page.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `visible_elements_tree` | DOM tree of visible elements (JSON) | See which elements Skyvern detected |
|
||||
| `visible_elements_tree_trimmed` | Trimmed tree (sent to LLM) | See what the AI could "see" |
|
||||
| `visible_elements_tree_in_prompt` | Element tree as plain text | Read exactly what was embedded in the prompt |
|
||||
| `visible_elements_id_css_map` | CSS selectors for each element | Debug element targeting issues |
|
||||
| `visible_elements_id_frame_map` | Element-to-iframe mapping | Debug elements inside iframes |
|
||||
| `visible_elements_id_xpath_map` | XPath selectors for each element | Alternative element targeting debug |
|
||||
| `hashed_href_map` | Mapping of hashed URLs to original URLs | Decode URL placeholders in LLM responses |
|
||||
| `html` | Generic HTML capture | Inspect page HTML |
|
||||
| `html_scrape` | Full HTML captured during scraping | Inspect the raw page structure |
|
||||
| `html_action` | HTML captured after an action | See how the page changed after each action |
|
||||
|
||||
**Debugging tip:** If the AI couldn't find an element, check `visible_elements_tree` to see if it was detected. If not, the element might be in an iframe, dynamically loaded, or outside the viewport.
|
||||
|
||||
**About the element tree variants:** The `visible_elements_tree` is a JSON structure, while `visible_elements_tree_in_prompt` is the plain-text representation that gets embedded directly into the LLM prompt. The latter is often easier to read when debugging prompt issues. If you're debugging iframe-related problems, `visible_elements_id_frame_map` shows which frame contains each element ID.
|
||||
|
||||
### Log artifacts
|
||||
|
||||
These contain structured execution data.
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `skyvern_log` | Formatted execution logs | Read through the run step-by-step |
|
||||
| `skyvern_log_raw` | Raw JSON logs | Parse programmatically for automation |
|
||||
| `browser_console_log` | Browser console output | Debug JavaScript errors on the page |
|
||||
|
||||
**Debugging tip:** `skyvern_log` is human-readable and shows the flow of execution. Start here for an overview before diving into specific artifacts.
|
||||
|
||||
### Network artifacts
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `har` | HTTP Archive (network requests/responses) | Debug API calls, check for failed requests, see response data |
|
||||
| `trace` | Playwright trace file | Replay the session in Playwright Trace Viewer |
|
||||
|
||||
**Debugging tip:** The HAR file captures every network request. If a form submission failed, check the HAR to see if the request was sent and what the server responded.
|
||||
|
||||
### File artifacts
|
||||
|
||||
| Type | What it contains | Use this to |
|
||||
|------|------------------|-------------|
|
||||
| `script_file` | Generated Playwright scripts | See the code Skyvern would use to repeat this task |
|
||||
|
||||
---
|
||||
|
||||
## Artifact response fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `artifact_id` | string | Unique identifier |
|
||||
| `artifact_type` | string | Type (see tables above) |
|
||||
| `uri` | string | Internal storage path |
|
||||
| `signed_url` | string \| null | Pre-signed URL for downloading |
|
||||
| `task_id` | string \| null | Associated task ID |
|
||||
| `step_id` | string \| null | Associated step ID |
|
||||
| `run_id` | string \| null | Run ID (e.g., `tsk_v2_...`, `wr_...`) |
|
||||
| `workflow_run_id` | string \| null | Workflow run ID |
|
||||
| `workflow_run_block_id` | string \| null | Workflow block ID |
|
||||
| `organization_id` | string | Your organization |
|
||||
| `created_at` | datetime | When created |
|
||||
| `modified_at` | datetime | When modified |
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Troubleshooting Guide"
|
||||
icon="wrench"
|
||||
href="/debugging/troubleshooting-guide"
|
||||
>
|
||||
Common issues and how to fix them
|
||||
</Card>
|
||||
<Card
|
||||
title="Error Handling"
|
||||
icon="triangle-exclamation"
|
||||
href="/going-to-production/error-handling"
|
||||
>
|
||||
Map errors to custom codes for programmatic handling
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Loading…
Add table
Add a link
Reference in a new issue