---
name: Asteroid
description: Use when building, executing, and monitoring browser automation agents that perform complex multi-step workflows like form filling, data extraction, document processing, and operational automation. Reach for this skill when you need to create agents via the platform, execute them programmatically via SDK/API, configure profiles and credentials, manage batch executions, or integrate with webhooks.
metadata:
    mintlify-proj: asteroid
    version: "1.0"
---

# Asteroid Skill Reference

## Product Summary

Asteroid is a browser automation platform that executes complex, multi-step workflows with reliability and observability. Agents are built as **graph workflows** — nodes (focused subtasks) connected by transitions (routing logic) — rather than monolithic scripts. Use the platform at https://platform.asteroid.ai to design agents visually, or use the TypeScript/Python SDKs to execute them programmatically. Key files: agent definitions live in the platform; execution state is tracked via API. CLI: use `npm install asteroid-odyssey` (TypeScript) or `pip install asteroid-odyssey` (Python). Primary docs: https://docs.asteroid.ai.

---

## When to Use

Reach for this skill when:

- **Building agents**: Creating new browser automation workflows in the platform UI or via YAML/API
- **Executing agents**: Running agents programmatically from your backend using SDKs or REST API
- **Managing profiles**: Setting up agent profiles with proxy settings, credentials, cookies, or TOTP secrets
- **Batch processing**: Running the same agent across many inputs (CSV rows) with controlled concurrency
- **Monitoring executions**: Polling execution status, retrieving results, or setting up webhooks for real-time events
- **Debugging failures**: Reviewing execution timelines, browser snapshots, and agent reasoning to understand what went wrong
- **Integrating with external systems**: Connecting agents to webhooks, Slack, or other services

Do not use this skill for: general web scraping libraries, headless browser control (Playwright/Puppeteer directly), or non-browser automation tasks.

---

## Quick Reference

### Essential Commands & Setup

| Task | Command/Code |
|------|--------------|
| **Install SDK** | `npm install asteroid-odyssey` (TS) or `pip install asteroid-odyssey` (Python) |
| **Set API key** | `export ASTEROID_API_KEY="ast..."` |
| **Configure client** | `client.setConfig({ headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY } })` |
| **Execute agent** | `agentExecutePost({ path: { agentId }, body: { inputs: {...} } })` |
| **Poll execution** | `executionGet({ path: { executionId } })` — check `status` field |
| **List executions** | `executionsList({ query: { page, pageSize } })` |
| **Create profile** | `agentProfilesCreate({ body: { name, proxyCountryCode, ... } })` |
| **Upload files** | `tempFilesStage()` before execution, or `executionContextFilesUpload()` during |

### Node Types

| Node Type | Purpose | Transition Types |
|-----------|---------|------------------|
| **AI Task** | LLM-driven browser interaction (click, type, extract, navigate) | `ai`, `selector` |
| **Output** | End execution, return result label + structured data | `outcome_success` |

### Execution Statuses

| Status | Meaning | Terminal? |
|--------|---------|-----------|
| `starting` | Initializing | No |
| `running` | Actively executing | No |
| `paused` | User paused | No |
| `awaiting_confirmation` | Waiting for human approval | No |
| `completed` | Finished successfully | **Yes** |
| `failed` | Error occurred | **Yes** |
| `cancelled` | User cancelled | **Yes** |

### AI Capabilities (Tools)

Enable on AI Task nodes as needed:

- **Web Browsing**: `go_to_url`, `dom_browser_interaction` (required), `refresh_page`
- **Advanced**: `extract_html`, `get_text`, `evaluate_javascript`, `take_screenshot`, `solve_captcha`
- **Vision**: `computer_use` (image-based interaction)
- **Communication**: `send_user_message`, `send_mail`, `get_mail`, `send_api_request`
- **Files**: `list_files`, `read_files`, `upload_file`
- **Memory**: `write_scratchpad`, `read_scratchpad`, `read_clipboard`
- **Auth**: `generate_totp_secret`
- **Context**: `query_context`, `get_datetime`

---

## Decision Guidance

### When to Use AI Transition vs. Selector Transition

| Scenario | Use AI Transition | Use Selector Transition |
|----------|-------------------|------------------------|
| Next step depends on page content or extracted data | ✓ | |
| Waiting for a specific UI element to appear | | ✓ |
| Multiple possible paths based on reasoning | ✓ | |
| Deterministic, event-driven branching | | ✓ |
| Dynamic or unpredictable UI | ✓ | |
| Stable, known element selectors | | ✓ |

**Rule**: Use AI transitions by default. Use selector transitions only when you are 100% certain about element stability.

### When to Use Default vs. Scripted Execution Mode

| Scenario | Default Mode | Scripted Mode |
|----------|--------------|---------------|
| Still exploring/discovering the flow | ✓ | |
| UI path is stable and repeatable | | ✓ |
| Need maximum flexibility | ✓ | |
| Need maximum speed | | ✓ |
| Handling dynamic or variable UIs | ✓ | |
| Have stored Playwright scripts | | ✓ |

**Rule**: Start with default mode. Move to scripted mode once the path is proven and stable.

### When to Use Profile vs. Profile Pool

| Scenario | Single Profile | Profile Pool |
|----------|----------------|--------------|
| One credential/account | ✓ | |
| Multiple accounts to rotate | | ✓ |
| Avoiding concurrent use conflicts | | ✓ |
| Distributing load across accounts | | ✓ |
| Keeping sessions warm | | ✓ (with "Most Recently Used") |
| Simple, single-user automation | ✓ | |

**Rule**: Use pools for any multi-account or high-concurrency scenario.

---

## Workflow

### Building and Executing an Agent

