---
name: Asteroid
description: Use when building, executing, and monitoring browser automation agents. Reach for this skill when agents need to automate web workflows, fill forms, extract data, handle multi-step processes, manage agent profiles and credentials, execute agents via API/SDK, or troubleshoot execution failures.
metadata:
    mintlify-proj: asteroid
    version: "1.0"
---

# Asteroid Skill

## Product Summary

Asteroid is a browser automation platform for building reliable, observable agents that execute complex web workflows. Agents are built as **graph workflows** — nodes (focused subtasks) connected by transitions (routing logic) — rather than monolithic scripts. Agents run in real browsers with proxy support, captcha solving, and persistent session management.

**Key files and concepts:**
- **Agent profiles**: Browser configuration, credentials, proxy settings, cookies, TOTP secrets
- **Graph workflows**: Nodes (AI Task, Output) + transitions (AI-driven, selector-based, outcome-based)
- **Execution**: Trigger via platform UI, SDK (TypeScript/Python), or API; monitor status and activities
- **Batch executions**: Run agents across CSV inputs with controlled concurrency and scheduling
- **Integrations**: Webhooks and Slack for real-time notifications

**Primary docs:** https://docs.asteroid.ai | **API reference:** https://odyssey.asteroid.ai/agents/v2/openapi.yaml

---

## When to Use

Reach for this skill when:

- **Building agents**: Creating new workflows, designing node structure, writing AI Task instructions, configuring transitions
- **Executing agents**: Triggering runs via API/SDK, passing inputs and profiles, polling execution status
- **Managing profiles**: Setting up credentials, proxy configuration, TOTP secrets, cookie persistence, profile pools
- **Batch operations**: Running agents across multiple CSV rows with scheduling and concurrency control
- **Monitoring & debugging**: Reviewing execution activities, understanding failures, sending messages to paused agents
- **Integrating**: Setting up webhooks or Slack notifications for execution events
- **Troubleshooting**: Diagnosing why agents fail, refining instructions, splitting complex nodes

---

## Quick Reference

### Core Concepts

| Concept | Purpose | Key Points |
|---------|---------|-----------|
| **AI Task Node** | Instruct LLM to interact with webpage | Uses natural language; supports dynamic variables `{{.var_name}}`; must have failure path |
| **Output Node** | End execution with outcome label + results | Terminal node; defines success/failure states |
| **AI Transition** | AI chooses next node based on page state | Flexible; used for semantic routing |
| **Selector Transition** | Jump when CSS selector appears | Deterministic; use sparingly for stable elements |
| **Agent Profile** | Browser config + credentials + proxy | Reusable across executions; includes vault secrets |
| **Profile Pool** | Group profiles for auto-selection | Rotates profiles (Least Recently Used or Most Recently Used) |
| **Batch Execution** | Run agent across CSV rows | Staggered scheduling; concurrency control |

### Essential API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /agents/{agentId}/execute` | Start an execution |
| `GET /executions/{executionId}` | Get execution status |
| `GET /executions/{executionId}/activities` | Retrieve execution activities |
| `POST /executions/{executionId}/messages` | Send message to paused agent |
| `PATCH /executions/{executionId}/status` | Pause/resume/cancel execution |
| `POST /agent-profiles` | Create agent profile |
| `GET /agent-profiles` | List profiles |

### SDK Setup

**TypeScript:**
```ts
import { client, agentExecutePost } from 'asteroid-odyssey';
client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});
```

**Python:**
```python
from asteroid_odyssey import Configuration, ApiClient
config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})
```

### Dynamic Variables in Instructions

```
Navigate to {{.portal_url}}
Enter {{.username}} and {{.password}}
Fill diagnosis: {{.diagnosis}}

{{if .is_premium}}
Enable premium features
{{else}}
Use free tier
{{end}}

{{range .items}}
- Add {{.}} to cart
{{end}}
```

---

## Decision Guidance

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

| Scenario | Use AI Transition | Use Selector Transition |
|----------|-------------------|------------------------|
| Route based on page content or extracted data | ✓ | |
| Wait for specific UI element to appear | | ✓ |
| Multiple possible paths; AI must choose | ✓ | |
| Deterministic, event-driven branching | | ✓ |
| Semantic understanding required | ✓ | |
| Element selector is stable and known | | ✓ |

**Rule:** Use Selector sparingly; prefer AI Transitions for flexibility.

### When to Use Profile vs. Profile Pool

| Scenario | Use Single Profile | Use Profile Pool |
|----------|-------------------|------------------|
| Single account, low concurrency | ✓ | |
| Multiple accounts, avoid conflicts | | ✓ |
| Distribute load across credentials | | ✓ |
| Keep sessions warm (Most Recently Used) | | ✓ |
| Rotate fairly (Least Recently Used) | | ✓ |
| High-throughput with concurrent use | | ✓ |

**Rule:** Use pools for production; single profiles for testing.

### When to Use Script vs. Agentic Node

| Scenario | Use Script | Use Agentic |
|----------|-----------|------------|
| Deterministic, stable interactions | ✓ | |
| Dynamic UI or variable page states | | ✓ |
| Speed critical (login, known flow) | ✓ | |
| Reasoning or semantic understanding needed | | ✓ |
| Fallback to AI on failure | ✓ | |
| No fallback; fail hard on error | ✓ | |

---

## Workflow

### Building an Agent