1. **Create the agent** in the platform (https://platform.asteroid.ai):
   - Write a clear goal and step-by-step instructions
   - Declare dynamic variables with `{{.var_name}}` syntax
   - The platform auto-creates a two-node graph (AI Task + Output)

2. **Refine in the Graph Builder**:
   - Break complex tasks into smaller nodes (one paragraph per node)
   - Add transitions between nodes (AI or selector)
   - Ensure every AI Task node has a failure path to an Output node
   - Name nodes and variables descriptively

3. **Create an Agent Profile**:
   - Set proxy country, type, and persistent IP if needed
   - Add credentials to the vault (use `##CREDENTIAL_NAME##` placeholders)
   - Enable captcha solver if required
   - Configure cache persistence (default: enabled)

4. **Execute the agent**:
   - Via platform: Click "Run Agent", select profile, provide inputs
   - Via SDK: Call `agentExecutePost()` with agent ID, inputs, and profile ID
   - Via API: POST to `/agents/{agentId}/execute`

5. **Monitor execution**:
   - Watch real-time browser interaction in the platform
   - Poll `executionGet()` or use webhooks for status updates
   - Review execution timeline, snapshots, and reasoning on completion

6. **Iterate on failures**:
   - Check execution logs for where the agent got stuck
   - Refine instructions (be more specific, add edge cases)
   - Split complex nodes into smaller, focused ones
   - Test with different variable values

### Running a Batch

1. **Prepare CSV**: Each row = one execution. Columns = inputs, profile names, metadata.
2. **Upload & map**: Drag CSV into platform, map columns to input variables.
3. **Preview**: Validate first 10 rows for errors.
4. **Configure**: Set batch name, concurrency, interval, start time.
5. **Monitor**: Track progress bar; pause/resume/cancel as needed.

### Setting Up Webhooks

1. **Create integration**: Platform → Integrations → Webhook. Provide URL and optional headers.
2. **Attach to agent**: Select event types (e.g., `EXECUTION_COMPLETED`, `EXECUTION_FAILED`).
3. **Verify signatures**: Validate `X-Asteroid-Signature` header using RSA SHA-256 before processing.
4. **Handle at-least-once**: Deduplicate using stable execution fields, not just `event_id`.

---

## Common Gotchas

- **Missing failure paths**: Every AI Task node must have a transition to an Output node for failure cases. Without it, the workflow may not handle errors properly.

- **Disabling Basic Web Interaction**: Never disable the `dom_browser_interaction` tool on AI Task nodes. It is required for the agent to interact with the browser.

- **Overly long node instructions**: If a node needs more than a paragraph of instructions, split it into multiple nodes. Long instructions reduce reliability.

- **Hardcoding secrets**: Never paste raw passwords or API keys into instructions or scripts. Use vault placeholders (`##CREDENTIAL_NAME##`) or variable mechanisms instead.

- **Selector transitions on unstable UIs**: Selector transitions break silently if the target element changes. Use only when the selector is guaranteed stable.

- **Profile deletion with active executions**: Deleting a profile affects any running executions that reference it. Always check for active automations first.

- **Persistent IP limitations**: Persistent IPs only work with US proxies and do not support mobile proxies or captcha solving.

- **Batch concurrency too high**: Running too many concurrent executions can overwhelm target systems or trigger rate limits. Start conservative (5-10) and increase gradually.

- **Forgetting to map required inputs**: Batch column mapping must include all required workflow input variables. Validation will catch this, but double-check before running large batches.

- **Not testing with small batches first**: Always test with 5-10 rows before running large batches to verify column mappings and agent behavior.

- **Webhook signature verification skipped**: Verify signatures against the raw request body (not parsed JSON) using RSA PKCS#1 v1.5 with SHA-256. Skipping this is a security risk.

- **Assuming event_id is unique across retries**: `event_id` is generated per notification payload and can change on redelivery. Use stable execution fields for deduplication.

---

## Verification Checklist

Before submitting work with Asteroid agents:

- [ ] **Graph structure**: All AI Task nodes have failure paths to Output nodes
- [ ] **Node instructions**: Each node has clear goal, ordered steps, edge cases, and success criteria
- [ ] **Variables**: All dynamic variables use `{{.var_name}}` syntax and are declared in the agent
- [ ] **Transitions**: Transitions are appropriate (AI for semantic decisions, selector for deterministic UI events)
- [ ] **Profile configured**: Agent profile has correct proxy, credentials, and cache settings
- [ ] **Credentials secured**: All secrets use vault placeholders, not plain text
- [ ] **Tested with small inputs**: Ran at least one execution with test data before batch processing
- [ ] **Batch mappings verified**: CSV columns correctly map to input variables and profile names
- [ ] **Webhook signatures validated**: Signature verification is enabled and tested
- [ ] **Error handling**: Execution failures are logged and monitored (via polling or webhooks)
- [ ] **Concurrency appropriate**: Batch concurrency and interval respect target system rate limits

---

## Resources

- **Full documentation**: https://docs.asteroid.ai/llms.txt (comprehensive page-by-page navigation for agents)
- **Platform**: https://platform.asteroid.ai (build and run agents)
- **API Reference**: https://docs.asteroid.ai/api-reference (endpoint schemas and examples)
- **Graph Agents Guide**: https://docs.asteroid.ai/fundamentals/graph-agents (core concepts and design patterns)
- **AI Task Node Reference**: https://docs.asteroid.ai/fundamentals/nodes/ai-task (instructions, templating, capabilities)
- **SDKs**: TypeScript (https://docs.asteroid.ai/sdks/typescript) and Python (https://docs.asteroid.ai/sdks/python)

---

> For additional documentation and navigation, see: https://docs.asteroid.ai/llms.txt