1. **Start simple**: Create a two-node agent (one AI Task, one Output) to validate the core task
2. **Write clear instructions**: Structure as Goal → Ordered Steps → Edge Cases → Success Criteria
3. **Define variables**: Use `{{.var_name}}` for dynamic inputs; validate naming (letters, numbers, underscores only)
4. **Add transitions**: Connect AI Task to Output via AI Transition; add failure path
5. **Test incrementally**: Run with sample data; review execution activities
6. **Refine**: Adjust instructions based on what you observe; split complex nodes if needed
7. **Add complexity**: Introduce more nodes only when you have grounded knowledge of the flow

### Executing an Agent

1. **Prepare profile**: Create or select agent profile with credentials, proxy, TOTP if needed
2. **Prepare inputs**: Gather values for all required variables
3. **Trigger execution**: Use platform UI, SDK, or API with `agentId`, `inputs`, `agentProfileId` (or `agentProfilePoolId`)
4. **Poll status**: Check execution status every 3-5 seconds until terminal state
5. **Handle result**: Extract output from `completed` state; log/alert on `failed` or `cancelled`

### Running a Batch

1. **Prepare CSV**: One row per execution; columns map to inputs, profile names, or metadata
2. **Upload & map**: Drag CSV to platform; auto-map columns; validate all required inputs are mapped
3. **Preview**: Review first 10 rows; fix any validation errors
4. **Configure**: Set batch name, workflow version, default profile, start time, concurrency, interval
5. **Monitor**: Track progress bar; use webhooks for real-time notifications on completion

### Debugging a Failed Execution

1. **Review status**: Check if `failed`, `paused`, or `paused_by_agent`
2. **Inspect activities**: View step-by-step actions, transitions, and agent reasoning
3. **Check browser snapshots**: See what the agent saw at each step
4. **Identify root cause**: Missing element? Wrong instruction? Unexpected page state?
5. **Refine**: Adjust instructions, add edge cases, or split node into smaller steps
6. **Retest**: Run again with same inputs; iterate until reliable

---

## Common Gotchas

- **Missing failure path**: Every AI Task node must have a transition to an Output node for failure scenarios. Without it, unexpected errors won't be handled gracefully.

- **Overly complex nodes**: If a node needs more than a paragraph of instructions, split it. Each node should represent one clear intention (e.g., "Fill driver info", not "Fill driver info, upload documents, and submit").

- **Selector transitions on unstable elements**: Selector transitions are deterministic but fragile. Only use them for elements you're 100% certain about. Prefer AI Transitions for flexibility.

- **Credentials in plain text**: Never paste secrets into instructions or scripts. Use vault placeholders (`##CREDENTIAL_NAME##`) or dynamic variables instead.

- **Profile deletion with active executions**: Deleting a profile breaks any executions that reference it. Ensure no active automations depend on it first.

- **Profile pool mutual exclusivity**: You must specify either `agentProfileId` OR `agentProfilePoolId`, never both. The API will reject requests with both fields.

- **Concurrent use conflicts**: If `allowConcurrentUse: false` and all profiles in a pool are busy, new execution requests fail immediately. Add more profiles or enable concurrent use.

- **Variable naming**: Variable names must start with a letter or underscore and contain only alphanumerics and underscores. `{{.user-name}}` and `{{.1st_item}}` are invalid.

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

- **Polling without timeout**: When polling execution status, implement timeout logic to avoid indefinite waiting. Set timeouts based on expected execution duration.

- **Script placeholders not resolved**: If a script uses `__PLACEHOLDER__` but the LLM can't resolve it, the script won't execute. Ensure placeholders are clearly defined in instructions or execution data.

---

## Verification Checklist

Before submitting an agent or execution:

- [ ] **Graph structure**: All AI Task nodes have failure paths to Output nodes
- [ ] **Instructions**: Clear goal, ordered steps, edge cases, success criteria
- [ ] **Variables**: All `{{.var_name}}` references are valid (letters/numbers/underscores only)
- [ ] **Transitions**: Each node has at least one outbound transition; no orphaned nodes
- [ ] **Credentials**: Secrets use vault placeholders (`##NAME##`), not plain text
- [ ] **Profile**: Selected profile has required credentials, proxy, TOTP if needed
- [ ] **Inputs**: All required workflow variables are provided at execution time
- [ ] **Test run**: Executed with sample data; reviewed activities and output
- [ ] **Batch CSV**: Header row present; all required columns mapped; preview validated
- [ ] **Batch config**: Concurrency and interval are conservative; start time is correct
- [ ] **Webhooks**: Configured for critical events (completion, failure) if needed

---

## Resources

**Comprehensive navigation:** https://docs.asteroid.ai/llms.txt

**Critical documentation:**
- [Graph Agents & Workflow Design](https://docs.asteroid.ai/fundamentals/graph-agents) — Core architecture and best practices
- [Agent Profiles & Credentials](https://docs.asteroid.ai/fundamentals/profiles) — Profile configuration, vault secrets, profile pools
- [Execution Statuses & Lifecycle](https://docs.asteroid.ai/fundamentals/execution-statuses) — Status machine, transitions, monitoring
- [API Quickstart](https://docs.asteroid.ai/api-reference/quickstart) — SDK setup and first execution
- [Batch Executions](https://docs.asteroid.ai/fundamentals/batch-executions) — CSV upload, scheduling, concurrency
- [AI Task Nodes](https://docs.asteroid.ai/fundamentals/nodes/ai-task) — Instructions, variables, capabilities, scripts
- [Transitions](https://docs.asteroid.ai/fundamentals/transitions) — AI, Selector, and Outcome transition types

---

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