# Add Profiles to Pool
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/add-profiles-to-pool

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agent-profile-pools/{poolId}/members
Add profiles to a pool



# Create Agent Profile Pool
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/create-agent-profile-pool

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agent-profile-pools
Create a new agent profile pool



# Delete Agent Profile Pool
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/delete-agent-profile-pool

https://odyssey.asteroid.ai/agents/v2/openapi.yaml delete /agent-profile-pools/{poolId}
Delete an agent profile pool



# Get Agent Profile Pool
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/get-agent-profile-pool

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profile-pools/{poolId}
Get an agent profile pool by ID



# List Agent Profile Pools
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/list-agent-profile-pools

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profile-pools
List all agent profile pools for an organization



# List Pool Members
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/list-pool-members

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profile-pools/{poolId}/members
List all profiles in a pool



# Remove Profiles from Pool
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/remove-profiles-from-pool

https://odyssey.asteroid.ai/agents/v2/openapi.yaml delete /agent-profile-pools/{poolId}/members
Remove profiles from a pool



# Update Agent Profile Pool
Source: https://docs.asteroid.ai/api-reference/agent-profile-pools/update-agent-profile-pool

https://odyssey.asteroid.ai/agents/v2/openapi.yaml patch /agent-profile-pools/{poolId}
Update an existing agent profile pool



# Clear Browser Cache
Source: https://docs.asteroid.ai/api-reference/agent-profiles/clear-browser-cache

https://odyssey.asteroid.ai/agents/v2/openapi.yaml delete /agent-profiles/{profileId}/clear-browser-cache
Clears the browser profile/cache for the specified agent profile by deleting its browser profile



# Create Agent Profile
Source: https://docs.asteroid.ai/api-reference/agent-profiles/create-agent-profile

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agent-profiles
Create a new agent profile



# Delete Agent Profile
Source: https://docs.asteroid.ai/api-reference/agent-profiles/delete-agent-profile

https://odyssey.asteroid.ai/agents/v2/openapi.yaml delete /agent-profiles/{profileId}
Delete an agent profile



# Duplicate Agent Profile
Source: https://docs.asteroid.ai/api-reference/agent-profiles/duplicate-agent-profile

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agent-profiles/{profileId}/duplicate
Duplicate an agent profile with all settings, credentials, and cookies



# Get Agent Profile
Source: https://docs.asteroid.ai/api-reference/agent-profiles/get-agent-profile

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profiles/{profileId}
Get an agent profile by ID



# Get Agent Profile Inbox Email
Source: https://docs.asteroid.ai/api-reference/agent-profiles/get-agent-profile-inbox-email

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profiles/{profileId}/inbox-emails/{emailId}
Get a single email from the agent profile's inbox by ID



# Get Agent Profile Inbox Emails
Source: https://docs.asteroid.ai/api-reference/agent-profiles/get-agent-profile-inbox-emails

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profiles/{profileId}/inbox-emails
List emails in the agent profile's inbox



# List Agent Profiles
Source: https://docs.asteroid.ai/api-reference/agent-profiles/list-agent-profiles

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agent-profiles
List all agent profiles for an organization



# Update Agent Profile
Source: https://docs.asteroid.ai/api-reference/agent-profiles/update-agent-profile

https://odyssey.asteroid.ai/agents/v2/openapi.yaml patch /agent-profiles/{profileId}
Update an existing agent profile



# Execute an agent
Source: https://docs.asteroid.ai/api-reference/agents/execute-an-agent

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agents/{agentId}/execute
Start an execution for the given agent.



# List Agents
Source: https://docs.asteroid.ai/api-reference/agents/list-agents

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agents
List all agents for an organization



# List Available Tools
Source: https://docs.asteroid.ai/api-reference/agents/list-available-tools

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agents/available-tools
List all available tools/capabilities for AI Task nodes in workflows



# Get Context
Source: https://docs.asteroid.ai/api-reference/context/get-context

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /context
Get the current user's context including organization memberships



# Get execution
Source: https://docs.asteroid.ai/api-reference/execution/get-execution

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /executions/{executionId}
Get a single execution by ID with all details



# Get recording redirect
Source: https://docs.asteroid.ai/api-reference/execution/get-recording-redirect

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /executions/{executionId}/recording
Redirect to the recording playback URL. Returns a 307 with a short-lived signed URL. Embed this endpoint in <video> tags — the player will follow the redirect and re-fetch on expiry.



# List executions
Source: https://docs.asteroid.ai/api-reference/execution/list-executions

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /executions
List executions with filtering and pagination



# Retrieve execution activities
Source: https://docs.asteroid.ai/api-reference/execution/retrieve-execution-activities

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /executions/{executionId}/activities
Get activities for an execution



# Send user message to execution
Source: https://docs.asteroid.ai/api-reference/execution/send-user-message-to-execution

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /executions/{executionId}/user-messages
Add a user message to an execution



# Update execution status
Source: https://docs.asteroid.ai/api-reference/execution/update-execution-status

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /executions/{executionId}/status
Update the status of an execution. Use this to pause, resume, or cancel an execution.



# Delete Agent Shared File
Source: https://docs.asteroid.ai/api-reference/files/delete-agent-shared-file

https://odyssey.asteroid.ai/agents/v2/openapi.yaml delete /agents/{agentId}/shared-files/{fileId}
Delete a file from the agent's persistent shared storage.



# Delete All Agent Shared Files
Source: https://docs.asteroid.ai/api-reference/files/delete-all-agent-shared-files

https://odyssey.asteroid.ai/agents/v2/openapi.yaml delete /agents/{agentId}/shared-files/delete-all
Delete all shared files for an agent.



# Download execution file
Source: https://docs.asteroid.ai/api-reference/files/download-execution-file

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /executions/{executionId}/files/{fileId}/download
Redirects to a short-lived signed URL for downloading the file.



# Download shared file
Source: https://docs.asteroid.ai/api-reference/files/download-shared-file

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agents/{agentId}/shared-files/{fileId}/download
Redirects to a short-lived signed URL for downloading the file.



# Get Agent Shared Files
Source: https://docs.asteroid.ai/api-reference/files/get-agent-shared-files

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agents/{agentId}/shared-files
Get all persistent shared files for an agent. These files persist across executions and are automatically restored when a new execution starts.



# Get Execution Files
Source: https://docs.asteroid.ai/api-reference/files/get-execution-files

https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /executions/{executionId}/files
Get all files for an execution, grouped by directory. Files are tracked by the file syncer daemon during execution.



# Set Freeze on Agent Shared File
Source: https://docs.asteroid.ai/api-reference/files/set-freeze-on-agent-shared-file

https://odyssey.asteroid.ai/agents/v2/openapi.yaml patch /agents/{agentId}/shared-files/{fileId}/freeze
Set the frozen status of a shared file. Frozen files are preserved across executions and cannot be overwritten by the agent.



# Stage a file for an execution
Source: https://docs.asteroid.ai/api-reference/files/stage-a-file-for-an-execution

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /temp-files/{organizationId}
Stage a file prior to starting an execution, so that it can be used when the execution is started. See the /agents/{agentId}/execute to understand how to pass the returned file information to the execution endpoint.



# Update Agent Shared File
Source: https://docs.asteroid.ai/api-reference/files/update-agent-shared-file

https://odyssey.asteroid.ai/agents/v2/openapi.yaml put /agents/{agentId}/shared-files/{fileId}
Replace the contents of a shared file. The request body must contain exactly one file.



# Upload Agent Shared Files
Source: https://docs.asteroid.ai/api-reference/files/upload-agent-shared-files

https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agents/{agentId}/shared-files
Upload one or more files to the agent's persistent shared storage. Files are available across all executions.



# API Quickstart
Source: https://docs.asteroid.ai/api-reference/quickstart

Get started with the Asteroid API and SDKs

Use this page as the starting point for programmatic access to Asteroid.

<Steps>
  <Step title="Sign up for Asteroid">
    Follow the instructions here to sign up for the Asteroid platform: [Asteroid signup](https://platform.asteroid.ai/) using your Google account.
  </Step>

  <Step title="Get your API key">
    Once you have signed up, you can retrieve your API key from the [API keys page](https://platform.asteroid.ai/keys).

    <img alt="Get your API key" />
  </Step>

  <Step title="Set your environment variable">
    Our examples use `ASTEROID_API_KEY` as a convenient environment variable. Set it once and read it from your own code:

    ```bash theme={null}
      export ASTEROID_API_KEY="your-key-here"
    ```
  </Step>

  <Step title="Choose how you want to integrate">
    Pick the starting point that matches your workflow:

    * [TypeScript SDK](/sdks/typescript) for the high-level helper client and generated namespaces
    * [Python SDK](/sdks/python) for the high-level client and generated subpackages
    * [API](/api-reference) for the main API landing page and common workflows

    The reference pages in this section are the best place to inspect individual request and response schemas.
  </Step>

  <Step title="Run your first execution">
    Use one of the SDK guides above, or start from the minimal examples below.

    <CodeGroup>
      ```ts TypeScript theme={null}
      import { client, agentExecutePost, executionGet } from 'asteroid-odyssey';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: { customerName: 'Jane Doe' },
        },
      });
      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      let exec;
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'starting');

      console.log(exec?.status);
      ```

      ```python Python theme={null}
      import os
      import time
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.execution_api import ExecutionApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          exec_api = ExecutionApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={"customerName": "Jane Doe"},
              ),
          )
          execution_id = response.execution_id

          while True:
              time.sleep(3)
              execution = exec_api.execution_get(execution_id=execution_id)
              if execution.status not in ("running", "starting"):
                  break

          print(execution.status)
      ```
    </CodeGroup>
  </Step>
</Steps>

## Next Steps

Once you've set up your environment, you can:

1. Inspect the endpoint reference pages in this API section for request and response details
2. Follow the [TypeScript SDK](/sdks/typescript) or [Python SDK](/sdks/python) guides for end-to-end examples
3. Review [Agent Profiles](/fundamentals/profiles) if you need persistent browser state, credentials, or proxies

Need help? Contact us at [founders@asteroid.ai](mailto:founders@asteroid.ai)


# Webhook Notification Payload
Source: https://docs.asteroid.ai/api-reference/webhook-notification-payload

https://odyssey.asteroid.ai/webhooks/openapi.json post /webhooks/example
Example endpoint to expose the webhook notification schema. This operation is for documentation purposes only.



# Best Practices
Source: https://docs.asteroid.ai/astro/best-practices

Tips for getting the most out of Astro

## Mentioning Executions

You can reference specific executions in your conversations with Astro using the `@` symbol. A quick menu will pop up showing your recent executions, making it easy to pick the right one. This is useful when you want Astro to analyze what happened during a particular run.

<Card title="Mentioning Executions" icon="at">
  When you type `@` in the chat input, a menu appears showing your recent executions. Simply select the one you want Astro to analyze.
</Card>

The more context you give Astro, the better it can help you. When asking for improvements or building agents:

* **Describe your goal**: Explain what you're trying to achieve
* **Share examples**: If relevant, mention specific executions or scenarios
* **Be specific**: Ask targeted questions rather than very general ones

## Iterative Improvement

Astro works best when you iterate:

<Steps>
  <Step title="Ask for help">
    Start with a question or request
  </Step>

  <Step title="Review suggestions">
    Look at what Astro proposes
  </Step>

  <Step title="Provide feedback">
    Accept, reject, or ask for modifications
  </Step>

  <Step title="Refine">
    Continue the conversation to fine-tune the results
  </Step>
</Steps>

## Tips for Better Results

* **Be specific**: Instead of "make it better," ask "how can I make the form filling more reliable?"
* **Provide context**: Mention specific nodes, executions, or issues you're facing
* **Iterate**: Don't expect perfect results on the first try—refine through conversation
* **Review changes carefully**: Always review workflow changes before accepting them
* **Test after changes**: Run your agent after making changes to verify improvements

***

## Examples

<Tabs>
  <Tab title="Building an Agent from Scratch">
    <Callout icon="user">
      I need to automate filling out a contact form on example.com. The form has name, email, and message fields.
    </Callout>

    <Callout icon="robot">
      *Analyzes request and suggests workflow structure*
    </Callout>

    <Callout icon="user">
      That looks good, but I also need to handle the captcha.
    </Callout>

    <Callout icon="robot">
      *Suggests creating an agent profile with captcha solvers enabled*
    </Callout>
  </Tab>

  <Tab title="Improving Existing Prompts">
    <Callout icon="user">
      Improve my prompts
    </Callout>

    <Callout icon="robot">
      *Reviews all node prompts and suggests improvements*
    </Callout>

    <Callout icon="user">
      I like the suggestions for the login node, but keep the original prompt for the data extraction node.
    </Callout>

    <Callout icon="robot">
      *Updates only the login node prompt*
    </Callout>
  </Tab>

  <Tab title="Debugging an Execution">
    <Callout icon="user">
      Why did this execution fail? `@execution-456`
    </Callout>

    <Callout icon="robot">
      *Analyzes execution logs and identifies the issue*
    </Callout>

    <Callout icon="user">
      How can I fix that?
    </Callout>

    <Callout icon="robot">
      *Suggests specific changes to prevent the failure*
    </Callout>
  </Tab>
</Tabs>


# Getting Started
Source: https://docs.asteroid.ai/astro/getting-started

Learn how to access and start using Astro

<Check>
  Use Astro in the [Asteroid platform](https://platform.asteroid.ai/). Go there first to build and run agents, then open Astro from the Create, Builder, or Execution pages.
</Check>

**Astro** is an AI assistant that helps you build, understand, and improve your Asteroid agents through natural language conversations. With deep expertise in Asteroid agent architecture, best practices, and design patterns, Astro can help you build more reliable, maintainable browser automations.

Whether you're building a new agent, optimizing an existing one, or troubleshooting issues encountered during executions, Astro is there to help.

<CardGroup>
  <Card title="Build" icon="wand-magic-sparkles">
    Create new agents using natural language or documents like PDFs
  </Card>

  <Card title="Optimize" icon="arrow-trend-up">
    Get suggestions for making your agents more reliable and robust
  </Card>

  <Card title="Understand" icon="brain">
    Learn what your agent does and how it operates on the web
  </Card>

  <Card title="Debug" icon="bug">
    Examine execution results and understand what happened
  </Card>
</CardGroup>

## Accessing Astro

Astro is available in different places depending on what you want to do.

<Card title="Creating a new agent" icon="plus">
  Start typing in the chatbox on the **Create** page
</Card>

<Card title="Working with an existing agent" icon="keyboard">
  Click the Astro button in the top left of the **Builder** or **Execution** pages
</Card>

Once Astro opens, you'll see a conversation interface with message history and a chat input where you can ask questions or give instructions.

At the top, you'll see several quick-start prompts:

* **"What can you help me with?"** - Learn about Astro's capabilities
* **"What does my agent do?"** - Get an explanation of your current agent
* **"Improve my prompts"** - Get suggestions for better prompts
* **"Examine an execution"** - Analyze a specific execution (use @ to mention executions)
* **"Build agent from PDF"** - Create an agent from a PDF document

You can click any of these to start, or simply type your own question in the chat input.


# How It Works
Source: https://docs.asteroid.ai/astro/how-it-works

Learn more about how Astro works

Here's how a typical interaction with Astro works.

<Steps>
  <Step title="Ask Astro to help">
    You describe what you want to accomplish, whether that's building a new agent, improving an existing one, or fixing an issue.
  </Step>

  <Step title="Astro analyzes and makes changes">
    Astro reads your agent's current state and can:

    * Read, edit, delete, and rename nodes
    * Modify node instructions and configurations
    * Tweak agent settings
    * Add or remove transitions between nodes
  </Step>

  <Step title="Review and approve changes">
    After Astro makes changes, you'll see a diff viewer showing exactly what was modified. You can review all proposed changes side-by-side, accept them to apply to your agent, or reject them and provide feedback for Astro to try again.

    <Card title="Review Changes" icon="eye">
      The diff viewer shows you exactly what Astro changed, with before and after views side-by-side. You can see modifications to node instructions, configurations, and workflow structure.
    </Card>

    <Card title="Accept or Reject" icon="check-circle">
      Once you've reviewed the changes, you can accept them to apply to your agent, or reject them and provide feedback for Astro to try a different approach.
    </Card>
  </Step>
</Steps>

This workflow ensures you maintain full control over your agent while benefiting from Astro's expertise and suggestions.

## Conversation Management

You can have multiple conversations with Astro for the same agent. Each conversation maintains its own history, making it easy to:

* Work on different aspects of your agent in separate conversations
* Keep track of different topics or improvements
* Share specific conversations with team members

All your conversations with Astro are saved. You can:

* **View history**: Access past conversations from the conversation selector
* **Resume conversations**: Pick up where you left off
* **Delete conversations**: Remove conversations you no longer need

### Operating Context

Each conversation with Astro is tied to a specific agent. When working with an agent, there are two important modes to understand:

**Edit Mode**

* Agents must be in **Edit mode** for Astro to make changes
* When you modify your agent, or accept Astro's changes, these are automatically saved as a draft
* You can iterate and refine your agent without affecting the published version

**Publishing and Running**

* An agent must be **Published** before it can be run
* When you run an agent, it uses the last published version, not the draft
* This means you can continue editing and improving your agent without disrupting running executions

This ensures:

<CardGroup>
  <Card title="Safe experimentation" icon="flask">
    Make changes in drafts without affecting production agents
  </Card>

  <Card title="Version control" icon="split">
    Keep a stable published version while iterating on improvements
  </Card>

  <Card title="No disruption" icon="shield-check">
    Running agents continue using the published version even as you edit
  </Card>

  <Card title="Confidence" icon="check">
    Test and review changes thoroughly before publishing
  </Card>
</CardGroup>


# AI Capabilities
Source: https://docs.asteroid.ai/fundamentals/ai-capabilities

Available capabilities for your AI Task nodes

AI Task nodes can be equipped with a wide range of capabilities.
Each capability unlocks additional tools the agent can use during execution. We suggest starting with the default capabilities, and enabling additional ones when strictly needed.

<Tip>
  **API Tool Identifiers** — When configuring AI Task node `tools` via the API or MCP server, use the snake\_case identifiers listed below each tool. You can also call the `listAvailableTools` MCP tool or `GET /agents/available-tools` API endpoint to discover all available tools programmatically.
</Tip>

***

## Web Browsing Essentials

Core tools for basic navigation and DOM interaction.

<Card title="Go to URL" icon="globe">
  Navigate the browser to any URL (`go_to_url`)
</Card>

<Card title="Refresh Page" icon="arrow-rotate-right">
  Reload the current webpage (`refresh_page`)
</Card>

<Card title="Basic Web Interaction" icon="mouse-pointer">
  Click, type, select elements, and interact via the DOM (`dom_browser_interaction`)
</Card>

<Warning>
  **Critical: Basic Web Interaction is Required**

  **Basic Web Interaction is enabled by default and should always remain enabled for AI Task nodes.** This capability provides essential tools for clicking, typing, selecting elements, and interacting with the DOM.

  * Disabling Basic Web Interaction will prevent AI Task nodes from performing basic browser interactions
  * You should not disable this capability unless you have a very specific reason
  * This capability is part of the default "Web Browsing Essentials" set and is required for AI Task nodes to function properly
</Warning>

***

## Advanced Web Browsing Toolkit

Tools for extraction, evaluation, and page manipulation

<Card title="Extract HTML" icon="code">
  Download or inspect the full HTML of the page (`extract_html`)
</Card>

<Card title="Get Text" icon="text">
  Extract visible text as clean markdown (`get_text`)
</Card>

<Card title="Evaluate JavaScript" icon="code">
  Run custom JS in the page context (`evaluate_javascript`)
</Card>

<Card title="Zoom Out" icon="magnifying-glass-minus">
  Reduce zoom level to view more content (`zoom_out`)
</Card>

<Card title="Zoom In" icon="magnifying-glass-plus">
  Increase zoom level for readability (`zoom_in`)
</Card>

<Card title="Take Screenshot" icon="camera">
  Take a screenshot of the current page (`take_screenshot`)
</Card>

<Card title="Solve Captcha" icon="puzzle-piece">
  Trigger automatic captcha solving (`solve_captcha`)
</Card>

<Card title="Save PDF" icon="file-pdf">
  Save the current page as a PDF file (`save_pdf`)
</Card>

***

## Computer Vision

Tools for image-based interaction when DOM access is insufficient.

<Card title="Computer Vision" icon="eye">
  Click, locate, and interact using visual recognition (`computer_use`)
</Card>

***

## Communication

Send messages or work with email during execution.

<Card title="Send User Message" icon="message">
  Ask the user questions or request clarification (`send_user_message`)
</Card>

<Card title="Send Mail" icon="envelope">
  Send emails with custom subject and body (`send_mail`)
</Card>

<Card title="Get Mail" icon="inbox">
  Retrieve inbound emails from the agent’s inbox (`get_mail`)
</Card>

<Card title="Send API Request" icon="server">
  Make HTTP API requests to external services (`send_api_request`)
</Card>

<Info>
  `send_mail` and `get_mail` require an agent profile to be attached to the execution — the inbox address is derived from the profile. See [Agent Emails](/fundamentals/emails) for the full setup and a prompt pattern for receiving email verification codes.
</Info>

***

## File System

Work with files locally or inside the browser session.

<Card title="List Files" icon="folder-open">
  View all files available in the execution context (`list_files`)
</Card>

<Card title="Read Files" icon="file-lines">
  Read text, images, PDFs, or downloaded files (`read_files`)
</Card>

<Card title="Upload File" icon="upload">
  Upload files to file input elements on a webpage (`upload_file`)
</Card>

***

## Memory & Storage

Store and retrieve execution-scoped data.

<Card title="Write Scratchpad" icon="pen-to-square">
  Save notes or structured data to memory (`write_scratchpad`)
</Card>

<Card title="Read Scratchpad" icon="book-open">
  Retrieve previously stored information (`read_scratchpad`)
</Card>

<Card title="Read Clipboard" icon="clipboard">
  Access the current clipboard contents (`read_clipboard`)
</Card>

***

## Google Sheets

Read and write spreadsheet data.

<Card title="Sheets: Get Data" icon="table">
  Retrieve values from cell ranges like A1:B10 (`google_sheets_get_data`)
</Card>

<Card title="Sheets: Set Value" icon="table">
  Update values in specific cells (`google_sheets_set_value`)
</Card>

***

## Authentication

Generate tokens and handle one-time passwords.

<Card title="Generate TOTP Code" icon="shield">
  Produce 6-digit MFA codes using stored credentials (`generate_totp_secret`)
</Card>

***

## Context & Utilities

Access deeper execution context or system utilities.

<Card title="Query Context" icon="search">
  Ask questions about past actions and stored information (`query_context`)
</Card>

<Card title="Get Datetime" icon="clock">
  Fetch the current datetime in any timezone (`get_datetime`)
</Card>


# Batch Executions
Source: https://docs.asteroid.ai/fundamentals/batch-executions

Run your agent across multiple inputs in bulk with controlled scheduling and concurrency

Batch executions allow you to run an agent many times with different inputs in a single operation. Instead of triggering executions one-by-one, you upload a CSV of inputs, configure scheduling parameters, and let the platform handle the rest.

<CardGroup>
  <Card title="Bulk Input" icon="file-csv">
    Upload a CSV to define inputs for each execution
  </Card>

  <Card title="Controlled Scheduling" icon="clock">
    Stagger executions with configurable concurrency and intervals
  </Card>

  <Card title="Lifecycle Management" icon="list-check">
    Pause, resume, or cancel an entire batch at once
  </Card>

  <Card title="Progress Tracking" icon="chart-simple">
    Monitor how many executions have been triggered, are pending, or cancelled
  </Card>
</CardGroup>

***

## How It Works

A **batch** is a container that groups multiple **scheduled executions** together. When you create a batch, you provide:

1. A **CSV file** where each row defines the inputs for a single execution
2. A **batch configuration** that controls when and how fast executions are triggered

The platform creates one scheduled execution per CSV row and staggers them over time according to your configuration. Each scheduled execution is triggered automatically when its scheduled time arrives, creating an actual agent execution.

```mermaid theme={null}
graph LR
    CSV[CSV Upload] --> Mapping[Column Mapping]
    Mapping --> Config[Batch Configuration]
    Config --> Batch[Batch Created]
    Batch --> SE1[Scheduled Execution 1]
    Batch --> SE2[Scheduled Execution 2]
    Batch --> SE3[Scheduled Execution N...]
    SE1 --> E1[Execution 1]
    SE2 --> E2[Execution 2]
    SE3 --> E3[Execution N...]
```

***

## Creating a Batch

Creating a batch is a guided process in the platform, broken into four steps.

<Steps>
  <Step title="Upload CSV">
    Upload a CSV file containing your execution data. Each row represents one execution, and each column contains data that will be mapped to agent inputs, profiles, or metadata.

    The CSV must include a header row. The platform parses it client-side using [Papa Parse](https://www.papaparse.com/) and validates that the file has consistent column counts.

    <Info>
      You can drag and drop a CSV file or click to browse. The platform accepts standard comma-separated CSV files.
    </Info>
  </Step>

  <Step title="Map Columns">
    Map each CSV column to one of the following field types:

    | Mapping Type           | Description                                                 |
    | ---------------------- | ----------------------------------------------------------- |
    | **Input Variable**     | Maps to one of the agent workflow's defined input variables |
    | **Agent Profile Name** | Overrides the default agent profile for that row            |
    | **Metadata**           | Attaches arbitrary key-value metadata to the execution      |
    | **Skip**               | Ignores the column entirely                                 |

    The platform auto-maps columns where the CSV header matches an input variable name (case-insensitive, with whitespace normalized to underscores). You can adjust mappings manually.

    <Tip>
      Column mappings are saved to your browser per agent. When you upload a new CSV with the same structure, your previous mappings are automatically restored.
    </Tip>

    **Validation rules:**

    * All required workflow input variables must be mapped
    * No duplicate mappings to the same field
    * At least one column must be mapped (not skipped)
    * Metadata fields must have names specified
  </Step>

  <Step title="Preview & Validate">
    Review a preview of the first 10 rows showing how your data maps to each field. Each row is validated and shows a status indicator:

    * Valid rows are ready for execution
    * Invalid rows display error tooltips explaining the issue

    Fix any issues in your CSV and re-upload if needed before proceeding.
  </Step>

  <Step title="Configure Batch">
    Set the batch execution parameters:

    | Parameter                 | Description                                                 |
    | ------------------------- | ----------------------------------------------------------- |
    | **Batch Name**            | A descriptive name to identify this batch                   |
    | **Workflow Version**      | Which version of the agent workflow to execute              |
    | **Default Agent Profile** | The profile to use for rows that don't specify one          |
    | **Start Time**            | When to begin triggering executions                         |
    | **Max Concurrent**        | Number of executions to trigger per batch interval          |
    | **Batch Interval**        | Seconds to wait between each group of concurrent executions |

    <Info>
      If the start time is in the past or now, the batch begins immediately with a `running` status. If the start time is in the future, the batch is created with a `pending` status and will start automatically at the specified time.
    </Info>
  </Step>
</Steps>

***

## Time-Based Batching

The scheduling system uses **time-based batching** to stagger execution start times and avoid overwhelming target systems or hitting rate limits.

The formula is:

```
For each item at index i:
  batchIndex = floor(i / maxConcurrent)
  executeAt  = startAt + (batchIndex * batchInterval seconds)
```

### Example

With `maxConcurrent = 5` and `batchInterval = 60` seconds:

| Items      | Execute At              |
| ---------- | ----------------------- |
| Rows 0-4   | `startAt` (immediately) |
| Rows 5-9   | `startAt + 60s`         |
| Rows 10-14 | `startAt + 120s`        |
| Rows 15-19 | `startAt + 180s`        |

This means 5 executions are triggered every 60 seconds until all rows have been processed.

<Tip>
  Choose your concurrency and interval settings based on the target system's rate limits and your agent's resource requirements. Start conservative and increase if needed.
</Tip>

***

## Batch Lifecycle

Batches follow a strict state machine that controls how scheduled executions are processed.

### Batch Statuses

```mermaid theme={null}
graph TB
    pending[Pending]
    running[Running]
    paused[Paused]
    completed[Completed]
    cancelled[Cancelled]

    pending --> running
    pending --> cancelled
    running --> paused
    running --> completed
    running --> cancelled
    paused --> running
    paused --> cancelled

    style completed fill:#dcfce7
    style cancelled fill:#fef3c7
    style running fill:#dbeafe
    style pending fill:#e0e7ff
    style paused fill:#fde68a
```

| Status        | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| **Pending**   | Batch is created with a future start time. Waiting for the start time to arrive. |
| **Running**   | Actively triggering scheduled executions according to the batch interval.        |
| **Paused**    | User paused the batch. No new executions are triggered until resumed.            |
| **Completed** | All scheduled executions in the batch have been triggered.                       |
| **Cancelled** | Batch was cancelled. Remaining pending executions will not be triggered.         |

### Scheduled Execution Statuses

Each item within a batch has its own status:

| Status        | Description                                      |
| ------------- | ------------------------------------------------ |
| **Pending**   | Waiting for its scheduled execute time to arrive |
| **Triggered** | The execution has been created and started       |
| **Cancelled** | This specific scheduled execution was cancelled  |

***

## Managing Batches

Once created, you can manage batches from the **Batch** tab on the agent page.

### Viewing Batches

The batch list shows all batches for the agent with:

* Name and current status
* Progress bar showing triggered vs. total executions
* Created and started timestamps
* Action buttons for lifecycle management

### Pause

Pausing a batch stops new executions from being triggered. Executions that have already been triggered continue running. Use pause when you need to temporarily halt a batch without losing progress.

### Resume

Resuming a paused batch recalculates the execution schedule from the current time and continues triggering remaining pending executions.

### Cancel

Cancelling a batch permanently stops it. Pending scheduled executions are cancelled and will not be triggered. Executions already in progress are not affected.

<Warning>
  Cancelling a batch is irreversible. Already-triggered executions will continue running, but no new executions will start.
</Warning>

### Viewing Scheduled Executions

Click **View Scheduled Executions** on a batch card to see all individual scheduled executions. From here you can:

* See the status of each scheduled execution
* View when each execution is scheduled to run
* Cancel or reschedule individual executions

***

## Progress Tracking

Each batch tracks aggregate statistics across its scheduled executions:

| Metric        | Description                                       |
| ------------- | ------------------------------------------------- |
| **Total**     | Total number of scheduled executions in the batch |
| **Pending**   | Executions waiting to be triggered                |
| **Triggered** | Executions that have been started                 |
| **Cancelled** | Executions that were cancelled                    |

The progress bar on each batch card shows `triggered / total` as a percentage, giving you an at-a-glance view of batch completion.

***

## Best Practices

### 1. Start with Small Batches

Test your configuration with a small CSV (5-10 rows) before running large batches. This lets you verify column mappings, input formatting, and agent behavior.

### 2. Use Conservative Concurrency

Start with low `maxConcurrent` values and increase gradually. Running too many concurrent executions can overwhelm target systems or trigger rate limiting.

### 3. Leverage Saved Mappings

If you regularly run batches with the same CSV structure, your column mappings are saved automatically per agent. This speeds up repeat batch creation.

### 4. Combine with Profile Pools

For large batches, use [Profile Pools](/fundamentals/profiles#profile-pools) to automatically rotate agent profiles across executions. This distributes load across credentials and avoids concurrent use conflicts.

### 5. Monitor with Webhooks

For large batches, set up [webhooks](/fundamentals/integrations/webhooks) to receive real-time notifications as individual executions complete, fail, or require attention. This is more efficient than polling the batch status.

***

## Related Resources

<CardGroup>
  <Card title="Execution Statuses" icon="circle-info" href="/fundamentals/execution-statuses">
    Understand individual execution lifecycle states
  </Card>

  <Card title="Agent Profiles" icon="browser" href="/fundamentals/profiles">
    Configure profiles and profile pools for batch executions
  </Card>

  <Card title="Webhooks" icon="webhook" href="/fundamentals/integrations/webhooks">
    Set up real-time notifications for execution events
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    View batch execution API endpoints
  </Card>
</CardGroup>


# Agent Emails
Source: https://docs.asteroid.ai/fundamentals/emails

Give your agent a real inbox so it can send and receive email — useful for login codes, email-based 2FA, and email-driven workflows

Every agent profile in Asteroid is automatically provisioned with its own email inbox. Agents can read and send mail from this inbox during a run, which makes it easy to handle flows that depend on email — for example, retrieving a one-time login code, confirming a sign-up link, or replying to a counterpart.

<CardGroup>
  <Card title="Per-profile inbox" icon="envelope">
    Each agent profile gets its own address at `agentmail.asteroid.ai`
  </Card>

  <Card title="Custom prefix" icon="pen">
    Override the default to use a friendly address like `acme-ops@agentmail.asteroid.ai`
  </Card>

  <Card title="Send & receive" icon="paper-plane">
    Enable the `send_mail` and `get_mail` tools on AI Task nodes
  </Card>

  <Card title="Email 2FA" icon="shield">
    Receive TOTP / login codes and feed them back into your workflow
  </Card>
</CardGroup>

## How the inbox is assigned

The inbox address is derived from the **agent profile** attached to the execution. The format is:

```
{prefix}@agentmail.asteroid.ai
```

By default the **prefix is the agent profile's UUID**, so a freshly created profile gets an address like:

```
9e2d8a14-3b1f-4e2c-9ab5-0c5f17d2c111@agentmail.asteroid.ai
```

You can override this by setting a custom **Inbox Email Prefix** on the profile (via the dashboard, API, or SDK). For example, setting the prefix to `acme-support` resolves to:

```
acme-support@agentmail.asteroid.ai
```

<Info>
  The prefix is normalised (lowercased and trimmed) and must be unique across the platform. If the prefix is already taken, profile creation/update will fail — pick a different one.
</Info>

<Warning>
  Inbox addresses are scoped to the agent profile, not the execution. Two executions that use the same profile (or two profiles in the same [profile pool](/fundamentals/profiles#profile-pools)) share an inbox. For strict isolation, give each agent its own profile.
</Warning>

## Requirements

To use email in an agent, two things have to be in place:

<Steps>
  <Step title="An agent profile is attached to the execution">
    Email is a profile-bound feature. Executions without an agent profile (or pool) have no inbox, and the `send_mail` / `get_mail` tools will fail.

    See [Agent Profiles](/fundamentals/profiles) for how to create one and how to attach it to an execution via the dashboard, API, or SDK.
  </Step>

  <Step title="Email tools are enabled on the node">
    On every AI Task node that needs to send or read mail, enable the email tools under the **Communication** capability in the node settings:

    * `send_mail` — send an email from the profile's inbox
    * `get_mail` — list recent emails, or fetch a specific email by ID

    You can enable these in the graph editor (the **AI Capabilities** panel on the node) or, when configuring nodes programmatically, by listing them in the node's `tools` array. See [AI Capabilities → Communication](/fundamentals/ai-capabilities#communication).
  </Step>
</Steps>

## Configuring the prefix

<Tabs>
  <Tab title="Dashboard">
    1. Open **Agent Profiles** on the Asteroid platform.
    2. Create a new profile, or open an existing one.
    3. Set the **Inbox Email Prefix** field (e.g. `acme-support`).
    4. Save. The full address is shown alongside the field.
  </Tab>

  <Tab title="API / SDK">
    Pass `inboxEmailPrefix` when creating or updating the profile.

    See [Create an agent profile](/api-reference/endpoints/agent-profiles/create-agent-profile) and [Update an agent profile](/api-reference/endpoints/agent-profiles/update-agent-profile).

    If you omit the field, the prefix defaults to the profile's UUID.
  </Tab>
</Tabs>

## Using email from an AI Task node

Once the tools are enabled and a profile is attached, the agent can call them like any other tool. The agent doesn't need to be told its own address — it's resolved automatically from the profile at runtime.

### Sending an email

The agent can send an email by calling `send_mail`. Typical instruction:

```
After you have generated the report, email a copy to {{.recipient}}:
- Subject: "Daily report for {{.account_name}}"
- Body: a short plain-text summary plus a link to the run

Use the send_mail tool. The "from" address is your inbox — you do not need to set it.
```

### Reading an email

The agent can list recent messages or fetch one by ID with `get_mail`. The tool only returns mail addressed to the profile's own inbox.

## Receiving email codes (TOTP / login)

The most common use case for the inbox is **catching one-time codes** sent by email — for example, a login flow that emails a 6-digit verification code, or a magic-link sign-in.

The pattern is:

<Steps>
  <Step title="Submit the email address on the target site">
    Instruct the agent to enter the profile's inbox address (e.g. `acme-support@agentmail.asteroid.ai`) into the sign-in form. You can pass the address in as a dynamic variable, or have the agent read it from the prompt.
  </Step>

  <Step title="Wait for the email to arrive">
    Email delivery takes a few seconds. Tell the agent to **poll its inbox** rather than calling `get_mail` once — codes can arrive 5–30 seconds after the request.
  </Step>

  <Step title="Extract the code and submit it">
    Once the email is in the inbox, the agent extracts the code from the body and enters it into the verification field.
  </Step>
</Steps>

### Example prompt

```
Goal: Log into the {{.product_name}} dashboard. The site will email a 6-digit code to our inbox.

Steps:
1. Navigate to {{.login_url}}.
2. Enter the email address {{.agent_email}} into the email field and submit.
3. Wait for the verification email to arrive. It will be sent from "no-reply@{{.product_domain}}" with a 6-digit code in the body.
   - Call get_mail to list recent emails.
   - If the verification email is not present yet, wait ~10 seconds and call get_mail again.
   - Retry up to 6 times (about a minute total) before giving up.
4. Once the email arrives, call get_mail with its email_id to fetch the full body.
5. Extract the 6-digit code from the body and enter it into the verification input on the page.
6. Click "Verify" and confirm you reach the dashboard.

Edge cases:
- If no email arrives after 6 polls, fail the task with a clear error message.
- Ignore unrelated emails (newsletters, marketing) — only act on the most recent verification email from the expected sender.
- If multiple verification emails are present, use the most recent one.
```

<Tip>
  The verification code prompt above is generic — for password-based 2FA where the code comes from an **authenticator app** rather than email, use the built-in [TOTP tool](/fundamentals/profiles#2fa---totp-secrets) instead.
</Tip>

<Warning>
  LLMs don't have a real `sleep` primitive — they "wait" by letting the next tool call happen on the next step of the loop. In practice, instructing the agent to "wait 10 seconds and retry" gives it enough latency in the model + tool round-trip to be effective. Avoid asking it to poll too tightly (e.g. every second) — it wastes steps and can hit rate limits on the upstream site.
</Warning>

## Privacy and isolation

* `get_mail` only returns emails addressed to the **profile's own inbox**. Mail sent to a different profile is not visible.
* Inbox addresses are unique across the platform — no two profiles can share the same prefix.
* Inboxes persist for the lifetime of the profile. Deleting the profile releases the prefix.

## Limitations

* The inbox is only available to executions that have an agent profile attached.
* Attachments on inbound mail are surfaced in the `get_mail` response but cannot currently be downloaded as workflow files.
* Mail delivery is best-effort — for hard-real-time flows, build in retries (see the prompt example above) rather than assuming the next `get_mail` call will succeed.

***

<Note>
  For more on profiles, credentials, and TOTP secrets, see [Agent Profiles](/fundamentals/profiles). For the full list of node capabilities including `send_mail` and `get_mail`, see [AI Capabilities](/fundamentals/ai-capabilities#communication).
</Note>


# Environments
Source: https://docs.asteroid.ai/fundamentals/environments

Overview of Browser, Linux, and Windows environments for agent execution

Asteroid agents run inside isolated sandboxes. The environment type determines how the agent interacts with the target system.

## Choose an environment

Use the pages below to pick the environment that matches your workload:

<CardGroup>
  <Card title="Browser" icon="globe" href="/fundamentals/environments-browser">
    Headless Chromium with DOM tools, scripts, and optional CUA.
  </Card>

  <Card title="Linux" icon="terminal" href="/fundamentals/environments-linux">
    Full Linux desktop for native apps and non-browser workflows.
  </Card>

  <Card title="Windows" icon="monitor" href="/fundamentals/environments-windows">
    Windows desktop for Windows-only enterprise software.
  </Card>
</CardGroup>

## Quick comparison

| Environment | Best for                                    | Interaction mode                   |
| :---------- | :------------------------------------------ | :--------------------------------- |
| Browser     | Web apps and sites in Chromium              | DOM tools + scripts + optional CUA |
| Linux       | Browser plus Linux-native desktop workflows | CUA desktop control                |
| Windows     | Windows-only desktop software               | CUA desktop control                |

***

## Shared conventions

Regardless of environment type, every sandbox uses the same **`/home/agent`** directory layout (`shared/`, `workspace/`, `downloads/`, `uploads/`), so file handling and tool behaviour stay consistent. See [Files](/fundamentals/files) for details.

<CardGroup>
  <Card title="Files" icon="folder" href="/fundamentals/files">
    Directory layout and file API access
  </Card>

  <Card title="AI Capabilities" icon="wand-magic-sparkles" href="/fundamentals/ai-capabilities">
    Tools and capability identifiers
  </Card>

  <Card title="Profiles" icon="user" href="/fundamentals/profiles">
    Credentials and environment configuration
  </Card>
</CardGroup>


# Browser Environment
Source: https://docs.asteroid.ai/fundamentals/environments-browser

Use Asteroid's Browser environment for Chromium-based web automation with DOM tools, Playwright scripts, and optional CUA.

The Browser environment runs your agent in a headless Chromium sandbox.

## When to use Browser

Choose Browser when your workflow is primarily web-based:

* Filling forms and navigating web apps
* Extracting structured content from pages
* Running deterministic browser automations
* Combining scripted steps with AI-driven web interaction

## Interaction options

Browser supports three approaches that can be mixed in one workflow:

* **DOM-based interaction**: click, type, and select by page structure
* **Playwright scripts**: deterministic JavaScript for precise repeatable steps
* **Computer Use (CUA)**: screenshot-based coordinate actions when DOM tooling is insufficient

## Related pages

* [Environments overview](/fundamentals/environments)
* [Linux environment](/fundamentals/environments-linux)
* [Windows environment](/fundamentals/environments-windows)
* [AI capabilities](/fundamentals/ai-capabilities)


# Linux Environment
Source: https://docs.asteroid.ai/fundamentals/environments-linux

Use Asteroid's Linux environment for full desktop automation beyond the browser.

The Linux environment gives your agent a full Linux desktop session in an isolated sandbox.

## When to use Linux

Choose Linux when the task goes beyond browser-only automation:

* Using native desktop applications
* Running terminal-driven workflows
* Working with local files through desktop tools
* Handling mixed browser and desktop interactions

## Interaction model

Linux environments rely on **Computer Use (CUA)** models that reason over screenshots and generate keyboard and mouse actions to control the desktop.

## Related pages

* [Environments overview](/fundamentals/environments)
* [Browser environment](/fundamentals/environments-browser)
* [Windows environment](/fundamentals/environments-windows)
* [Files](/fundamentals/files)


# Windows Environment
Source: https://docs.asteroid.ai/fundamentals/environments-windows

Use Asteroid's Windows environment for automations that require Windows-only desktop software.

The Windows environment provides a Windows desktop session in an isolated sandbox.

## When to use Windows

Choose Windows when your workflow depends on Windows-only software:

* Legacy enterprise desktop tools
* Vendor clients available only on Windows
* Internal apps that require Windows runtime dependencies

## Interaction model

Windows environments use **Computer Use (CUA)** models for interaction. The model interprets screenshots and issues mouse and keyboard actions to operate the desktop.

## Related pages

* [Environments overview](/fundamentals/environments)
* [Browser environment](/fundamentals/environments-browser)
* [Linux environment](/fundamentals/environments-linux)
* [Profiles](/fundamentals/profiles)


# Execution Statuses
Source: https://docs.asteroid.ai/fundamentals/execution-statuses

Understanding the lifecycle of agent executions

When you execute an agent, it progresses through various **statuses** that track its lifecycle from initiation to completion. Understanding these statuses helps you monitor execution state, handle errors gracefully, and build robust automation workflows.

Execution statuses fall into four main categories:

<CardGroup>
  <Card title="Processing" icon="gears">
    Actively starting or running
  </Card>

  <Card title="Paused" icon="pause">
    Temporarily suspended
  </Card>

  <Card title="Awaiting" icon="hourglass">
    Waiting for user input
  </Card>

  <Card title="Terminal" icon="flag-checkered">
    Finished (final states)
  </Card>
</CardGroup>

***

## Status Types

### Processing Statuses

These statuses indicate that the execution is actively being processed or is in the process of starting.

#### `starting`

The execution has been initiated but hasn't begun actual processing yet. This is the initial state when you trigger an agent execution.

**Can transition to:** `running`, `failed`, `cancelled`, `completed`

#### `running`

The execution is actively processing and executing agent logic. The agent is navigating pages, interacting with elements, or making decisions.

**Can transition to:** `paused`, `cancelled`, `awaiting_confirmation`, `completed`, `failed`

***

### Paused Statuses

These statuses indicate that execution has been temporarily suspended and can be resumed later.

#### `paused`

The execution has been paused by user request. This is useful when you need to temporarily halt an execution without cancelling it entirely.

**Can transition to:** `cancelled`, `running`

<Info>
  User-initiated pauses allow you to safely suspend execution and resume later without losing progress.
</Info>

#### `paused_by_agent`

The execution has been paused by the agent itself, typically when waiting for some condition or resource to become available.

**Can transition to:** `cancelled`, `running`

<Warning>
  **Timeout Considerations:** If an execution remains paused by the agent beyond the configured timeout period, it will timeout and transition to a `failed` state.
</Warning>

***

### Awaiting Statuses

#### `awaiting_confirmation`

The execution is waiting for user confirmation before proceeding. This status is used when the agent needs explicit user approval to continue with a sensitive or important action.

**Can transition to:** `completed`, `cancelled`, `failed`, `running`

<Tip>
  Use awaiting confirmation for critical operations that require human oversight, such as financial transactions or data deletions.
</Tip>

***

### Terminal Statuses

These statuses indicate that the execution has finished and **cannot transition to any other state**. They represent the final outcome of an execution.

#### `completed`

The execution finished successfully. The agent completed all its tasks and reached an Output node with a success outcome.

**Can transition to:** None (terminal state)

#### `failed`

The execution encountered an error and could not complete. This could be due to unexpected page states, missing elements, timeouts, or other runtime errors.

**Can transition to:** None (terminal state)

#### `cancelled`

The execution was cancelled by user request or system intervention. Work stopped before completion.

**Can transition to:** None (terminal state)

<Warning>
  **Terminal states are immutable.** Once an execution reaches `completed`, `failed`, or `cancelled`, it cannot be resumed or modified. You must start a new execution to retry.
</Warning>

***

## State Transitions

The status system enforces a **strict state machine** to maintain data integrity and ensure executions follow valid lifecycle paths.

### Valid Transition Rules

```mermaid theme={null}
graph TB
    starting[starting]
    running[running]
    paused[paused]
    paused_by_agent[paused_by_agent]
    awaiting[awaiting_confirmation]
    completed[completed]
    failed[failed]
    cancelled[cancelled]

    starting --> running
    starting --> failed
    starting --> cancelled
    starting --> completed

    running --> paused
    running --> awaiting
    running --> completed
    running --> failed
    running --> cancelled

    paused --> running
    paused --> cancelled

    paused_by_agent --> running
    paused_by_agent --> cancelled

    awaiting --> running
    awaiting --> completed
    awaiting --> failed
    awaiting --> cancelled

    style completed fill:#dcfce7
    style failed fill:#fee2e2
    style cancelled fill:#fef3c7
    style running fill:#dbeafe
    style starting fill:#e0e7ff
```

### Key Transition Constraints

1. **Terminal states are final** – Once an execution reaches `completed`, `failed`, or `cancelled`, it cannot transition to any other state.

2. **Starting is flexible** – From `starting`, the execution typically moves to `running`, but can go directly to terminal states if initialization fails or is cancelled.

3. **Running is the hub** – The `running` state is the most flexible and can transition to paused states, awaiting confirmation, or any terminal state.

***

## User-Initiated Status Changes

You can control execution flow by updating the execution status through the API.

### Pause

Pausing an execution temporarily suspends it, allowing you to inspect its current state or coordinate with other systems. The execution can be resumed later from where it left off.

**When to use:**

* Need to temporarily halt execution
* Want to inspect current state before continuing
* Coordinating with other systems or processes

### Resume

Resume a paused execution to continue processing from where it stopped.

### Cancel

Cancelling an execution stops it permanently and transitions it to a terminal state. **Cancel requests take priority over pause requests.**

**When to use:**

* Execution is no longer needed
* Detected an error condition
* User wants to stop the automation

<Info>
  If a pause request is pending and you issue a cancel request, the cancel will take priority and the execution will be cancelled instead of paused.
</Info>

See the [API Reference](/api-reference) for details on updating execution status.

***

## Monitoring Execution Status

There are two primary ways to monitor execution status:

### Polling for Status Updates

You can poll the execution status endpoint to monitor progress. Check the status field to determine if the execution is still processing, has completed, or encountered an error.

**Status categories for monitoring:**

* **Processing**: `starting`, `running`
* **Paused**: `paused`, `paused_by_agent`
* **Awaiting**: `awaiting_confirmation`
* **Terminal**: `completed`, `failed`, `cancelled`

See the [API Reference](/api-reference) for details on the execution status endpoint.

### Webhook Notifications

For real-time status updates, configure webhooks to receive notifications when execution status changes. This is more efficient than polling, especially for long-running executions.

Learn more about webhooks in the [Integrations](/fundamentals/integrations/webhooks) section.

***

## Best Practices

### 1. Always Check Status Before Operations

Before attempting to send messages or modify an execution, verify it's not in a terminal state. Operations on completed, failed, or cancelled executions will fail.

### 2. Handle All Terminal States

When monitoring executions, handle all three terminal states appropriately:

* **`completed`**: Extract results and proceed with your workflow
* **`failed`**: Log the error, trigger retry logic, or send alerts
* **`cancelled`**: Clean up resources and notify relevant systems

### 3. Distinguish Between Pause Types

Track whether a pause was user-initiated or agent-initiated for proper UI/UX:

* **`paused`**: User-initiated - show "Resume" controls
* **`paused_by_agent`**: Agent-initiated - display "Agent is waiting..." message

### 4. Set Appropriate Timeouts

When polling for status, implement timeout logic to avoid indefinite waiting. Consider the expected duration of your automation when setting timeouts.

### 5. Use Webhooks for Long-Running Executions

For executions that may take several minutes or hours, use webhooks instead of polling to avoid unnecessary API calls and improve efficiency.

***

## Related Resources

<CardGroup>
  <Card title="API Reference" icon="code" href="/api-reference/endpoints/execution/get-execution-status">
    View the execution status API endpoint
  </Card>

  <Card title="Webhooks" icon="webhook" href="/fundamentals/integrations/webhooks">
    Set up real-time status notifications
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/fundamentals/graph-agents">
    Learn about failure paths in workflows
  </Card>

  <Card title="SDKs" icon="book-open" href="/sdks/setup">
    Use our TypeScript or Python SDKs
  </Card>
</CardGroup>


# Agent Filesystem
Source: https://docs.asteroid.ai/fundamentals/files

A full filesystem where agents create files, run scripts, and persist knowledge across executions

Every Asteroid agent has access to a **real filesystem**. During a run the agent can create files, update them, and execute scripts—just like a developer working on a local machine. This is what makes browser agents on Asteroid so capable: they don't just click through pages, they can **write code, run it, and build on it later**.

The agent interacts with the filesystem using standard tools — **Read**, **Write**, **Edit**, **Glob**, **Grep**, and **Bash** — with the working directory set to `/home/agent`.

## Agents that improve over time

The filesystem has a **persistent region** called **`shared/`** that survives between executions. Before each run, all previously saved shared files are restored into the sandbox. Anything the agent writes to `shared/` during the run is synced back to durable storage when the execution finishes. That means an agent can:

* **Remember how a workflow works** — save step-by-step procedures so future runs skip the trial-and-error phase.
* **Record site-specific gotchas** — note that a portal requires a specific click order, or that a form silently drops data if submitted too fast.
* **Store and refine scripts** — write Playwright scripts during one run, then reuse and improve them on the next (see [Scripted mode](/fundamentals/nodes/ai-task)).
* **Build up knowledge** — accumulate extracted data, summaries, or reference files the model can read via file tools.

This is a **frontier capability**: instead of starting from scratch every time, each execution makes the agent a little smarter. Workflows **compound in quality** over repeated runs.

## Directory layout

Each execution mounts a filesystem under `/home/agent` with four regions:

| Directory        | Scope                          | Quota  | Purpose                                                                      |
| ---------------- | ------------------------------ | ------ | ---------------------------------------------------------------------------- |
| **`shared/`**    | Persists across all executions | 50 MB  | Durable memory — scripts, notes, extracted data, learned procedures          |
| **`workspace/`** | Current execution only         | 500 MB | Scratch space for in-progress work                                           |
| **`downloads/`** | Current execution only         | 500 MB | Browser downloads land here (see [Environments](/fundamentals/environments)) |
| **`uploads/`**   | Current execution only         | 200 MB | Files attached via API or staging                                            |

Rule of thumb: if the agent should remember it next time, put it in **`shared/`**. Everything else goes in **`workspace/`**.

<Tip>
  The agent is automatically notified when new files appear in `downloads/` or `uploads/` (e.g. browser downloads or API uploads). Changes to `shared/` and `workspace/` don't trigger notifications since the agent created those files itself.
</Tip>

<CardGroup>
  <Card title="Staging Files" icon="clock" href="#staging-files">
    Pre-upload files before starting an execution
  </Card>

  <Card title="File Downloads" icon="download" href="#file-downloads">
    Automatically download files from websites
  </Card>

  <Card title="File Reading" icon="eye" href="#file-reading">
    Read and process images, PDFs, CSVs, and other file types
  </Card>

  <Card title="File Uploads" icon="upload" href="#file-uploads">
    Upload files to web forms and applications
  </Card>

  <Card title="API Access" icon="code" href="#api-access">
    Programmatically manage files through the Asteroid Odyssey SDK
  </Card>
</CardGroup>

## Staging Files

<Info>
  Use staging files when you need to provide files to an execution **before** it starts.
  If your execution is already running, use [Upload files to an execution](/api-reference/endpoints/files/post-executions-context-files) instead.
</Info>

Staging files is useful when you have files that the agent needs from the very start of execution.

### How It Works

```mermaid theme={null}
sequenceDiagram
    participant App
    participant StagingAPI as /temp-files
    participant ExecuteAPI as /agents/{id}/execute
    participant Execution

    App->>StagingAPI: POST files
    StagingAPI-->>App: tempFiles (id, name)
    Note over App: Must use within 60 mins
    App->>ExecuteAPI: POST with tempFiles array
    ExecuteAPI->>Execution: Start with files attached
```

1. **Stage**: Upload files via `POST /temp-files/{organizationId}` - this returns an array of temp file objects with `id` and `name`
2. **Execute**: Pass the temp file array in the `tempFiles` parameter when calling `POST /agents/{agentId}/execute`
3. When the execution starts, your staged files are automatically attached to the execution context

<Warning>
  Staged files expire after **60 minutes**. You must start an execution using the staged files within this time window, or the files will be automatically deleted.
</Warning>

### Code Examples

<CodeGroup>
  ```typescript staging-files.ts theme={null}
  import { client, tempFilesStage, agentExecutePost } from 'asteroid-odyssey';
  import { readFileSync } from 'node:fs';

  client.setConfig({
    headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
  });

  // Step 1: Stage files before execution
  const fileContent = readFileSync('document.pdf');
  const file = new File([fileContent], 'document.pdf', { type: 'application/pdf' });

  const { data: staged } = await tempFilesStage({
    path: { organizationId: 'YOUR_ORGANIZATION_ID' },
    body: { files: [file] },
  });
  // staged.tempFiles = [{ id: "uuid", name: "document.pdf" }]

  // Step 2: Execute agent with staged files
  const { data } = await agentExecutePost({
    path: { agentId: 'YOUR_AGENT_ID' },
    body: {
      tempFiles: staged?.tempFiles,
      inputs: {
        // your variables
      },
    },
  });

  console.log(`Execution ID: ${data?.executionId}`);
  ```

  ```python staging-files.py theme={null}
  import os
  import requests

  api_key = os.environ.get("ASTEROID_API_KEY", "YOUR_API_KEY")
  organization_id = "YOUR_ORGANIZATION_ID"
  agent_id = "YOUR_AGENT_ID"

  # Step 1: Stage files before execution
  with open("document.pdf", "rb") as f:
      stage_response = requests.post(
          f"https://odyssey.asteroid.ai/agents/v2/temp-files/{organization_id}",
          headers={"X-Asteroid-Agents-Api-Key": api_key},
          files={"files": ("document.pdf", f)},
      )

  temp_files = stage_response.json()["tempFiles"]
  # temp_files = [{"id": "uuid", "name": "document.pdf"}]

  # Step 2: Execute agent with staged files
  execute_response = requests.post(
      f"https://odyssey.asteroid.ai/agents/v2/agents/{agent_id}/execute",
      headers={
          "X-Asteroid-Agents-Api-Key": api_key,
          "Content-Type": "application/json",
      },
      json={
          "tempFiles": temp_files,
          "inputs": {  # your variables
          },
      },
  )

  execution_id = execute_response.json()["executionId"]
  ```
</CodeGroup>

## File Downloads

Your agents can download files from websites during browser automation sessions. Files land under **`/home/agent/downloads`** and sync like other agent directories; use **List Files** and related tools rather than forcing `download.saveAs()` into custom paths.

<Info>Downloaded files appear in the Files area of the execution UI and in API/SDK file listings.</Info>

## File Reading

Asteroid agents can read and process various file types.

### Supported File Types

* **Images (PNG, JPEG)**
* **PDFs**
* **Text Files (TXT, MD)**
* **CSVs**

## File Uploads

Agents can upload files to web applications using the **Upload File** tool, which supports:

* Local file uploads
* Previously downloaded files (using `downloads/filename` format)

## API Access

File upload and downloads are also available programmatically through the Asteroid Odyssey SDK:

<CardGroup>
  <Card title="Stage Files Endpoint" icon="clock" href="/api-reference/endpoints/files/stage-a-file-for-an-execution">
    Stage files before you start an execution.
  </Card>

  <Card title="Upload Files Endpoint" icon="upload" href="/api-reference/endpoints/files/post-executions-context-files">
    Upload files to an execution that is already running.
  </Card>
</CardGroup>

### Upload Files

```typescript theme={null}
import { client, executionContextFilesUpload } from 'asteroid-odyssey';
import { readFileSync } from 'node:fs';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

// Upload files to a running execution
const fileContent = readFileSync('document.pdf');
const file = new File([fileContent], 'document.pdf', { type: 'application/pdf' });

await executionContextFilesUpload({
  path: { executionId: 'your-execution-id' },
  body: { files: [file] },
});
```

### Download Files

Each file in the list response includes a `downloadUrl`. Fetch it with your API key and the server will redirect you to the file contents.

<CodeGroup>
  ```typescript download-files.ts theme={null}
  import { client, executionContextFilesGet } from 'asteroid-odyssey';
  import { writeFileSync } from 'node:fs';

  client.setConfig({
    headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
  });

  const { data: files } = await executionContextFilesGet({
    path: { executionId: 'your-execution-id' },
  });

  for (const file of files ?? []) {
    const response = await fetch(file.downloadUrl, {
      headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
    });
    if (!response.ok) throw new Error(`Download failed: ${response.status}`);
    writeFileSync(`./downloads/${file.fileName}`, Buffer.from(await response.arrayBuffer()));
  }
  ```

  ```python download-files.py theme={null}
  import os
  import requests

  api_key = os.environ["ASTEROID_API_KEY"]
  headers = {"X-Asteroid-Agents-Api-Key": api_key}

  files = requests.get(
      f"https://odyssey.asteroid.ai/agents/v2/executions/your-execution-id/context-files",
      headers=headers,
  ).json()

  for file in files:
      data = requests.get(file["downloadUrl"], headers=headers).content
      with open(f"./downloads/{file['fileName']}", "wb") as f:
          f.write(data)
  ```
</CodeGroup>

<Tip>
  `downloadUrl` is an authenticated Asteroid URL, not a direct storage link. Your HTTP client follows the redirect automatically — no extra handling needed.
</Tip>


# Graph Agents
Source: https://docs.asteroid.ai/fundamentals/graph-agents

Graph workflows, nodes, transitions, and context patterns on Asteroid

Asteroid implements browser automation as **graph workflows**: a simple but powerful way to break complex tasks into small, reliable components.
Instead of one large “do everything” agent, your automation is built from **nodes** (focused subtasks) linked by **transitions** (rules that determine what happens next).

This structure makes your agents:

<CardGroup>
  <Card title="Reliable" icon="shield-check">
    Each node handles a narrow responsibility, reducing ambiguity and improving success rates
  </Card>

  <Card title="Observable" icon="eye">
    Every state, transition, and action is visible, making debugging and monitoring effortless
  </Card>

  <Card title="Composable" icon="puzzle-piece">
    Mix AI actions, scripts, and outputs seamlessly
  </Card>

  <Card title="In Control" icon="sliders">
    Assign different models, permissions, and capabilities to each part of your workflow
  </Card>
</CardGroup>

***

## Nodes & Transitions

Asteroid workflows are built from two core concepts: **nodes** and **transitions**.

### Nodes

Nodes represent individual steps of your automation. They come in a range of types, depending on the nature of their subtask:

<Card title="AI Task Node" icon="brain" href="/fundamentals/nodes/ai-task">
  Instruct an LLM to interact with the webpage
</Card>

<Card title="Output Node" icon="check-circle" href="/fundamentals/nodes/output">
  End the execution and return an outcome label plus structured results
</Card>

### Transitions

Transitions define how the workflow moves between nodes:

* **Agent-driven** transitions: The AI detects when a subtask is complete and moves forward
* **Deterministic** transitions: Code or conditions trigger movement (e.g., *“element X appeared”*)

This hybrid architecture gives you the freedom to pair AI reasoning with deterministic logic—ideal for real-world, multi-step browser flows.

<Info>
  Curious why we chose this architecture?
  Read our deep dive: **[Graph-Powered Browser Agents](https://asteroid.ai/blog/introducing-asteroid-ai-browser-agents)**.
</Info>

***

## Context Management

### Local context

Each node receives only the information it needs for **its subtask**. This prevents context pollution, reduces reasoning drift, and makes each step more deterministic.

### Passing information between nodes

When data must flow between steps, you should use:

* **[Scratchpad](/fundamentals/ai-capabilities#memory-%26-storage)**: store information in a file shared by nodes
* **[Query Context](/fundamentals/ai-capabilities#context-%26-utilities)**: allow the LLM to query values from earlier nodes

This model avoids “giant prompts” and encourages clean, modular design—similar to strong function boundaries in software engineering.

***

## Workflow Design Best Practices

### 1. Start simple

Begin with:

* **One AI Task node**, and
* **One Output node**

This helps validate the core task before introducing structure.

### 2. Add nodes as complexity grows

Introduce more nodes when:

* You interact with **multiple portals** or move between distinct URLs
* The workflow involves **separate tabs or pages** within one portal
* A subtask becomes long or has multiple sub-steps
* You want different models or timeouts for different stages
* You’ve gained grounded knowledge and can safely split steps

A good rule of thumb:

> **If a node needs more than a paragraph of instructions, it should probably be split.**

### 3. Scope nodes to a sequence of related actions

Each node should represent a clear, single intention, such as:
“Fill driver information” | “Upload documents” | “Retrieve quote”.

### 4. Use descriptive naming

Clear names make your graph self-documenting:

* **Agent Name** – what the whole flow accomplishes
* **Node Names** – the subtask (“Drivers Node”, “Billing Node”)
* **Variables** – reflect real-world meaning (`customer_id`, `doctor_note`)
* **Outcome labels** – predictable and explicit

### 5. Always define failure paths

Every AI Task node should have a **Failure** transition to an output node.

Failure paths make debugging easier and enable safe recoverability.

***

## Examples Task Decomposition

Here are high-level examples of how complex workflows break naturally into nodes.

### **Insurance Carrier Quoting**

**Task:** Generate an insurance quote for a customer.

**Nodes**:

* <Icon icon="brain" /> Navigate to carrier and log in (AI Task node)
* <Icon icon="brain" /> Create quote (AI Task node)
* <Icon icon="brain" /> Insert driver info (AI Task node)
* <Icon icon="check-circle" /> Output quote (Output node)

***

### **Healthcare EHR Data Entry**

**Task:** File a patient consultation on an EHR.

**Nodes**:

* <Icon icon="brain" /> Navigate to EHR and log in (AI Task node)
* <Icon icon="brain" /> Lookup patient (AI Task node)
* <Icon icon="brain" /> Fill consultation (AI Task node)
* <Icon icon="check-circle" /> Confirm success (Output node)

***

### **Property Management Workflow**

**Task:** Update the lease information for a tenant.

**Nodes**:

* <Icon icon="brain" /> Navigate to portal and log in (AI Task node)
* <Icon icon="brain" /> Search tenant (AI Task node)
* <Icon icon="brain" /> Update lease info (AI Task node)
* <Icon icon="check-circle" /> Return updated records (Output node)

These flows remain readable, predictable, and easy to iterate on, far more than a single long-running “mega-agent.”


# Overview
Source: https://docs.asteroid.ai/fundamentals/integrations/overview

Learn how to connect Asteroid Agents to external services

Integrations allow your agents to communicate with external services and platforms. Whether you need to send notifications to Slack, trigger webhooks, or connect to other tools, the integration system provides a flexible way to handle these interactions.

## How Integrations Work

The integration system operates on two levels:

1. **Global Integrations**: You first create an integration at the organization level. This establishes the connection to the external service (e.g., authenticating with Slack or defining a webhook endpoint).
2. **Agent Notifications**: You then "bind" these integrations to specific agents. This allows you to control exactly which agents use which integrations and what events trigger them.

<Frame>
  ```mermaid theme={null} theme={null}
  flowchart TD
    Service["External Service (e.g. Slack)"]
    Integration["Integration"]
    NotifA["Notification A"]
    NotifB["Notification B"]
    AgentA["Agent A"]
    AgentB["Agent B"]

    Service <--> Integration
    Integration --> NotifA
    Integration --> NotifB
    NotifA --> AgentA
    NotifB --> AgentB
  ```
</Frame>

## Event System

Asteroid Agents emit events throughout their execution lifecycle. You can subscribe to these events to trigger notifications or external workflows.

### Event Types

#### Execution Status Events

| Event Type                      | Description                                                                               |
| :------------------------------ | :---------------------------------------------------------------------------------------- |
| `ExecutionStarted`              | Triggered when an agent begins a new execution.                                           |
| `ExecutionCompleted`            | Triggered when an agent successfully completes its task.                                  |
| `ExecutionFailed`               | Triggered when an agent encounters an error and fails.                                    |
| `ExecutionCancelled`            | Triggered when an execution is cancelled (by user, timeout, or max steps).                |
| `ExecutionPaused`               | Triggered when an agent pauses (e.g., waiting for user input).                            |
| `ExecutionResumed`              | Triggered when a paused agent resumes execution.                                          |
| `ExecutionAwaitingConfirmation` | Triggered when an agent needs confirmation before proceeding (e.g., "Human in the Loop"). |

#### Action Events

| Event Type               | Description                                            |
| :----------------------- | :----------------------------------------------------- |
| `ExecutionActionStarted` | Triggered when an action within execution has started. |
| `ExecutionActionFailed`  | Triggered when an action within execution fails.       |

#### Execution Details Events

| Event Type                 | Description                                                |
| :------------------------- | :--------------------------------------------------------- |
| `ExecutionStepStarted`     | Triggered when a step in the execution starts.             |
| `ExecutionWorkflowUpdated` | Triggered when the execution workflow is updated.          |
| `UserMessageReceived`      | Triggered when the agent receives a message from the user. |

## Filtering & Rules

When adding a notification to an agent, you can control exactly when it triggers using our powerful filtering system.

### Subscription Modes

* **Subscribe to All**: Receive notifications for **every** event type, including any new event types added in the future.
* **Custom Rules**: Select specific event types and optionally add detailed filters.

### Advanced Filtering

For each event type, you can add one or more **Field Filters**.

* **OR Logic**: If you add multiple filters to a single event type, the notification will trigger if **ANY** of the filters match.
  * *Example*: A filter for `Outcome equals 'failure'` and `Outcome equals 'cancelled'` effectively means "Notify me if the outcome is failure **OR** cancelled".

This allows you to create precise rules, such as:

* "Notify me on `ExecutionCompleted` only if the result contains 'Urgent'."
* "Notify me on `ExecutionFailed` or `ExecutionCancelled`."

### Metadata Filtering

In addition to event-type filters, you can filter notifications based on **execution metadata**. Metadata is a set of key-value pairs that you attach to an execution when you create it (e.g., via the SDK or API).

When you add a notification to an agent, you can specify a **metadata filter** — a set of key-value pairs that must all match the execution's metadata for the notification to fire.

* **AND Logic**: All specified key-value pairs must match. If any pair doesn't match, the notification is skipped.
* **Empty or omitted**: If no metadata filter is set, the notification triggers for all executions regardless of metadata.
* **Extra keys are ignored**: The execution can have additional metadata keys beyond those in the filter — only the keys you specify are checked.

<Note>
  Metadata filtering is applied **after** event-type filtering. An execution must first match the event rules, then match the metadata filter, before a notification is sent.
</Note>

**Example:** You run the same agent across multiple environments and only want Slack alerts for production failures:

| Execution Metadata                         | Metadata Filter                           | Result                                 |
| :----------------------------------------- | :---------------------------------------- | :------------------------------------- |
| `environment: production`                  | `environment: production`                 | Notification sent                      |
| `environment: staging`                     | `environment: production`                 | Skipped                                |
| `environment: production, region: us-east` | `environment: production`                 | Notification sent (extra keys ignored) |
| `environment: production`                  | `environment: production, team: payments` | Skipped (`team` key missing)           |

## Example Use Case

Most users only want to be notified about critical events—when something goes wrong or when specific outcomes occur.

### Scenario: Order Processing Agent

Sarah manages an e-commerce agent that processes customer orders hourly. She doesn't need notifications for every successful order, but she does want alerts for failures and payment issues.

**Her Configuration:**

1. Creates a Slack integration connected to `#operations-alerts`
2. Adds it to her agent with filters:
   * **Event: `ExecutionFailed`** - No filters (all failures)
   * **Event: `ExecutionCompleted`** - Filter: `outcome` equals `payment_declined`

**What Happens:**

* **Successful orders** (`outcome: success`) → No notification
* **Failed executions** → Slack alert: "🔴 Execution Failed - Payment gateway timeout"
* **Declined payments** → Slack alert: "🟡 Execution Completed - Payment declined for Order #12345"

**Result:** Sarah's team receives 5-10 critical notifications per day instead of hundreds.

### Scenario: Multi-Environment Deployment Agent

Alex runs the same deployment agent across staging and production. He wants a different webhook for each environment.

**His Configuration:**

1. Creates two webhook integrations: `Production Alerts` and `Staging Alerts`
2. Adds `Production Alerts` to the agent with:
   * **Events:** `ExecutionFailed`, `ExecutionCompleted`
   * **Metadata Filter:** `environment = production`
3. Adds `Staging Alerts` to the agent with:
   * **Events:** `ExecutionFailed`
   * **Metadata Filter:** `environment = staging`

**What Happens:**

* Production execution fails → `Production Alerts` webhook fires
* Staging execution completes → No notification (staging only alerts on failures)
* Production execution completes → `Production Alerts` webhook fires
* Staging execution fails → `Staging Alerts` webhook fires

**Result:** Each environment routes to the right channel with the right level of detail.


# Slack
Source: https://docs.asteroid.ai/fundamentals/integrations/slack

Send real-time notifications to your Slack channels

The Slack integration allows you to receive rich, real-time updates about your agents directly in your Slack workspace. You can configure notifications for specific events, such as when an execution completes, fails, or requires your attention.

## Prerequisites

* A Slack Workspace where you have permissions to install apps.
* Access to the Asteroid Platform.

## Setup

### 1. Install the Integration

1. Log in to the [Asteroid Platform](https://platform.asteroid.ai).
2. Navigate to **Integrations** in the main menu.
3. Click the **Add Integration** button and select **Slack**.
4. You will be redirected to Slack's authorization page.
   * Review the requested permissions (e.g., `chat:write`, `channels:read`).
   * Select the Slack Workspace you want to connect.
   * Click **Allow** to grant access.

### 2. Configure the Default Channel

Once the integration is installed, you need to tell Asteroid where to send messages by default.

1. In the **Integrations** list, find your new Slack integration.
2. Click the **Edit** button (pencil icon) on the integration card.
3. In the configuration modal, select a **Default Channel** from the dropdown list.
4. Click **Save**.

<Note>
  **Private Channels**: The dropdown lists all public channels. If you want to send notifications to a private channel, you must manually invite the Asteroid bot (usually named `@Asteroid`) to that private channel inside Slack first. Once invited, the channel will appear in the dropdown list (you may need to refresh the page).
</Note>

The Asteroid bot will automatically attempt to join the channel you select.

## Usage

### Binding to Agents

To start receiving notifications, you must attach the Slack integration to your agents.

1. Navigate to the **Agents** page and select an agent.
2. Go to the **Notifications** tab.
3. Click **Add Notification**.
4. Select your Slack integration from the list.
5. Configure your **Event Rules** (see [Overview](/fundamentals/integrations/overview#filtering--rules) for details on filtering).
6. Click **Add**.

### Notification Format

Asteroid sends rich, structured messages to Slack designed to give you immediate context:

* **Status**: Visual indicators (Green for success, Red for failure, etc.) showing the event type.
* **Agent Context**: The name of the agent and a link to the specific execution in the platform.
* **Details**:
  * For `EXECUTION_COMPLETED`: A snippet of the result and the agent's reasoning.
  * For `EXECUTION_FAILED`: The error message and reason for failure.
  * For `EXECUTION_PAUSED`: The reason for the pause (e.g., the question the agent is asking).

### Interactive Elements

Some notifications, such as "Human in the Loop" requests, may include interactive buttons allowing you to View Execution directly from Slack.


# Webhooks
Source: https://docs.asteroid.ai/fundamentals/integrations/webhooks

Set up webhooks for real-time execution notifications

Webhooks let you receive real-time execution notifications from Asteroid over HTTP.

<Note>
  Only **Webhook V2** is supported. Webhook V1 is deprecated and no longer accepted by the API.
</Note>

## Overview

<CardGroup>
  <Card title="Real-time Notifications" icon="bell">
    Get updates as execution events happen
  </Card>

  <Card title="Secure Delivery" icon="shield-check">
    Every request includes an RSA signature in `X-Asteroid-Signature`
  </Card>

  <Card title="Event Coverage" icon="plug">
    Subscribe to status, step, action, file, message, workflow, and batch events
  </Card>

  <Card title="Filterable Notifications" icon="filter">
    Filter by event type, payload fields, and execution metadata
  </Card>
</CardGroup>

## Configuration

### Setting Up Your Webhook

<Steps>
  <Step title="Create a Webhook Integration">
    In Asteroid, go to **Integrations** → **Add Integration** → **Webhook**, then set:

    * **URL**: The endpoint that will receive execution events
    * **Headers**: Optional custom headers Asteroid should include

    <Note>
      Webhook requests are always `POST` with a JSON body in the V2 format documented below.
    </Note>
  </Step>

  <Step title="Attach the Integration to an Agent">
    Attach the webhook integration to each agent you want notifications from. You can configure:

    * **Event rules**: choose which event types should trigger notifications
    * **Field filters**: filter by payload fields for specific event types
    * **Metadata filter**: only trigger when execution metadata key/value pairs match
    * **Unwrap result** (optional): for `ExecutionCompleted`, send only `payload.result` instead of the full envelope

    See [Filtering & Rules](/fundamentals/integrations/overview#filtering--rules) for rule semantics.
  </Step>

  <Step title="Verify Signatures in Your Endpoint">
    Validate the `X-Asteroid-Signature` header against the raw request body before processing.
  </Step>
</Steps>

## V2 Payload Structure

Each webhook request body is a JSON object with this top-level shape:

```json theme={null}
{
  "type": "execution",
  "event_id": "83b7b49f-1f73-4f86-9d89-6fd8dd2557f3",
  "timestamp": "2024-01-15T10:30:00Z",
  "info": {
    "event": "EXECUTION_COMPLETED",
    "execution_id": "a2c7f3b3-cbc8-4b6a-a5f2-c5f6cb548e95",
    "execution_url": "https://platform.asteroid.ai/executions/a2c7f3b3-cbc8-4b6a-a5f2-c5f6cb548e95",
    "agent_id": "6bf63aaf-6e3e-4115-8f13-e707d627582f",
    "agent_name": "Data Extraction Agent",
    "metadata": {
      "environment": "production"
    },
    "payload": {
      "result": { /* execution result data */ },
      "reasoning": "Task completed successfully",
      "outcome": "success"
    }
  }
}
```

### Top-Level Fields

<ParamField type="string">
  The category of the notification. Currently only `"execution"` is supported.
</ParamField>

<ParamField type="string">
  Unique identifier generated for this specific webhook notification payload.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp when the event occurred.
</ParamField>

<ParamField type="object">
  Execution event context and event-specific payload. See [Execution Info](#execution-info-structure).
</ParamField>

### Execution Info Structure

`info` contains execution context plus an event-specific `payload`.

<ParamField type="string">
  Event name. See [Execution Events](#execution-events) for supported values.
</ParamField>

<ParamField type="string">
  Execution UUID.
</ParamField>

<ParamField type="string">
  URL to view this execution (or batch for batch events) in Asteroid.
</ParamField>

<ParamField type="string">
  Agent UUID.
</ParamField>

<ParamField type="string">
  Agent display name.
</ParamField>

<ParamField type="object">
  Optional execution metadata map. Included when metadata was supplied at execution creation time.
</ParamField>

<ParamField type="object">
  Event-specific data. The schema depends on `info.event`.
</ParamField>

## Execution Events

Asteroid currently emits the following webhook events:

### Core execution status

* `EXECUTION_STARTED` -> payload: `{}`
* `EXECUTION_COMPLETED` -> payload: `{ result: object, reasoning: string, outcome: string }`
* `EXECUTION_FAILED` -> payload: `{ reason: string }`
* `EXECUTION_CANCELLED` -> payload: `{ reason: string, cancelled_by: string }`
* `EXECUTION_PAUSED` -> payload: `{ reason: string, paused_by: string }`
* `EXECUTION_RESUMED` -> payload: `{ reason: string }`
* `EXECUTION_AWAITING_CONFIRMATION` -> payload: `{ reason: string }`

### Action and step events

* `EXECUTION_ACTION_STARTED` -> `{ action_id, action_name, arguments, step_number }`
* `EXECUTION_ACTION_COMPLETED` -> `{ action_id, action_name, output, step_number, duration? }`
* `EXECUTION_ACTION_FAILED` -> `{ action_id, action_name, failure, step_number, duration?, os_error? }`
* `EXECUTION_STEP_STARTED` -> `{ step }`
* `EXECUTION_STEP_PROCESSED` -> `{ step }`

### Execution detail events

* `EXECUTION_MESSAGE_ADDED` -> `{ message }`
* `EXECUTION_REASONING_ADDED` -> `{ reasoning }`
* `EXECUTION_FILE_ADDED` -> `{ file_id, file_name, mime_type, file_size, source, presigned_url }`
* `EXECUTION_PLAYWRIGHT_SCRIPT_GENERATED` -> `{ node_id, node_name, script, context, generated_at }`
* `EXECUTION_TRANSITIONED` -> `{ to_node, from_node_duration?, transition_type? }`
* `EXECUTION_WORKFLOW_UPDATED` -> `{ workflow_update: [...] }`
* `USER_MESSAGE_RECEIVED` -> `{ user_id, message, execution_was, injected_into }`

### Batch and test events

* `BATCH_STARTED` -> `{ batch_id, batch_name, item_count }`
* `BATCH_COMPLETED` -> `{ batch_id, batch_name, triggered_count, cancelled_count }`
* `EXECUTION_TEST` -> `{ message }` (used when testing integration connectivity)

<Note>
  For batch events, `info.execution_url` points to the agent batch page (`/agents/{agent_id}/batch`) rather than an execution page.
</Note>

### Example: `EXECUTION_ACTION_FAILED`

```json theme={null}
{
  "type": "execution",
  "event_id": "f0df4bd4-fdf8-445b-b870-1cd6ed329f39",
  "timestamp": "2026-03-27T16:10:05Z",
  "info": {
    "event": "EXECUTION_ACTION_FAILED",
    "execution_id": "a2c7f3b3-cbc8-4b6a-a5f2-c5f6cb548e95",
    "execution_url": "https://platform.asteroid.ai/executions/a2c7f3b3-cbc8-4b6a-a5f2-c5f6cb548e95",
    "agent_id": "6bf63aaf-6e3e-4115-8f13-e707d627582f",
    "agent_name": "Data Extraction Agent",
    "payload": {
      "action_id": "playwright_script-node-123",
      "action_name": "playwright_script",
      "failure": "Timeout waiting for selector",
      "step_number": 7,
      "duration": 1432,
      "os_error": {
        "message": "Target page, context or browser has been closed"
      }
    }
  }
}
```

## Security & Signature Verification

Asteroid signs every webhook body using:

* SHA-256 digest of the raw body bytes
* RSA PKCS#1 v1.5 signing
* Base64-encoded signature in the header

### Signature Header

```
X-Asteroid-Signature: <base64-signature>
```

<Warning>
  Verify signatures using the **raw** request body bytes before JSON parsing.
</Warning>

### Public Key

Use the webhook verification public key provided for your Asteroid environment/workspace.

### JavaScript (Node.js) verification example

```javascript theme={null}
import crypto from "node:crypto";

export function verifyWebhookSignature(rawBodyBuffer, signatureBase64, publicKeyPem) {
  const verifier = crypto.createVerify("sha256");
  verifier.update(rawBodyBuffer);
  verifier.end();

  return verifier.verify(publicKeyPem, signatureBase64, "base64");
}

// Example Express handler
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Asteroid-Signature");
  const isValid = verifyWebhookSignature(req.body, signature, process.env.ASTEROID_WEBHOOK_PUBLIC_KEY_PEM);

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // process event...
  res.status(200).json({ received: true });
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Respond quickly with 2xx">
    Return a `2xx` response as quickly as possible, then process asynchronously in your own job queue.
  </Accordion>

  <Accordion title="Design for at-least-once delivery">
    Duplicate deliveries can happen. Use your own idempotency key strategy based on stable business identifiers.

    <Note>
      `event_id` is generated per notification payload and can change across retries/redeliveries, so do not rely on it as the only dedupe key.
    </Note>
  </Accordion>

  <Accordion title="Verify signatures before processing">
    Validate `X-Asteroid-Signature` against the raw body and reject invalid requests with `401`.
  </Accordion>

  <Accordion title="Handle retries safely">
    Asteroid performs up to 3 send attempts with short backoff in the notification worker before marking a delivery failed.
  </Accordion>

  <Accordion title="Log execution context">
    Log at least `info.event`, `info.execution_id`, `info.agent_id`, and your own processing result for observability.
  </Accordion>
</AccordionGroup>

## Testing Your Webhooks

<Tip>
  Use [webhook.site](https://webhook.site) for quick smoke tests, then validate with your real endpoint and signature verification enabled.
</Tip>

### Test Integration Event Example

Using "Test integration" in Asteroid sends an `EXECUTION_TEST` payload:

```json theme={null}
{
  "type": "execution",
  "event_id": "2ec89fb9-c2b5-4f6a-9fe9-c8f4f9dd6f66",
  "timestamp": "2024-01-15T10:30:00Z",
  "info": {
    "event": "EXECUTION_TEST",
    "execution_id": "00000000-0000-0000-0000-000000000003",
    "execution_url": "",
    "agent_id": "00000000-0000-0000-0000-000000000001",
    "agent_name": "Test Agent",
    "payload": {
      "message": "This is a test notification from Asteroid. If you're seeing this, your integration is working correctly! 🎉"
    }
  }
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook Not Receiving Events">
    * Verify your endpoint is reachable from Asteroid and accepts `POST`
    * Ensure your notification rule configuration matches the events you expect
    * Confirm metadata filter values exactly match execution metadata values
  </Accordion>

  <Accordion title="Signature Verification Failing">
    * Verify against raw request bytes, not parsed JSON
    * Ensure you use RSA PKCS#1 v1.5 with SHA-256
    * Confirm you're using the correct environment public key
  </Accordion>

  <Accordion title="Receiving Duplicate Events">
    * Handle at-least-once semantics in your endpoint logic
    * Use stable execution fields for idempotency (not only `event_id`)
    * Return `2xx` once a duplicate is safely recognized
  </Accordion>
</AccordionGroup>


# AI Task Node
Source: https://docs.asteroid.ai/fundamentals/nodes/ai-task

Instruct an LLM to interact with a webpage

The **AI Task node** uses natural language instructions to perform actions inside a real browser.
It is the most flexible node type and is ideal for handling dynamic UI, multi-step interactions, and workflows that benefit from LLM reasoning.

Common actions include:

<CardGroup>
  <Card title="Navigate" icon="compass">
    Navigate to and through pages
  </Card>

  <Card title="Fill forms" icon="list">
    Enter and submit structured data
  </Card>

  <Card title="Use files" icon="file">
    Read, upload, or download files
  </Card>

  <Card title="Extract data" icon="chart-line">
    Scrape data from a webpage
  </Card>
</CardGroup>

***

## Configuration

### Instructions

The core of an AI Task node is a **natural language instruction block**.
You describe what the agent should do, and the LLM executes those steps in the browser.

#### Recommended Structure

To achieve the most reliable behavior, structure your instructions with:

* **Goal**: What the node is trying to accomplish
* **Ordered steps**: A sequence of specific actions
* **Edge cases**: Known variations the agent must handle
* **Success criteria**: Observable conditions indicating completion

Example:

```
Your goal is to submit the consultation form for the current patient:
1.	Click “New Consultation”
2.	Fill the form fields with the provided data
3.	Upload any provided attachments
4.	Click “Create”

Edge cases:
- If a modal appears, close it before continuing
- If the page asks for confirmation, accept it

Success criteria:
Once you see the “Consultation Submitted” banner, the task is complete.
```

### Dynamic Variables

Dynamic variables make your instructions reusable across multiple runs with different inputs.
Variables are passed at execution time and referenced with the `{{.var_name}}` syntax.

Example:

```
Navigate to the patient search page:
1.	Enter {{.patient_name}} into the search bar
2.	Select the matching result
3.	Fill {{.diagnosis}}
4.	Click Submit
...
```

#### Naming Rules

Variable names must:

* Start with a letter or underscore
* Contain only letters, numbers, and underscores
* Not include special characters such as `@`, `-`, `.`, or spaces

Valid: `{{.user_name}}`, `{{.email}}`, `{{.api_key}}`

Invalid: `{{.user-name}}`, `{{.my@var}}`, `{{.1st_item}}`

### Advanced Templating

AI Task instructions support full **Go Template** syntax, enabling conditionals, loops, and structured data.

<AccordionGroup>
  <Accordion title="Advanced: Conditionals">
    Use `if` statements to conditionally adjust behavior:

    ```
    {{if .is_premium}}
    Navigate to the premium dashboard and enable all features.
    {{else}}
    Navigate to the free dashboard.
    {{end}}
    ```

    The corresponding variable values should be:

    ```json theme={null}
    {"is_premium": true}
    ```
  </Accordion>

  <Accordion title="Advanced: Loops">
    Iterate through lists or arrays.

    **Simple array:**

    ```
    Fill the form with the following items:
    {{range .items}}
    - Enter "{{.}}" in the next field
    {{end}}
    ```

    **Array of objects:**

    ```
    Add products to the cart:
    {{range .products}}
    - {{.name}}: {{.price}}
    {{end}}
    ```

    The corresponding variable values should be:

    ```json theme={null}
    ["Item 1", "Item 2", "Item 3"]
    ```

    Via SDK, you'd pass:

    ```json theme={null}
    {
      "inputs": {
        "products": [
          {"name": "Widget A", "price": "$10"},
          {"name": "Widget B", "price": "$20"}
        ]
      }
    }
    ```

    <Info>
      Inside a `range`, `{{.}}` refers to the current item.
      For objects, use fields like `{{.name}}` and `{{.price}}`.
    </Info>
  </Accordion>

  <Accordion title="Advanced: Nested Data">
    Access nested JSON structures:

    ```
    User: {{.user.name}} ({{.user.email}})

    {{if .user.verified}}
    Proceed to checkout.
    {{else}}
    Please verify your email before continuing.
    {{end}}
    ```

    The corresponding variable values should be:

    ```json theme={null}
    {"name": "Jane Smith", "email": "jane@example.com", "verified": true}
    ```
  </Accordion>
</AccordionGroup>

## Model Selection

Choose the model that best fits the complexity of the task:

<Card title="Asteroid Fast" icon="zap">
  Lowest latency. Best for simple, fast interactions.
</Card>

<Card title="Asteroid Balanced" icon="lightbulb">
  Default model. Balanced speed and accuracy.
</Card>

<Card title="Asteroid Max" icon="brain">
  Highest intelligence and reasoning depth for complex flows.
</Card>

## Execution mode

Execution mode controls how much autonomy the AI has at each step. In **default** mode the model reasons and uses tools freely. In **scripted** mode the runtime runs stored automation first for speed and reliability, falling back to the AI only when the script fails.

Scripted mode pairs that determinism with self-healing: when a script breaks or the UI drifts, you can let the AI recover, escalate to a human, or stop the run, depending on how you configure failure handling below.

<Info>
  In the graph editor this appears as **Execution mode**. In API or YAML exports, set `execution_mode` to `default` or `scripted` on the AI Task node.
</Info>

<Tabs>
  <Tab title="Default" icon="brain">
    Full autonomy with shared knowledge. The agent reasons and acts freely, with access to a persistent `shared/` directory for saving and reusing knowledge across executions.

    <Card title="Agent filesystem" icon="folder-open" href="/fundamentals/files">
      Read how `shared/` keeps files across runs for the same agent
    </Card>
  </Tab>

  <Tab title="Scripted" icon="code">
    Runs stored scripts before the LLM. Falls back to AI on failure, or cancels if freeze is enabled.

    <Tip>
      Use scripted mode when the UI path is stable and you want speed; stay on default while you are still exploring the flow.
    </Tip>
  </Tab>
</Tabs>

### If the script fails

When a stored script errors in scripted mode, the graph editor lets you choose how the run continues:

<CardGroup>
  <Card title="Fall back to AI" icon="sparkles">
    Let the AI agent recover and continue the task.
  </Card>

  <Card title="Cancel execution" icon="ban">
    Stop the execution immediately.
  </Card>

  <Card title="Ask the human" icon="message">
    Pause and wait for a human to decide.
  </Card>
</CardGroup>

## AI Capabilities

Enable specific capabilities depending on what the node needs to perform:

<Card title="Web Browsing Essentials" icon="globe" href="/fundamentals/ai-capabilities#web-browsing-essentials">
  Basic navigation, clicking, typing, and interaction
</Card>

<Card title="Advanced Web Browsing" icon="compass" href="/fundamentals/ai-capabilities#advanced-web-browsing-toolkit">
  Complex navigation, dynamic UIs, and robust action handling
</Card>

<Card title="Computer Vision" icon="eye" href="/fundamentals/ai-capabilities#computer-vision">
  Visual understanding of the page and image-based interaction
</Card>

<Card title="Communication" icon="message" href="/fundamentals/ai-capabilities#communication">
  Exchange messages and emails with the user during execution
</Card>

<Card title="File System" icon="folder" href="/fundamentals/ai-capabilities#file-system">
  Upload, download, read, and write files
</Card>

<Card title="Memory & Storage" icon="database" href="/fundamentals/ai-capabilities#memory-%26-storage">
  Store and retrieve data across execution steps
</Card>

<Card title="Google Sheets" icon="table" href="/fundamentals/ai-capabilities#google-sheets">
  Read from and write to Google Sheets
</Card>

<Card title="Authentication" icon="lock" href="/fundamentals/ai-capabilities#authentication">
  Generate and manage authentication tokens
</Card>

<Card title="Context & Utilities" icon="info" href="/fundamentals/ai-capabilities#context-%26-utilities">
  Access contextual data and system utilities
</Card>

<Info>
  Explore all available features in **[AI Capabilities](/fundamentals/ai-capabilities)**.
</Info>

<Warning>
  **Critical: Basic Browser Interaction Tools Required**

  **Always ensure Basic Web Interaction tools are enabled for AI Task nodes.** This capability is enabled by default and provides essential tools for clicking, typing, selecting elements, and interacting with the DOM.

  * Basic Web Interaction is required for AI Task nodes to function properly
  * Disabling this capability will prevent the agent from performing basic browser interactions
  * You should not disable this capability unless you have a very specific reason

  For more details, see [AI Capabilities](/fundamentals/ai-capabilities#web-browsing-essentials).
</Warning>

***

## Transitions and Failure Handling

<Warning>
  **Critical: AI Task Nodes Must Have Failure Paths**

  **All AI Task nodes must have a connection to an Output node via a failure path.** This is essential for proper error handling and workflow completion.

  * Every AI Task node should have at least one transition (typically an AI Transition) that connects to an Output node configured for failure scenarios
  * Without a failure path, your workflow may not properly handle errors, unexpected conditions, or edge cases
  * This ensures that unexpected conditions, missing elements, or interpretation errors are surfaced correctly in your workflow

  For more details, see [Transitions](/fundamentals/transitions#failure-transitions) and [Output Nodes](/fundamentals/nodes/output).
</Warning>

***

## API / YAML Reference

When configuring an AI Task node via the API, SDK, or MCP, use the following type identifier:

| Field            | Value                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Node type        | `ai`                                                                                                                          |
| Transition types | `ai`, `selector`                                                                                                              |
| Optional         | `execution_mode`: `default` or `scripted`; `freeze`: cancel when the stored script is missing or fails (strict scripted path) |

Example `settings.yaml`:

```yaml theme={null}
label: "Submit Form"
type: ai
execution_mode: default
tools:
  - go_to_url
  - dom_browser_interaction
model: "asteroid_balanced"
transitions:
  - to: success_output
    type: ai
  - to: failure_output
    type: ai
  - to: confirmation_page
    type: selector
    name: "Confirmation Visible"
    selector: ".confirmation-banner"
```

The node's instructions are stored in a separate `instructions.md` file in the same directory.

***

## Additional Settings

### Batch Actions

Enable parallel steps for faster execution when the workflow allows it.

### Snapshot Compression

Reduce context size by compressing browser snapshots captured during execution.

### Scripted mode (scripts and placeholders)

In **scripted** execution mode, the runtime looks for a stored script on disk before involving the full LLM turn. API / YAML: `execution_mode: scripted` on the AI Task node.

#### Where scripts live

Scripts live under the agent’s persistent **`shared/`** tree (see [Agent filesystem](/fundamentals/files)):

* Default path: `shared/<node-slug>/scripts/` with **exactly one** `.js` file for the fast path.
* If you pass a `target_directory` execution input, the path becomes `shared/<node-slug>/<target_directory>/scripts/`.

`<node-slug>` is derived from the node’s display name (lowercased, punctuation stripped). See [Files](/fundamentals/files) for the full layout.

#### Placeholders and substitution

1. **`__PLACEHOLDER__`** — Double underscores around a **UPPER\_SNAKE** name in the saved script. Before the deterministic run, a lightweight model pass reads the script plus your **instructions** and fills these slots; values are substituted into the script text.
2. **`<<.var_name>>`** — Same family as Playwright script variables: declared fields the resolver replaces with concrete strings before execution.

Vault secrets use **`##CREDENTIAL##`** (see [Agent profiles](/fundamentals/profiles)); that system is separate from `__PLACEHOLDER__` and `<<.>>` resolution.

#### Runtime behaviour

The stored script runs against the live browser session. Credentials referenced in the script are injected automatically at runtime; return values are captured as activities for transitions.

If the script **succeeds** and the node has a **single unambiguous outbound transition**, the runtime may advance **without** a full agent round-trip for that node. Otherwise the script outcome is passed to the model as context.

If **no** eligible script file exists while the node is configured to require one (strict / **freeze** in API exports), the execution cannot proceed.

<Info>
  Scripted mode is usually much faster than full **default** mode but expects stable UI. Use **default** mode while you are still discovering the flow; move to **scripted** mode when the path is repeatable.
</Info>


# Output Node
Source: https://docs.asteroid.ai/fundamentals/nodes/output

Terminate the workflow and return results with a custom outcome label

The **Output Node** marks the end of your agent's execution.
When your agent reaches an Output Node, it:

<CardGroup>
  <Card title="End Execution" icon="stop">
    Terminates the workflow and closes the browser
  </Card>

  <Card title="Outcome Label" icon="tag">
    Assign a custom, meaningful end-state
  </Card>

  <Card title="Structured Result" icon="database">
    Return JSON data using a custom schema
  </Card>

  <Card title="Workflow Clarity" icon="flag">
    Clearly define how and why a run finished
  </Card>
</CardGroup>

Every workflow should have at least one Output Node to properly conclude execution. Additionally, every AI Task node should be connected to an output node to handle failures.

***

## Configuration

### Outcome Labels

**Outcome Labels** define the possible states your execution can end in.
They work like exit codes or status tags that answer: *“How did this run finish?”*

By default, we return `success` or `failure`, but you can define custom Outcome Labels that reflect your real business logic.

#### Common Patterns

* **Default:**
  `success`, `failure`

* **Business Logic States:**
  `item_purchased`, `out_of_stock`, `login_required`

* **Decision Outcomes:**
  `approved`, `rejected`, `needs_review`

#### Example Outcome Labels

For an e-commerce checkout agent, you might define:

* `purchase_completed`
* `payment_failed`
* `item_unavailable`
* `session_expired`

#### Best Practices for Outcome Labels

* Use clear, descriptive names (e.g., `payment_completed` instead of `done`)
* Define all realistic end states your agent might encounter
* Keep naming consistent across similar workflows
* Use `snake_case`

***

### Result Schema

Alongside an Outcome Label, an Output Node can return **structured data** using a **Result Schema**. This is a custom JSON Schema that defines the shape of the data you expect when this Output Node is reached.

Using Result Schemas ensures outputs are predictable and machine-readable, and makes it easy to consume execution results via API or SDKs.

Our schema format follows [OpenAI Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) specification (a subset of JSON Schema).

#### When to Use a Result Schema

Use a custom Result Schema when:

* You need structured data in a specific format
* Other services or downstream systems expect defined fields
* You want consistent outputs across executions and environments
* You’re extracting multiple values (prices, names, URLs, IDs, etc.)

#### Example Result Schema

A possible schema for a product-scraping agent:

```json theme={null}
{
  "type": "object",
  "properties": {
    "product_name": {
      "type": "string",
      "description": "The name of the product"
    },
    "price": {
      "type": "number",
      "description": "The product price"
    },
    "in_stock": {
      "type": "boolean",
      "description": "Whether the product is available"
    }
  },
  "additionalProperties": false,
  "required": ["product_name", "price", "in_stock"]
}
```

#### Result Schema Requirements

When defining a Result Schema, follow these rules:

* All **object types** must include `"additionalProperties": false`
* All properties should be listed in the `"required"` array
* Use the `"description"` field to guide the AI in populating values correctly

***

## Tips

* **Start Simple:**
  Begin with Outcome Labels only. Add a Result Schema once you know what data you need to return.

* **Plan End States First:**
  Think through all the ways your agent might finish (success, partial success, failures, edge cases) and design Outcome Labels accordingly.

* **Test Outcomes:**
  Run test executions to verify the workflow can reach each defined Outcome Label.

* **Validate Your Schema:**
  Use the examples in the docs as a reference and ensure your JSON Schema is valid before relying on it in production.

***

## API / YAML Reference

When configuring an Output node via the API, SDK, or MCP, use the following type identifier:

| Field     | Value    |
| --------- | -------- |
| Node type | `output` |

Example `settings.yaml`:

```yaml theme={null}
label: "Result"
type: output
outcomes:
  - success
  - failure
```

The node's result schema (if any) is stored in a separate `schema.json` file in the same directory.


# Agent Profiles
Source: https://docs.asteroid.ai/fundamentals/profiles

Manage browser automation profiles, authentication credentials, 2FA, and cookies persistence for consistent execution environments

Agent profiles in Asteroid provide a way to create consistent, reusable browser automation environments. Each profile contains configuration settings for proxies and captcha solving, along with associated credentials for authentication across different websites and services.

<CardGroup>
  <Card title="Agent Profiles" icon="browser" href="#agent-profiles">
    Configure browser settings, proxy configurations, and automation parameters
  </Card>

  <Card title="Credentials Management" icon="key" href="#credentials-management">
    Securely store and manage authentication data for your automation workflows
  </Card>

  <Card title="Profile Pools" icon="layer-group" href="#profile-pools">
    Group multiple profiles for automatic selection and credential rotation
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Create an Agent Profile">
    Use the Asteroid dashboard to create a new agent profile with your desired proxy settings, captcha solver configuration, and automation features.
    You can also create profiles via the API and SDKs:

    * [Create an agent profile](/api-reference/endpoints/agent-profiles/create-agent-profile)
    * [TypeScript SDK](/sdks/typescript)
    * [Python SDK](/sdks/python)
  </Step>

  <Step title="Add Credentials (Optional)">
    If your automation requires authentication, add credentials to your profile through the dashboard's credential management interface.
  </Step>

  <Step title="Execute with Profile">
    Execute your agent using the profile through either the dashboard or SDK:

    <Tabs>
      <Tab title="Dashboard">
        1. Navigate to the **Agents** section in your Asteroid dashboard
        2. Select the agent you want to execute
        3. Choose your created profile from the dropdown next to Run Agent
        4. Provide your input data and click Run
        5. Monitor the execution progress in real-time
      </Tab>

      <Tab title="SDK">
        Use the SDK to programmatically execute your agent with the specific profile:

        <CodeGroup>
          ```ts TypeScript theme={null}
          import { client, agentExecutePost } from 'asteroid-odyssey';

          client.setConfig({
            headers: { 'X-Asteroid-Agents-Api-Key': 'your-api-key' },
          });

          const { data } = await agentExecutePost({
            path: { agentId: 'YOUR_AGENT_ID' },
            body: {
              inputs: { input: 'your data' },
              agentProfileId: 'YOUR_AGENT_PROFILE_ID',
            },
          });
          ```

          ```python Python theme={null}
          import os
          from asteroid_odyssey import Configuration, ApiClient
          from asteroid_odyssey.api.agents_api import AgentsApi
          from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

          config = Configuration(api_key={"ApiKeyAuth": "your-api-key"})
          with ApiClient(config) as api_client:
              agents_api = AgentsApi(api_client)
              response = agents_api.agent_execute_post(
                  agent_id="your-agent-id",
                  agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                      inputs={"input": "your data"},
                      agent_profile_id="your-profile-id",
                  ),
              )
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Agent Profiles

Agent profiles define the browser automation environment settings that will be used during execution. These profiles ensure consistent behavior across different automation runs and provide isolation between different use cases.

### Profile Configuration

Each agent profile contains the following key components:

<AccordionGroup>
  <Accordion title="Proxy Settings">
    * **Proxy Country Code**: Two-letter lowercase country code for proxy location (e.g., "us", "uk", "de")
    * **Proxy Type**: Type of proxy connection to use
    * **Persistent IP**: Whether to maintain the same IP address across requests
      <Warning> Persistent IP's can only be used with a US proxy and do not support Mobile proxies or Captcha Solving </Warning>
  </Accordion>

  <Accordion title="Automation Features">
    * **Captcha Solver**: Enable/disable automatic captcha solving capabilities
    * **Cookies**: Profiles can preload and persist site cookies. You can create profiles with cookies, and add/remove cookies later via the SDK. Useful for keeping authenticated sessions or site preferences.
    * **Cache Persistence**: Control whether browser cache and cookies are retained between executions. When enabled (default), the profile maintains session state, cookies, and cached data across runs for seamless continuity. When disabled, each execution starts with a fresh browser state. Cache can be manually cleared at any time using the "Clear Cache" option.
  </Accordion>
</AccordionGroup>

<Info>
  Agent profiles can be created and managed through the dashboard, the API, and SDKs.
  See [Create an agent profile](/api-reference/endpoints/agent-profiles/create-agent-profile), [List agent profiles](/api-reference/endpoints/agent-profiles/list-agent-profiles), [TypeScript SDK](/sdks/typescript), and [Python SDK](/sdks/python).
</Info>

<Warning>
  Deleting a profile will affect any executions that reference it. Ensure no active automations depend on the profile before deletion.
</Warning>

## Credentials Management

Store credentials securely by linking them to an **agent profile**.

In the **Vault** section, enter the credential name and value. The platform mirrors vault names into **placeholder tokens** of the form `##CREDENTIAL_NAME##` (uppercase with underscores matching how the name is normalized for substitution).

Your automations can use these placeholders in:

* **AI Task instructions** (for tools that consume templated prompts—still avoid pasting raw secrets into chat logs).
* **Playwright scripts** — the runtime injects decrypted values only into browser automation inputs, not into arbitrary shell or file tools, to reduce accidental leakage.

This injection path is separate from **`__PLACEHOLDER__` templates** in **scripted mode** scripts on AI Task nodes. Those systems resolve values from LLM reasoning or structured variable definitions, not from the vault’s `##...##` map. See [AI Task node](/fundamentals/nodes/ai-task).

For more information, see [Security](/support-security/security).

<Warning>Never paste real secrets into instructions or scripts as plain text—use vault placeholders or dedicated variable mechanisms instead.</Warning>

## Profile Pools

Profile pools allow you to group multiple agent profiles together so the system automatically selects one at execution time. Instead of manually choosing a single profile for each execution, you point to a pool and Asteroid picks the best available profile for you.

<Info>
  Profile pools can be created and managed through the dashboard, the API, and SDKs.
  See [Create a pool](/api-reference/endpoints/agent-profile-pools/create-agent-profile-pool), [List pools](/api-reference/endpoints/agent-profile-pools/list-agent-profile-pools), [Update a pool](/api-reference/endpoints/agent-profile-pools/update-agent-profile-pool), and [Add pool members](/api-reference/endpoints/agent-profile-pools/add-pool-members).
</Info>

### Why Use Profile Pools?

Profile pools solve common challenges in browser automation:

* **Avoid credential conflicts**: Prevent simultaneous use of the same account across multiple executions
* **Distribute load**: Spread requests across multiple accounts to respect rate limits
* **Improve reliability**: Automatically use alternative profiles when one is unavailable
* **Reduce friction**: Eliminate manual profile selection for each execution

<Info>
  Think of profile pools as a "rotation strategy" for your automation credentials. Rather than hard-coding a specific profile, you define a pool of profiles and let the system intelligently choose which one to use.
</Info>

### Selection Strategies

Profile pools support two selection strategies that determine which profile gets picked for each execution:

<AccordionGroup>
  <Accordion title="Least Recently Used (Default)">
    Selects the profile that hasn't been used for the longest time. This distributes load evenly across all profiles in the pool.

    **Best for:**

    * Spreading requests across accounts to avoid rate limits
    * Rotating through multiple accounts fairly
    * Scenarios where you want to minimize repeated use of the same profile

    **Example**: If you have profiles A, B, and C, and the last execution used profile B, the next execution will prefer profile A (if it was used longest ago), then C, then B.
  </Accordion>

  <Accordion title="Most Recently Used">
    Selects the most recently used profile. This concentrates activity on fewer "warm" profiles.

    **Best for:**

    * Keeping sessions warm and browser state cached
    * Reusing authenticated sessions when possible
    * Scenarios where session continuity matters more than distribution

    **Example**: If profile B was just used successfully, the next execution will try to use profile B again to maintain session state.
  </Accordion>
</AccordionGroup>

### Concurrent Use Control

Control whether a profile can be selected while it's already being used by another running execution:

* **`allowConcurrentUse: false` (default)** — A profile that is currently tied to an active execution will be skipped. If all profiles in the pool are busy, the execution request fails immediately.
  * **Best for:** Strict credential isolation where you never want the same account used simultaneously
  * **Use when:** The target site enforces per-session limits or you need guaranteed isolation

* **`allowConcurrentUse: true`** — Any profile can be selected regardless of whether it's currently in use by another execution.
  * **Best for:** High-throughput scenarios where the target site doesn't enforce strict per-session limits
  * **Use when:** You want maximum availability and don't need credential isolation

<Warning>
  If `allowConcurrentUse` is set to `false` and all profiles in the pool are currently in use, new execution requests will fail with an error indicating no profiles are available. Consider adding more profiles to your pool or enabling concurrent use.
</Warning>

### Quick Start

<Steps>
  <Step title="Create a Pool">
    Create a new profile pool via the platform or programmatically:

    <Tabs>
      <Tab title="Platform">
        1. Navigate to **Agent Profiles** in your Asteroid dashboard
        2. Click **Create Profile Pool**
        3. Provide a unique name for your pool
        4. Choose your selection strategy (Least Recently Used or Most Recently Used)
        5. Configure concurrent use setting
        6. Click **Create**
      </Tab>

      <Tab title="SDK">
        Use the platform today, or call the profile pool endpoints directly:

        * [Create an agent profile pool](/api-reference/endpoints/agent-profile-pools/create-agent-profile-pool)
        * [List agent profile pools](/api-reference/endpoints/agent-profile-pools/list-agent-profile-pools)
        * [Get an agent profile pool](/api-reference/endpoints/agent-profile-pools/get-agent-profile-pool)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add Profiles to the Pool">
    Select existing agent profiles to include in your pool:

    <Tabs>
      <Tab title="Platform">
        1. Open your newly created profile pool
        2. Click **Add Profiles**
        3. Select the agent profiles you want to include
        4. Click **Add to Pool**
      </Tab>

      <Tab title="SDK">
        Add pool members through the profile pool API pages:

        * [Add pool members](/api-reference/endpoints/agent-profile-pools/add-pool-members)
        * [List pool members](/api-reference/endpoints/agent-profile-pools/list-pool-members)
        * [Remove pool members](/api-reference/endpoints/agent-profile-pools/remove-pool-members)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Execute with the Pool">
    Use the pool ID when triggering an execution instead of specifying a profile ID:

    <Tabs>
      <Tab title="Platform">
        1. Navigate to your agent
        2. Click **Run Agent**
        3. Select your profile pool from the dropdown (instead of a single profile)
        4. Provide your input data and click **Run**
        5. The system will automatically select an available profile from the pool
      </Tab>

      <Tab title="SDK">
        Profile pools are available through the platform and the API endpoint pages.

        Use [Execute an agent](/api-reference/endpoints/agents/execute-an-agent) and pass `agentProfilePoolId` in the request body when you want the API to choose a profile from a pool.
      </Tab>
    </Tabs>
  </Step>
</Steps>

### Important Constraints

<AccordionGroup>
  <Accordion title="Mutual Exclusivity">
    The API treats `agentProfileId` and `agentProfilePoolId` as mutually exclusive. You must specify one or the other, but not both.

    **Correct:**

    ```json theme={null}
    { "agentProfileId": "profile-123" }

    { "agentProfilePoolId": "pool-456" }
    ```

    **Incorrect:**

    ```json theme={null}
    {
      "agentProfileId": "profile-123",
      "agentProfilePoolId": "pool-456"
    }
    ```
  </Accordion>

  <Accordion title="Organization Scope">
    * All profiles in a pool must belong to the same organization
    * Pool names must be unique within an organization
    * Profiles cannot be added to pools from different organizations
  </Accordion>

  <Accordion title="Availability Requirements">
    * A pool must contain at least one profile to be used for executions
    * If `allowConcurrentUse` is `false` and all profiles are in use, execution requests will fail
    * Removing the last profile from a pool will prevent new executions from using that pool
  </Accordion>

  <Accordion title="Recommended Pool Size">
    The number of profiles in your pool should match your expected parallelism. For example, if you need to run 5 agent executions simultaneously, you need at least 5 profiles in the pool. We recommend having 1-2 extra profiles as buffer for peak loads.
  </Accordion>
</AccordionGroup>

<Info>
  Profile pools work seamlessly with all profile features including credentials, cookies, TOTP secrets, and cache persistence. The selected profile's configuration applies to the execution as if you had manually chosen that specific profile.
</Info>

## 2FA - TOTP Secrets

Set up Two-Factor Authentication (2FA) using Time-based One-Time Passwords (TOTP) with our TOTP tool. Asteroid supports all standard TOTP providers including Google Authenticator, Microsoft Authenticator, Authy, 1Password, and others.

<Info>
  TOTP provides an additional layer of security by generating time-based codes that expire after 30 seconds. This prevents unauthorized access even if your password is compromised. Our TOTP tool works with any service that provides a standard TOTP secret key.
</Info>

<Steps>
  <Step title="Obtain TOTP Secret Key">
    Get your TOTP secret key from your service provider. The process varies by provider:

    **Google Account:**

    1. Navigate to your [Google Account](https://myaccount.google.com/) → **Security**
    2. Go to **2-Step Verification** → **Authenticator app** → **Set up authenticator**
    3. Click **Can't scan it?** to reveal the 32-character setup key

    **Other Popular Services:**

    * **Microsoft Authenticator**: Microsoft Account → Security → Advanced security options → Add sign-in method
    * **GitHub**: Settings → Password and authentication → Two-factor authentication → Set up using an app
    * **AWS**: IAM Console → Users → Security credentials → Assign MFA device
    * **Discord**: User Settings → My Account → Enable Two-Factor Auth
    * **Most Services**: Look for "manual entry", "can't scan", or "setup key" options that reveal the secret key
    * The key is typically a 16-32 character alphanumeric string (Base32 encoded)
  </Step>

  <Step title="Create TOTP Secret in Vault">
    In your Agent Profile's **Vault**, create a new TOTP Secret credential and paste the secret key as the credential value. You can name your credential anything as long as it has the prefix `TOTP_`.
  </Step>

  <Step title="Add TOTP Tool to Agent">
    Add the **Generate TOTP Secret** tool to the agent node where you want to use TOTP.
  </Step>

  <Step title="Test Configuration">
    Execute your agent with the configured profile.
  </Step>
</Steps>

## Inbox Email

Every agent profile is automatically provisioned with its own email inbox at `{prefix}@agentmail.asteroid.ai`. The default prefix is the profile's UUID, and you can override it by setting an **Inbox Email Prefix** on the profile (for example, `acme-support` resolves to `acme-support@agentmail.asteroid.ai`).

Agents can read and send from this inbox by enabling the `send_mail` and `get_mail` tools on AI Task nodes (under the **Communication** capability). A common use case is **receiving email login / verification codes** — instruct the agent to poll its inbox until the code arrives, then extract it and continue the flow.

See [Agent Emails](/fundamentals/emails) for the full guide, including a prompt template for catching verification codes.

## Cookies on Agent Profiles

Profiles can store website cookies to persist authenticated sessions and preferences across runs. Add cookies when creating a profile, or manage them later via the API.

```ts theme={null}
type Cookie = {
  id?: string;       // present on existing cookies
  name: string;      // display name
  key: string;       // cookie name
  value: string;     // cookie value
  domain: string;    // e.g. '.example.com'
  secure: boolean;
  http_only: boolean;
  same_site: 'Strict' | 'Lax' | 'None';
  expiry?: string;   // ISO 8601
  created_at: string; // ISO 8601
}
```

### SDK Methods

See the SDK for creation and management details: [TypeScript SDK](/sdks/typescript) and [Python SDK](/sdks/python). The Asteroid SDK provides a simple interface for using agent profiles during execution:

<CodeGroup>
  ```ts TypeScript theme={null}
  import { client, agentExecutePost } from 'asteroid-odyssey';

  client.setConfig({
    headers: { 'X-Asteroid-Agents-Api-Key': 'YOUR_API_KEY' },
  });

  // Execute an agent with a specific profile
  const { data } = await agentExecutePost({
    path: { agentId: 'YOUR_AGENT_ID' },
    body: {
      inputs: { key: 'value' },
      agentProfileId: 'YOUR_AGENT_PROFILE_ID',
    },
  });
  ```

  ```python Python theme={null}
  import os
  from asteroid_odyssey import Configuration, ApiClient
  from asteroid_odyssey.api.agents_api import AgentsApi
  from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

  config = Configuration(api_key={"ApiKeyAuth": "YOUR_API_KEY"})
  with ApiClient(config) as api_client:
      agents_api = AgentsApi(api_client)
      # Execute an agent with a specific profile
      response = agents_api.agent_execute_post(
          agent_id="YOUR_AGENT_ID",
          agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
              inputs={"key": "value"},
              agent_profile_id="YOUR_AGENT_PROFILE_ID",
          ),
      )
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Profile Not Found">
    **Error**: Agent profile not found

    **Causes**:

    * Profile was deleted
    * Incorrect profile ID or name
    * Profile belongs to different organization

    **Solutions**:

    * Verify the profile ID/name is correct
    * Check organization access permissions
    * Use the list profiles API to confirm available profiles
  </Accordion>
</AccordionGroup>

***

<Note>
  For additional help with agent profiles and credentials, consult the [SDK documentation](/sdks/setup) or contact our [support](/support-security/support).
</Note>


# Agent Settings
Source: https://docs.asteroid.ai/fundamentals/settings

Configure your agent settings and preferences in the `Settings` panel

Agent settings control how your agent executes tasks and behaves during automation. These settings are **agent-specific** and apply to all executions of this agent.

<Info>
  **Agent Settings vs. Agent Profiles**

  * **Agent Settings** (this page): Control agent behavior, execution limits, and agent-level configuration. These settings are tied to the agent itself.

  * **Agent Profiles**: Control browser environment settings like proxies, cookies, cache persistence, and credentials. Profiles are reusable across multiple agents. See [Agent Profiles](/fundamentals/profiles) for profile configuration.
</Info>

## Agent-Level Configuration

<CardGroup>
  <Card title="Agent Behavior" icon="robot">
    Control how your agent executes tasks and interacts with webpages
  </Card>

  <Card title="Execution Limits" icon="clock">
    Set maximum steps and timeout limits
  </Card>

  <Card title="LLM Settings" icon="brain">
    Customize AI behavior and response generation
  </Card>

  <Card title="Advanced Features" icon="toggle-on">
    Enable optional features and performance optimizations
  </Card>
</CardGroup>

## Agent Settings

<AccordionGroup>
  <Accordion title="Agent Behavior">
    <Tabs>
      <Tab title="Execution Limits">
        **Maximum Steps** `10-200`

        Maximum number of steps the agent can take during execution

        **Execution Timeout** `1-120 minutes`

        Maximum execution time before the agent automatically stops
      </Tab>

      <Tab title="Input Method">
        **Text Input Method**

        Choose how the agent inputs text into web forms:

        * **Auto**: Automatically detect the best input method
        * **Type**: Simulate natural typing behavior
        * **Paste**: Direct paste for faster input
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Viewport Settings">
    **Viewport Width** `100-2000 pixels`

    Browser viewport width in pixels (100-2000)

    **Viewport Height** `100-2000 pixels`

    Browser viewport height in pixels (100-2000)

    <Tip>
      Use standard resolutions like 1920x1080 for desktop or 375x667 for mobile testing
    </Tip>
  </Accordion>

  <Accordion title="Feature Toggles">
    **Parallel Tool Calls**

    Allow agent to execute multiple tools simultaneously for faster performance
  </Accordion>
</AccordionGroup>

***

## Profile-Level Settings

The following settings are configured in **Agent Profiles**, not in agent settings. Profiles allow you to reuse browser environment configurations across multiple agents.

<AccordionGroup>
  <Accordion title="Proxy Configuration">
    **Proxy settings** (country, type, persistent IP) are configured in [Agent Profiles](/fundamentals/profiles#proxy-settings).

    <Info>
      Configure proxy settings when creating or editing an agent profile. This allows you to reuse the same proxy configuration across multiple agents.
    </Info>
  </Accordion>

  <Accordion title="Cache & Cookie Persistence">
    **Cache persistence** and **cookie management** are configured in [Agent Profiles](/fundamentals/profiles#automation-features).

    <Info>
      Enable cache persistence in your agent profile to maintain browser state, cookies, and cached data between executions. This is separate from agent-level cache clearing.
    </Info>
  </Accordion>

  <Accordion title="Credentials & Authentication">
    **Credentials, cookies, and 2FA secrets** are managed in [Agent Profiles](/fundamentals/profiles#credentials-management).

    <Info>
      Store authentication credentials securely in agent profiles. These can be reused across multiple agents that need the same authentication.
    </Info>
  </Accordion>
</AccordionGroup>

***

## Agent Management

<CardGroup>
  <Card title="Agent Identity" icon="user">
    Manage agent name and organizational settings
  </Card>

  <Card title="Data Management" icon="database">
    Clear agent-level cache and stored data
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="Agent Identity">
    **Change Agent Name**

    Update the display name for this agent

    **Organization**

    Set or change the organization that owns this agent. Anyone with access to this organization will be able to see and use this agent.
  </Accordion>

  <Accordion title="Data Management">
    **Clear Browser Cache**

    Clear the browser cache for this agent. This removes:

    * All cached data and files
    * Stored cookies and sessions
    * Browser state and preferences

    <Info>
      This clears agent-level cache. For profile-level cache persistence settings, see [Agent Profiles](/fundamentals/profiles#automation-features).
    </Info>
  </Accordion>

  <Accordion title="Agent Deletion">
    **Delete Agent**

    Permanently remove this agent, including:

    * All previous versions
    * All execution history
    * All associated data

    <Warning>
      This action cannot be undone. Consider exporting important data before deletion.
    </Warning>
  </Accordion>
</AccordionGroup>


# Transitions
Source: https://docs.asteroid.ai/fundamentals/transitions

How workflows decide what happens next

Transitions define **how your workflow moves from one node to the next**.
They represent the routing logic of your automation and determine which path the agent follows under different conditions.

Asteroid provides **three types of transitions**, each designed for a different kind of decision-making.

<Card title="AI Transition" icon="brain">
  Chosen by AI based on the agent’s analysis of the page and task context
</Card>

<Card title="Selector Transition" icon="code">
  Jumps to the next node the moment a specific element appears
</Card>

<Card title="Outcome Success" icon="check">
  Used by nodes that deterministically signal successful completion
</Card>

***

## API / YAML Reference

When configuring transitions via the API, SDK, or MCP, use the following type identifiers:

| Transition          | YAML `type` value | Used with           |
| ------------------- | ----------------- | ------------------- |
| AI Transition       | `ai`              | AI Task nodes       |
| Selector Transition | `selector`        | AI Task nodes       |
| Outcome Success     | `outcome_success` | Deterministic nodes |

***

## Types of Transitions

### AI Transitions

AI Transitions are the most flexible and expressive transition type.
They allow **AI nodes** to choose the next step based on reasoning, context, and analysis of the current browser state.

**When to use:**

* When the next step depends on **page content** or **semantic understanding**
* When multiple paths are possible and the AI must **choose intelligently**
* For workflows requiring reasoning, interpretation, or decisions based on extracted information

**Example:**

```mermaid theme={null}
flowchart TB
    A[AI Task node] -->|AI Transition| B[Next node]
    A[AI Task node] -->|AI Transition| C[Failure node]
```

**YAML example:**

```yaml theme={null}
transitions:
  - to: next_node
    type: ai
  - to: failure_output
    type: ai
```

### Selector Transitions

Selector Transitions are **deterministic**.
They activate **immediately when a specific selector becomes visible or present** on the page.

**When to use:**

* When waiting for a **specific UI element** to appear
* As a **guardrail** for navigation changes or modal detection
* For flows that require deterministic, event-driven branching

**Use carefully:**
Selector transitions should be used **sparingly**, only when you are 100% certain about the structure and stability of the target element.

**Example selector:**

```
button:has-text("Submit")
```

**YAML example:**

```yaml theme={null}
transitions:
  - to: confirmation_page
    type: selector
    name: "Submit Button Visible"
    selector: "button:has-text('Submit')"
```

### Outcome Success Transitions

Outcome Success transitions are used after **deterministic nodes** that explicitly return either a success or failure.

**When to use:**

* Any deterministic node that returns a clear "success" state

**YAML example:**

```yaml theme={null}
transitions:
  - to: next_node
    type: outcome_success
```

***

## Best Practices

### Choosing the Right Transition

Use the appropriate transition type for each decision point:

* **AI Transitions:**
  For dynamic routing based on page content, extracted information, or reasoning.

* **Selector Transitions:**
  For immediate, deterministic reactions to UI events.
  *Use cautiously, only when element type, structure, and behavior are known and stable.*

* **Outcome Success Transitions:**
  For deterministic steps with clearly defined success states.

### Failure Transitions

<Warning>
  **Critical: AI Task Node Failure Paths**

  **All AI Task nodes must have a connection to an Output node via a failure path.** This is essential for proper error handling and workflow completion.

  * Every AI Task node should have at least one transition (typically an AI Transition) that connects to an Output node configured for failure scenarios
  * Without a failure path, your workflow may not properly handle errors, unexpected conditions, or edge cases
  * This ensures that unexpected conditions, missing elements, or interpretation errors are surfaced correctly in your workflow
</Warning>


# LLM Integration
Source: https://docs.asteroid.ai/get-started/llm-integration

Canonical resources for integrating LLM agents with Asteroid: API specs, auth requirements, llms.txt, llms-full.txt, skill.md, and MCP setup.

Use this page as the single starting point for using your coding agents to integrate with Asteroid.

## Integration Contract

* **Base URL:** `https://odyssey.asteroid.ai/agents/v2`
* **Authentication header:** `X-Asteroid-Agents-Api-Key: <your-api-key>`
* **OpenAPI specs:**
  * `https://odyssey.asteroid.ai/agents/v2/openapi.yaml`
  * `https://odyssey.asteroid.ai/webhooks/openapi.json`
* **Primary flow:** execute agent -> poll execution -> inspect activities/result -> send user message if paused

## AI Discovery Endpoints

* [https://docs.asteroid.ai/llms.txt](https://docs.asteroid.ai/llms.txt)
* [https://docs.asteroid.ai/llms-full.txt](https://docs.asteroid.ai/llms-full.txt)
* [https://docs.asteroid.ai/skill.md](https://docs.asteroid.ai/skill.md)

## What Each File Does

### `llms.txt` (directory-level index)

Use this for fast discovery of pages and descriptions.

* Lists docs pages in a machine-friendly format
* Includes API specification links when configured
* Helps agents find the right page before reading details

### `llms-full.txt` (full context snapshot)

Use this when an agent needs broad context across the entire documentation set.

* Combines the full docs corpus into one file
* Useful for indexing pipelines and long-form retrieval
* Larger payload than `llms.txt`, so use when broad context is required
* Best option when agents need platform context around reliability, security, compliance, and high-scale production workloads

### `skill.md` (capability contract)

Use this for action planning and tool behavior.

* Describes what Asteroid can do
* Defines required inputs and constraints
* Improves reliability when agents execute workflows
* Helps AI systems reason about regulated operational use cases, including HIPAA healthcare workflow automation

## Recommended Usage

<Steps>
  <Step title="Load discovery files first">
    Start with `llms.txt`, then use `skill.md` for capability and constraint guidance.
  </Step>

  <Step title="Use llms-full.txt when needed">
    Use `llms-full.txt` for broad indexing or when your retrieval flow benefits from one complete context document.
  </Step>

  <Step title="Connect MCP for live actions">
    Follow [MCP Setup](/mcp/setup) to let coding assistants perform live operations against Asteroid.
  </Step>
</Steps>

## Add to Agent Tooling

To add this docs skill to compatible tooling:

```bash theme={null}
npx skills add https://docs.asteroid.ai
```

## Important Notes

* These files are available to external agents only when docs are publicly accessible.
* If you use a reverse proxy, forward `/skill.md` and `/.well-known/skills/*` to the Mintlify origin without caching.
* Mintlify auto-generates `llms.txt` and `llms-full.txt`. Prefer auto-generation unless you need strict custom control.

## Related Resources

<CardGroup>
  <Card title="MCP Setup" icon="plug" href="/mcp/setup">
    Connect Asteroid MCP to Cursor, Claude Code, and other clients
  </Card>

  <Card title="API Quickstart" icon="cloud" href="/api-reference/quickstart">
    Run your first API call with the required auth and base URL
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.asteroid.ai/get-started/quickstart

Build your first agent in minutes

Learn how to create, configure, run, and monitor your first agent using the [Asteroid Platform](https://platform.asteroid.ai/).

## Steps

<Steps>
  <Step title="Create">
    <Card title="Create Page" icon="plus">
      After signing in, create a new agent and describe the automation task you want it to perform.
    </Card>

    Start with a clear, high-level goal for the agent, then outline the step-by-step instructions it should follow. For example:

    ```
    Fill in the doctor note information in my EHR portal.

    1. Go to https://mediflowhealth.life/login
    2. Log in with the email and password available to you
    3. Click the “Patients” button
    4. Select {{.NAME}}
    5. Click “New Consultation”
    6. Fill out the consultation form using the following doctor note: {{.DOCTOR_NOTE}}
    7. Click “Create” to finish
    ```

    Notice how you can:

    * Provide credentials for the agent to use
    * Declare variables that will be supplied at runtime

    <Info>
      Learn more about [Agent Profiles](/fundamentals/profiles) and [Dynamic Variables](/fundamentals/nodes/ai-task#dynamic-variables).
    </Info>
  </Step>

  <Step title="Configure">
    <Card title="Builder Page" icon="wrench">
      Once your agent is created, you can refine its behavior in the Graph Builder.
    </Card>

    The Builder allows you to customize all aspects of your agent, including:

    * **Agent Name** — Give it a clear, meaningful name
    * **Nodes** — Break the workflow into smaller, deterministic subtasks
    * **Transitions** — Define the logical sequence the agent should follow

    The default two-node agent is a great starting point. You can always return to this page as your automation grows more complex.

    <Info>
      For a deeper dive into our graph-based approach, see the [Graph Agents](/fundamentals/graph-agents) guide.
    </Info>
  </Step>

  <Step title="Run">
    <Card title="Run Config" icon="cog">
      Before launching a run, configure variables, credentials, and environment options.
    </Card>

    Click **Run Agent** in the Builder to open the run configuration modal.
    Here you can:

    * Select or create an Agent Profile (credentials, browser settings, etc.)
    * Provide values for any dynamic variables referenced in your node instructions

    Once everything is set, trigger the run.

    <Info>
      You can also upload [Files](/fundamentals/files) for your agent to reference during execution.
    </Info>
  </Step>

  <Step title="Monitor">
    <Card title="Execution Page" icon="eye">
      Watch your agent in action with real-time monitoring.
    </Card>

    After the run starts, you'll be taken to the **Execution** page, where you can observe the agent's behavior live.
    From here, you can:

    * Send messages to the agent
    * Pause or cancel the run
    * Interact with the browser directly
    * Apply live edits to the graph
  </Step>

  <Step title="Iterate & Improve">
    <Card title="Stats Page" icon="chart-line">
      Review past outcomes to understand what worked and what didn't.
    </Card>

    After your first run, review results on the **Executions** page: check the timeline, browser snapshots, and agent reasoning to see what happened.

    **When things go wrong:**

    * **Agent couldn't find an element**: Make instructions more specific
    * **Agent took the wrong action**: Clarify instructions or add edge case handling
    * **Agent got stuck**: Add clearer success criteria or break into smaller nodes

    **Improve your agent:**

    * Refine instructions based on what you observed
    * Add edge cases and failure paths
    * Split complex nodes into smaller, focused ones
    * Test with different dynamic variable values

    **Best Practices:**

    * **Start simple**: Get a basic version working first, then add complexity
    * **Test incrementally**: Make small changes and test after each modification
    * **Use descriptive names**: Name nodes and variables clearly so the graph is self-documenting
    * **Document edge cases**: Add notes about known variations in your instructions

    <Info>
      For more guidance, see [Graph Agents](/fundamentals/graph-agents) for design best practices and [Output Nodes](/fundamentals/nodes/output) for handling different outcomes.
    </Info>
  </Step>
</Steps>

<Card title="Start Building Now!" icon="play" href="https://platform.asteroid.ai">
  Ready to build your first automation? Open the Asteroid platform and start building.
</Card>


# Browser & Computer Use Platform
Source: https://docs.asteroid.ai/get-started/welcome

Build reliable browser and computer use agents with Asteroid. Automate web workflows, including claims, prior auth, revenue cycle, and EHR tasks.

Asteroid agents execute complex, multi-step processes with reliability, observability, and enterprise-grade scale built in. Whether you're extracting data, completing forms, or orchestrating end-to-end operational workflows, Asteroid helps you automate faster and ship with confidence.

Asteroid is trusted in production by hundreds of startups and enterprises to run hundreds of thousands of executions per week across thousands of portals, including regulated use cases like HIPAA healthcare workflow automation.

***

## Quick Links

<CardGroup>
  <Card title="Quickstart" icon="play" href="/get-started/quickstart">
    Build and launch your first agent in minutes
  </Card>

  <Card title="LLM Integration" icon="sparkles" href="/get-started/llm-integration">
    Use `llms.txt`, `llms-full.txt`, `skill.md`, and OpenAPI for assistant-first integrations
  </Card>

  <Card title="API Reference" icon="cloud" href="/api-reference">
    Explore endpoints, schemas, auth requirements, and integration workflows
  </Card>

  <Card title="Fundamentals" icon="book-open" href="/fundamentals/graph-agents">
    Learn the core concepts behind graph-based agents
  </Card>

  <Card title="Healthcare Automation" icon="shield-check" href="/healthcare-workflow-automation/overview">
    Explore HIPAA-sensitive workflows for claims, prior auth, RCM, and EHR operations
  </Card>

  <Card title="SDKs" icon="code" href="/sdks/setup">
    Integrate agents into your product or backend systems
  </Card>

  <Card title="What's New" icon="sparkles" href="/whats-new/changelog">
    See the latest updates and improvements
  </Card>
</CardGroup>

***

## Example Use Cases

Asteroid agents streamline operational workflows by automating complex browser interactions end-to-end.

Common applications include:

* Form filling and structured data entry
* Scheduled data extraction and reporting
* Prior authorization automation
* Claims processing automation
* Revenue cycle automation
* EHR automation

Below are real-world examples across industries:

<AccordionGroup>
  <Accordion title="Insurance Carrier Quoting">
    Automate interactions with carrier portals to:

    * Enter customer and policy information
    * Retrieve and compare quotes across carriers
    * Submit applications and track their status
    * Extract policy details and coverage breakdowns
  </Accordion>

  <Accordion title="Healthcare Systems Integration">
    Securely connect to EHR portals to:

    * Retrieve patient records and medical history
    * Update treatment plans or medication details
    * Manage appointment schedules and follow-ups
    * Track insurance claims and billing status
  </Accordion>

  <Accordion title="Property Management Systems">
    Streamline property-ops workflows by:

    * Fetching tenant and lease information
    * Monitoring maintenance requests and work orders
    * Tracking financial and occupancy metrics
    * Updating rental rates and availability
  </Accordion>

  <Accordion title="Supply Chain Portal Integration">
    Coordinate logistics and vendor systems to:

    * Track inventory levels across suppliers
    * Monitor shipment progress and delivery timelines
    * Extract pricing and availability data
    * Update order status and fulfillment information
  </Accordion>
</AccordionGroup>


# Claims Processing Automation
Source: https://docs.asteroid.ai/healthcare-workflow-automation/claims-processing

Automate repetitive claims workflows such as eligibility checks, submission, status retrieval, and reconciliation.

Use Asteroid to automate high-volume claims workflows while preserving controls for exception cases.

## Common workflows

* Perform eligibility checks before claim submission
* Execute claim submission steps across payer systems
* Retrieve claim status updates and denial reasons
* Reconcile outcomes with internal systems and queues

## Where agents help most

* Standardized repetitive claim operations
* Multi-portal workflows with similar action patterns
* Status and reconciliation loops that consume team time

## Related healthcare use cases

* [Prior Authorization](/healthcare-workflow-automation/prior-authorization)
* [Revenue Cycle](/healthcare-workflow-automation/revenue-cycle)
* [Healthcare Workflow Automation overview](/healthcare-workflow-automation/overview)


# EHR Operations Automation
Source: https://docs.asteroid.ai/healthcare-workflow-automation/ehr-operations

Automate high-volume EHR workflows including intake, chart updates, scheduling, and downstream operational follow-up.

Use Asteroid to automate repetitive operational EHR workflows while maintaining clear auditability and review controls.

## Common workflows

* Execute note-driven data entry and chart maintenance tasks
* Schedule appointments, reschedules, and calendar follow-ups based on workflow rules
* Trigger follow-up operational actions from chart or referral events
* Synchronize status, identifiers, and completion outcomes across EHR and adjacent systems

## Advanced capabilities

* Use browser and desktop automation together when workflows span EHR UI, file systems, and supporting tools
* Reverse engineer underlying web APIs from target systems when available, then combine API calls with UI automation for faster and more reliable execution
* Capture explicit failure states and route exceptions for human review instead of forcing unsafe completion

## Where agents help most

* Repetitive click-paths and structured operational updates
* High-volume queue processing where consistency matters across teams and sites
* Scheduling-heavy workflows that depend on timing, follow-up windows, and calendar coordination
* Tasks that benefit from human-in-the-loop checkpoints before sensitive writes

## Related healthcare use cases

* [Prior Authorization](/healthcare-workflow-automation/prior-authorization)
* [Revenue Cycle](/healthcare-workflow-automation/revenue-cycle)
* [Healthcare Workflow Automation overview](/healthcare-workflow-automation/overview)


# Overview
Source: https://docs.asteroid.ai/healthcare-workflow-automation/overview

Automate HIPAA healthcare workflows with secure browser and computer use agents for prior auth, claims processing, revenue cycle, and EHR operations.

Asteroid provides reliable, secure **browser agents** and **computer use agents** for high-volume healthcare operations. Teams use Asteroid as a production **web agent** platform for HIPAA-sensitive workflows that span claims, prior authorizations, revenue cycle operations, and EHR systems.

## Why teams choose Asteroid for healthcare automation

* **Built for production reliability:** run large-scale automations consistently, with observability and debugging built in.
* **Secure and compliant:** supports HIPAA healthcare workflow automation with enterprise-grade controls and documented security posture.
* **Works across real portals:** automate thousands of websites and internal tools, including legacy payer and provider portals.
* **Human-in-the-loop ready:** pause, review, and continue safely when clinical or billing decisions need approval.

## Core healthcare use cases

<CardGroup>
  <Card title="Prior Authorization" icon="file-check" href="/healthcare-workflow-automation/prior-authorization">
    Gather chart details, submit payer forms, and track authorization status.
  </Card>

  <Card title="Claims Processing" icon="receipt" href="/healthcare-workflow-automation/claims-processing">
    Automate eligibility checks, claim submission, status retrieval, and reconciliation.
  </Card>

  <Card title="Revenue Cycle" icon="chart-line" href="/healthcare-workflow-automation/revenue-cycle">
    Support end-to-end RCM workflows with deterministic steps and AI handling.
  </Card>

  <Card title="EHR Operations" icon="hospital" href="/healthcare-workflow-automation/ehr-operations">
    Automate repetitive EHR updates and note-driven operational tasks.
  </Card>
</CardGroup>

## Operate at healthcare scale

Asteroid is used by hundreds of startups and enterprises in production, running hundreds of thousands of executions each week across thousands of portals.

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="play" href="/get-started/quickstart">
    Build and run your first production workflow.
  </Card>

  <Card title="Security & Compliance" icon="shield-check" href="/support-security/security">
    Review compliance and security controls for regulated workloads.
  </Card>

  <Card title="MCP Server" icon="plug" href="/mcp/overview">
    Connect your coding assistant to operate workflows directly.
  </Card>

  <Card title="API" icon="cloud" href="/api-reference">
    Integrate Asteroid with your product and operational systems.
  </Card>
</CardGroup>


# Prior Authorization Automation
Source: https://docs.asteroid.ai/healthcare-workflow-automation/prior-authorization

Automate prior authorization workflows with browser and computer use agents across payer portals.

Use Asteroid to automate prior authorization workflows across payer portals while keeping human review points for clinical decisions.

## Common workflows

* Collect patient and chart details required for submission
* Complete and submit payer-specific prior auth forms
* Attach supporting artifacts and required documentation
* Track authorization status and update downstream systems

## Where agents help most

* Repetitive data entry across multiple payer portals
* Frequent status checks and follow-up actions
* Routing exceptions to reviewers when additional context is required

## Related healthcare use cases

* [Claims Processing](/healthcare-workflow-automation/claims-processing)
* [Revenue Cycle](/healthcare-workflow-automation/revenue-cycle)
* [Healthcare Workflow Automation overview](/healthcare-workflow-automation/overview)


# Revenue Cycle Automation
Source: https://docs.asteroid.ai/healthcare-workflow-automation/revenue-cycle

Automate core revenue cycle workflows by combining deterministic browser steps with AI-driven exception handling.

Use Asteroid to support end-to-end revenue cycle workflows with reliable execution and observability.

## Common workflows

* Validate and submit billing-related portal actions
* Monitor payer responses and required follow-up tasks
* Route exception cases for manual approval or escalation
* Keep workflow status synchronized with internal systems

## Where agents help most

* Repeatable high-volume tasks with periodic edge cases
* Cross-system workflows that involve portals and internal tools
* Operations that require auditability and status visibility

## Related healthcare use cases

* [Claims Processing](/healthcare-workflow-automation/claims-processing)
* [EHR Operations](/healthcare-workflow-automation/ehr-operations)
* [Healthcare Workflow Automation overview](/healthcare-workflow-automation/overview)


# MCP Server
Source: https://docs.asteroid.ai/mcp/overview

Connect your AI coding assistant to Asteroid via the Model Context Protocol

The Asteroid MCP server lets you manage agents, inspect executions, and update workflows directly from AI-powered coding tools like **Claude Code** and **Cursor**. Instead of switching between your editor and the Asteroid platform UI, you can ask your assistant to do it in natural language.

## Quick Start

1. [Set up the MCP server](/mcp/setup) in Claude Code or Cursor.
2. Complete sign-in when your client prompts you (first tool use).
3. Ask your assistant to call `getContext`, then `agentList` for your organization.
4. Use `workflowGet` on a version ID from `workflowsList` to read the graph; `workflowCreate` and `workflowPublish` to ship changes.
5. Run `agentExecutePost` to test, and `executionGet` / `executionActivitiesGet` to debug.

See the [Setup guide](/mcp/setup) for detailed installation instructions.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that connects AI assistants to external tools and data sources. When you add the Asteroid MCP server to your editor, your assistant gains access to Asteroid's API — it can start executions, read results, update workflows, and more.

## What You Can Do

<CardGroup>
  <Card title="Inspect Executions" icon="magnifying-glass">
    View execution status, results, and activity logs without leaving your editor.
  </Card>

  <Card title="Manage Workflows" icon="diagram-project">
    Fetch, modify, and publish agent workflow versions through natural language commands.
  </Card>

  <Card title="Start Executions" icon="play">
    Kick off agent runs with custom inputs directly from your terminal.
  </Card>

  <Card title="Debug Failures" icon="bug">
    Investigate failed executions by examining outcomes, reasoning, and activity traces.
  </Card>
</CardGroup>

## Available Tools

Tool names below are the identifiers MCP clients expose to the model when connected to `https://mcp.asteroid.ai/mcp`.

### Context and docs

| Tool                 | Description                                                                                                  |
| :------------------- | :----------------------------------------------------------------------------------------------------------- |
| `getContext`         | Your user context, including organization IDs and names. Call this first when you need an organization UUID. |
| `listAvailableTools` | Capabilities that can be assigned to AI Task nodes in workflows.                                             |
| `searchDocs`         | Search Asteroid documentation for guides, node types, and best practices.                                    |

### Agents and profiles

| Tool                            | Description                                                                  |
| :------------------------------ | :--------------------------------------------------------------------------- |
| `agentList`                     | List agents for an organization (use `organizationId` from `getContext`).    |
| `agentProfilesList`             | List browser profiles (proxy, captcha, credentials, persistence) for an org. |
| `agentProfilesCreate`           | Create a profile.                                                            |
| `agentProfileGet`               | Fetch one profile by ID.                                                     |
| `agentProfileUpdate`            | Update profile settings.                                                     |
| `agentProfileDelete`            | Delete a profile.                                                            |
| `agentProfileClearBrowserCache` | Clear persisted browser state for a profile.                                 |

### Executions

| Tool                          | Description                                                               |
| :---------------------------- | :------------------------------------------------------------------------ |
| `agentExecutePost`            | Start an execution for an agent (uses the published workflow by default). |
| `executionsList`              | List executions with filters and pagination.                              |
| `executionGet`                | Full detail for one execution.                                            |
| `executionActivitiesGet`      | Activity log (tool calls, messages, events).                              |
| `executionContextFilesGet`    | Files attached to an execution context.                                   |
| `executionContextFilesUpload` | Upload files to a running execution.                                      |
| `executionStatusUpdate`       | Pause, resume, or cancel an execution.                                    |
| `executionUserMessagesAdd`    | Send a user message into an execution.                                    |

### Workflows (agent versions)

| Tool                    | Description                                                                            |
| :---------------------- | :------------------------------------------------------------------------------------- |
| `workflowsList`         | List workflow versions for an agent.                                                   |
| `workflowGet`           | Load a full version (graph, rules, settings).                                          |
| `workflowCreate`        | Create a new version; set `parentId` for lineage. Unpublished until `workflowPublish`. |
| `workflowPublish`       | Publish a version so it becomes the default for new runs.                              |
| `workflowExecute`       | Run a specific version (including unpublished), useful for testing.                    |
| `workflowSyncExecution` | Point a running execution at a specific workflow version.                              |

### Files and validation

| Tool                        | Description                                              |
| :-------------------------- | :------------------------------------------------------- |
| `tempFilesStage`            | Stage a file before starting an execution.               |
| `agentSharedFilesGet`       | List persistent shared files for an agent.               |
| `agentSharedFilesUpload`    | Add shared files (available across executions).          |
| `agentSharedFilesUpdate`    | Replace contents of one shared file.                     |
| `agentSharedFilesDelete`    | Remove one shared file.                                  |
| `agentSharedFilesDeleteAll` | Remove all shared files for an agent.                    |
| `agentSharedFilesFreeze`    | Freeze or unfreeze a shared file.                        |
| `schemaValidate`            | Validate JSON schema for structured output requirements. |

<Info>
  The MCP server authenticates with **OAuth** (browser sign-in to your Asteroid account). Your client receives a bearer token valid for the API; permissions match the platform and REST API for your user. For HTTP access to Asteroid without MCP, use an **API key** and the [API](/api-reference) tab — that is separate from MCP auth.
</Info>


# Setup
Source: https://docs.asteroid.ai/mcp/setup

Add the Asteroid MCP server to Claude Code or Cursor

Connect your AI coding assistant to Asteroid in under a minute. The same MCP server works with any editor that supports the Model Context Protocol over HTTP.

## Prerequisites

* An **Asteroid account** you can sign into at [platform.asteroid.ai](https://platform.asteroid.ai)
* **Claude Code** or **Cursor** (or another MCP client that supports streamable HTTP and OAuth discovery)

REST integrations use [API keys](https://platform.asteroid.ai/keys) with the HTTP API. The hosted MCP server uses **OAuth** instead — your editor runs the sign-in flow and stores the session; you do not paste an API key into the MCP `Authorization` header.

## Claude Code

<Steps>
  <Step title="Add the MCP server">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http asteroid https://mcp.asteroid.ai/mcp
    ```

    This registers the Asteroid MCP server with Claude Code.
  </Step>

  <Step title="Authenticate">
    The first time Claude Code uses an Asteroid tool, complete the **browser sign-in** when prompted. The client exchanges the OAuth code for a token and sends it on subsequent requests.
  </Step>

  <Step title="Verify the connection">
    Ask Claude Code to list your agents:

    ```
    "List all my Asteroid agents"
    ```

    If the connection is working, you'll see your agents listed in the response.
  </Step>
</Steps>

## Cursor

<Steps>
  <Step title="Add the MCP server config">
    Add the following to your `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "asteroid": {
          "url": "https://mcp.asteroid.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Authenticate">
    On first use, accept the OAuth flow so Cursor can obtain a token for your Asteroid user.
  </Step>

  <Step title="Verify the connection">
    In Cursor's AI chat, ask:

    ```
    "List all my Asteroid agents"
    ```
  </Step>
</Steps>

<Info>
  The server speaks **streamable HTTP** (`/mcp`) and exposes OAuth metadata at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` for clients that auto-discover authentication.
</Info>

## Usage Examples

Once connected, you can interact with Asteroid using natural language. Tool names your client sees match the [overview](/mcp/overview) (for example `agentList`, `executionGet`, `workflowPublish`).

### Inspecting executions

```
"What happened in execution abc123-def4-..."
"Show me the last 10 executions for my scraping agent"
"Why did execution abc123 fail?"
"List all failed executions from today"
```

### Managing workflows

```
"Fetch the current workflow for agent abc123-..."
"Add a new input called 'language' to the agent workflow"
"Update the output schema to include a 'confidence' field"
"Publish the new workflow version"
```

### Starting executions

```
"Run agent abc123 with url=https://example.com and name=Test"
```

### Debugging

```
"Show me the activity log for execution abc123"
"What tool calls did the agent make in execution abc123?"
"What was the agent's reasoning for the outcome?"
```

## Troubleshooting

| Problem                      | Solution                                                                                                                                                 |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Tool not found" errors      | Verify the MCP server is registered — run `claude mcp list` (Claude Code) or check `.cursor/mcp.json` (Cursor)                                           |
| Authentication or 401 errors | Complete OAuth again: remove the server from the client, re-add it, and sign in when prompted. Ensure your Asteroid user has access to the organization. |
| Timeout errors               | The MCP server calls the Asteroid API — ensure you have internet access and no firewall blocking `mcp.asteroid.ai`                                       |

<Note>
  Need help? Visit our [Support](/support-security/support) page or reach out on GitHub.
</Note>


# Cookbook
Source: https://docs.asteroid.ai/sdks/cookbook

Practical examples for the current Asteroid TypeScript and Python SDKs

These examples are aligned with the current SDK surfaces documented on the [TypeScript SDK](/sdks/typescript) and [Python SDK](/sdks/python) pages.

<Tabs>
  <Tab title="Basic Execution" icon="play">
    Start an execution and poll until the result is available.

    <CodeGroup>
      ```ts theme={null}
      import { client, agentExecutePost, executionGet } from 'asteroid-odyssey';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: {
            patientName: 'Jane Doe',
            appointmentDate: '2026-03-27',
          },
          metadata: {
            source: 'cookbook-basic',
          },
        },
      });

      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      let exec;
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'starting');

      console.log(exec?.status, exec?.inputs);
      ```

      ```python theme={null}
      import os
      import time
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.execution_api import ExecutionApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          exec_api = ExecutionApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={
                      "patientName": "Jane Doe",
                      "appointmentDate": "2026-03-27",
                  },
              ),
          )
          execution_id = response.execution_id

          while True:
              time.sleep(3)
              execution = exec_api.execution_get(execution_id=execution_id)
              if execution.status not in ("running", "starting"):
                  break

          print(execution.status, execution.inputs)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Interactive Run" icon="message">
    Handle runs that pause and need a user message before they can continue.

    <CodeGroup>
      ```ts theme={null}
      import {
        client,
        agentExecutePost,
        executionGet,
        executionUserMessagesAdd,
      } from 'asteroid-odyssey';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: {
            task: 'Ask the user to confirm before submitting the final form',
          },
        },
      });
      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      // Wait for the agent to pause for input
      let exec;
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'starting');

      if (exec?.status === 'paused_by_agent') {
        await executionUserMessagesAdd({
          path: { executionId },
          body: { message: 'Confirmed. Please continue.' },
        });
      }

      // Continue polling until terminal state
      do {
        await new Promise((r) => setTimeout(r, 3000));
        const res = await executionGet({ path: { executionId } });
        exec = res.data;
      } while (exec?.status === 'running' || exec?.status === 'paused_by_agent');

      console.log(exec?.status);
      ```

      ```python theme={null}
      import os
      import time
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.execution_api import ExecutionApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          exec_api = ExecutionApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={"task": "Ask the user to confirm before submitting the final form"},
              ),
          )
          execution_id = response.execution_id

          # Poll until paused or terminal
          while True:
              time.sleep(3)
              execution = exec_api.execution_get(execution_id=execution_id)
              if execution.status not in ("running", "starting"):
                  break

          if execution.status == "paused_by_agent":
              exec_api.execution_user_messages_add(
                  execution_id=execution_id,
                  agents_execution_user_messages_add_text_body={"message": "Confirmed. Please continue."},
              )

              # Poll until terminal
              while True:
                  time.sleep(3)
                  execution = exec_api.execution_get(execution_id=execution_id)
                  if execution.status not in ("running", "paused_by_agent"):
                      break

          print(execution.status)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Files" icon="file">
    Attach files to executions and download the files produced by a run.

    <CodeGroup>
      ```ts theme={null}
      import {
        client,
        agentExecutePost,
        tempFilesStage,
        executionContextFilesUpload,
        executionContextFilesGet,
      } from 'asteroid-odyssey';
      import { readFileSync, writeFileSync } from 'node:fs';

      client.setConfig({
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });

      const invoiceBytes = readFileSync('./invoice.pdf');
      const invoice = new File([invoiceBytes], 'invoice.pdf', { type: 'application/pdf' });

      const { data: staged } = await tempFilesStage({
        path: { organizationId: 'your-org-id' },
        body: { files: [invoice] },
      });

      const { data, error } = await agentExecutePost({
        path: { agentId: 'your-agent-id' },
        body: {
          inputs: {
            task: 'Read the attached invoice and summarize it',
          },
          tempFiles: staged?.tempFiles,
        },
      });
      if (error) throw new Error(JSON.stringify(error));
      const executionId = data.executionId;

      await executionContextFilesUpload({
        path: { executionId },
        body: { files: [invoice] },
      });

      const { data: files } = await executionContextFilesGet({
        path: { executionId },
      });
      for (const file of files ?? []) {
        const response = await fetch(file.downloadUrl, {
          headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
        });
        if (!response.ok) throw new Error(`Download failed: ${response.status}`);
        writeFileSync(`./downloads/${file.fileName}`, Buffer.from(await response.arrayBuffer()));
      }
      ```

      ```python theme={null}
      import os
      from asteroid_odyssey import Configuration, ApiClient
      from asteroid_odyssey.api.agents_api import AgentsApi
      from asteroid_odyssey.api.files_api import FilesApi
      from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

      config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

      with ApiClient(config) as api_client:
          agents_api = AgentsApi(api_client)
          files_api = FilesApi(api_client)

          response = agents_api.agent_execute_post(
              agent_id="your-agent-id",
              agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                  inputs={"task": "Read the uploaded invoice and summarize it"},
              ),
          )
          execution_id = response.execution_id

          files_api.execution_context_files_upload(
              execution_id=execution_id,
              files=[open("./invoice.pdf", "rb")],
          )

          files = files_api.execution_context_files_get(execution_id=execution_id)
          for file in files:
              print(f"{file.file_name}: {file.file_size} bytes")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Related Resources

<CardGroup>
  <Card title="TypeScript SDK" icon="code" href="/sdks/typescript">
    See the current TypeScript helper and generated namespaces
  </Card>

  <Card title="Python SDK" icon="terminal" href="/sdks/python">
    See the current Python high-level client and generated subpackages
  </Card>
</CardGroup>


# Python SDK
Source: https://docs.asteroid.ai/sdks/python

Use the Asteroid Python SDK to execute agents, monitor runs, and manage profiles

Use the `asteroid-odyssey` Python SDK to execute agents, monitor executions, work with files, and manage profiles from your application.

<Info>
  The SDK provides generated API classes. Instantiate `Configuration` with your API key, create an `ApiClient`, then use the API classes directly.
</Info>

## Install

```bash theme={null}
pip install --upgrade asteroid-odyssey
```

Or with uv:

```bash theme={null}
uv pip install asteroid-odyssey
```

## Quickstart

```python theme={null}
import os
import time
from asteroid_odyssey import Configuration, ApiClient
from asteroid_odyssey.api.agents_api import AgentsApi
from asteroid_odyssey.api.execution_api import ExecutionApi
from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

with ApiClient(config) as api_client:
    agents_api = AgentsApi(api_client)
    exec_api = ExecutionApi(api_client)

    response = agents_api.agent_execute_post(
        agent_id="your-agent-id",
        agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
            inputs={"customerName": "Jane Doe"},
        ),
    )
    execution_id = response.execution_id

    # Poll until complete
    while True:
        time.sleep(3)
        execution = exec_api.execution_get(execution_id=execution_id)
        if execution.status not in ("running", "starting"):
            break

    print(execution.status, execution.inputs)
```

Run it with:

```bash theme={null}
python run_agent.py
```

## API Classes

Import these from `asteroid_odyssey.api.*`:

| Class                  | Import                                         | Purpose                             |
| ---------------------- | ---------------------------------------------- | ----------------------------------- |
| `AgentsApi`            | `asteroid_odyssey.api.agents_api`              | Execute agents, list agents         |
| `ExecutionApi`         | `asteroid_odyssey.api.execution_api`           | Get, list, poll, message executions |
| `FilesApi`             | `asteroid_odyssey.api.files_api`               | Upload/download execution files     |
| `AgentProfilesApi`     | `asteroid_odyssey.api.agent_profiles_api`      | Manage agent profiles               |
| `AgentProfilePoolsApi` | `asteroid_odyssey.api.agent_profile_pools_api` | Manage profile pools                |
| `WorkflowsApi`         | `asteroid_odyssey.api.workflows_api`           | Execute specific workflow versions  |

Models live under `asteroid_odyssey.models.*`.

## Common Patterns

<Tabs>
  <Tab title="Executions">
    ```python theme={null}
    import os
    import time
    from asteroid_odyssey import Configuration, ApiClient
    from asteroid_odyssey.api.agents_api import AgentsApi
    from asteroid_odyssey.api.execution_api import ExecutionApi
    from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

    config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

    with ApiClient(config) as api_client:
        agents_api = AgentsApi(api_client)
        exec_api = ExecutionApi(api_client)

        response = agents_api.agent_execute_post(
            agent_id="your-agent-id",
            agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                inputs={"task": "Summarize the attached invoice"},
            ),
        )
        execution_id = response.execution_id

        activities = exec_api.execution_activities_get(
            execution_id=execution_id,
            limit=20,
            order="desc",
        )
        exec_api.execution_user_messages_add(
            execution_id=execution_id,
            agents_execution_user_messages_add_text_body={"message": "Please use the latest file only."},
        )

        status = exec_api.execution_get(execution_id=execution_id)
        print(status.status)
        for activity in activities:
            print(activity.payload)
    ```
  </Tab>

  <Tab title="Files">
    ```python theme={null}
    import os
    from asteroid_odyssey import Configuration, ApiClient
    from asteroid_odyssey.api.agents_api import AgentsApi
    from asteroid_odyssey.api.files_api import FilesApi
    from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

    config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

    with ApiClient(config) as api_client:
        agents_api = AgentsApi(api_client)
        files_api = FilesApi(api_client)

        response = agents_api.agent_execute_post(
            agent_id="your-agent-id",
            agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                inputs={"task": "Read the uploaded invoice and summarize it"},
            ),
        )
        execution_id = response.execution_id

        files_api.execution_context_files_upload(
            execution_id=execution_id,
            files=[open("./invoice.pdf", "rb")],
        )

        files = files_api.execution_context_files_get(execution_id=execution_id)
        for file in files:
            print(f"{file.file_name}: {file.file_size} bytes")
    ```
  </Tab>

  <Tab title="Profiles">
    ```python theme={null}
    import os
    from asteroid_odyssey import Configuration, ApiClient
    from asteroid_odyssey.api.agent_profiles_api import AgentProfilesApi
    from asteroid_odyssey.models.agents_profile_create_agent_profile_request import AgentsProfileCreateAgentProfileRequest

    config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

    with ApiClient(config) as api_client:
        profiles_api = AgentProfilesApi(api_client)

        profiles = profiles_api.agent_profiles_list(organization_id="your-org-id")
        print([profile.name for profile in profiles.items])

        created = profiles_api.agent_profiles_create(
            agents_profile_create_agent_profile_request=AgentsProfileCreateAgentProfileRequest(
                name="Shared Billing Profile",
                description="Reusable browser profile for billing workflows",
                organization_id="your-org-id",
                proxy_country_code="us",
                proxy_type="residential",
                captcha_solver_active=False,
                sticky_ip=False,
                credentials=[],
                cookies=[],
            ),
        )
        print(created.id)
    ```
  </Tab>
</Tabs>

## Notes

* Use `inputs` for execution variables — `dynamic_data` is deprecated.
* `execution_activities_get` returns a list of `AgentsExecutionActivity` objects directly.
* `agent_profiles_list` requires `organization_id`.
* The SDK's default base URL is `https://odyssey.asteroid.ai/agents/v2`. Override via `Configuration(host=...)`.

## Related Resources

<CardGroup>
  <Card title="TypeScript SDK" icon="code" href="/sdks/typescript">
    See the TypeScript SDK guide
  </Card>

  <Card title="API" icon="book" href="/api-reference">
    Browse the API landing page and common workflows
  </Card>
</CardGroup>


# Setup
Source: https://docs.asteroid.ai/sdks/setup

Hook your agent up to Asteroid in minutes

The easiest way to get started is to head to our platform and run an agent from there: [https://platform.asteroid.ai](https://platform.asteroid.ai)

If you want to run an agent from your own code, you can follow the steps below:

<Steps>
  <Step title="Generate an API key">
    Sign in to our [platform](https://platform.asteroid.ai), head to [API Keys](https://platform.asteroid.ai/keys) and generate a new key.

    ```bash theme={null}
    export ASTEROID_API_KEY="ast..."
    ```

    Our SDK examples read from `ASTEROID_API_KEY`, but you can pass the value into your client however you prefer.

    See [API Quickstart](/api-reference/quickstart) for more details.
  </Step>

  <Step title="Choose your SDK">
    We provide SDKs for both TypeScript and Python.

    * [TypeScript SDK](/sdks/typescript)
    * [Python SDK](/sdks/python)

    Each SDK page contains detailed documentation and examples to help you get started.
  </Step>
</Steps>

## Next Steps

Once you've set up your environment, you can:

1. Create your first agent using the platform UI
2. Follow the examples in the SDK documentation
3. Review the [API](/api-reference) page for common workflows and endpoint coverage

Need help? Reference our [Support](/support-security/support) page


# TypeScript SDK
Source: https://docs.asteroid.ai/sdks/typescript

Use the Asteroid TypeScript SDK to execute agents, monitor runs, and manage profiles

Use the `asteroid-odyssey` TypeScript SDK to execute agents, monitor executions, work with files, and manage profiles from your application.

<Info>
  The SDK exports a `client` singleton and individual endpoint functions. Configure the client once with your API key, then call the functions directly.
</Info>

## Install

```bash theme={null}
npm install asteroid-odyssey
```

Or with pnpm:

```bash theme={null}
pnpm add asteroid-odyssey
```

## Quickstart

```ts theme={null}
import { client, agentExecutePost, executionGet } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

const { data, error } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: {
      customerName: 'Jane Doe',
    },
    metadata: {
      source: 'docs',
    },
  },
});

if (error) throw new Error(JSON.stringify(error));
const executionId = data.executionId;

// Poll until complete
let exec;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const res = await executionGet({ path: { executionId } });
  exec = res.data;
} while (exec?.status === 'running' || exec?.status === 'starting');

console.log(exec?.status, exec?.inputs);
```

Run it with:

```bash theme={null}
npx tsx run_agent.ts
```

## Client Configuration

All SDK functions share the singleton `client`. Configure it once at startup:

```ts theme={null}
import { client } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
  // Optional: override the base URL
  baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
});
```

Every function accepts an optional `client` override if you need per-request auth:

```ts theme={null}
const { data } = await executionGet({
  client: myOtherClient,
  path: { executionId },
});
```

## Exported Functions

| Function                      | Purpose                                         |
| ----------------------------- | ----------------------------------------------- |
| `agentList`                   | List agents with pagination                     |
| `agentExecutePost`            | Execute an agent                                |
| `executionGet`                | Fetch execution details                         |
| `executionsList`              | List executions with filters                    |
| `executionActivitiesGet`      | Fetch execution activities (returns `Array`)    |
| `executionStatusUpdate`       | Update execution status (e.g. cancel)           |
| `executionUserMessagesAdd`    | Send a user message to a running execution      |
| `executionContextFilesGet`    | List files on an execution                      |
| `executionContextFilesUpload` | Upload files to a running execution             |
| `tempFilesStage`              | Stage temporary files before execution          |
| `agentProfilesList`           | List agent profiles (requires `organizationId`) |
| `agentProfilesCreate`         | Create an agent profile                         |
| `agentProfileGet`             | Fetch a single profile                          |
| `agentProfileUpdate`          | Update a profile                                |
| `agentProfileDelete`          | Delete a profile                                |
| `agentWorkflowsExecute`       | Execute a specific workflow version             |

## Common Patterns

<Tabs>
  <Tab title="Executions">
    ```ts theme={null}
    import {
      client,
      agentExecutePost,
      executionsList,
      executionActivitiesGet,
      executionUserMessagesAdd,
    } from 'asteroid-odyssey';

    client.setConfig({
      headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
    });

    const { data } = await agentExecutePost({
      path: { agentId: 'your-agent-id' },
      body: {
        inputs: {
          task: 'Summarize the attached invoice',
        },
      },
    });
    const executionId = data!.executionId;

    const { data: page } = await executionsList({
      query: {
        page: 1,
        pageSize: 10,
        executionId,
      },
    });

    const { data: activities } = await executionActivitiesGet({
      path: { executionId },
      query: { limit: 20, order: 'desc' },
    });

    await executionUserMessagesAdd({
      path: { executionId },
      body: { message: 'Please use the latest file only.' },
    });

    console.log(page?.items);
    console.log(activities?.map((a) => a.payload.activityType));
    ```
  </Tab>

  <Tab title="Files">
    ```ts theme={null}
    import {
      client,
      agentExecutePost,
      tempFilesStage,
      executionContextFilesUpload,
      executionContextFilesGet,
    } from 'asteroid-odyssey';
    import { readFileSync, writeFileSync } from 'node:fs';

    client.setConfig({
      headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
    });

    const fileBuffer = readFileSync('./invoice.pdf');
    const invoice = new File([fileBuffer], 'invoice.pdf', { type: 'application/pdf' });

    const { data: staged } = await tempFilesStage({
      path: { organizationId: 'your-org-id' },
      body: { files: [invoice] },
    });

    const { data } = await agentExecutePost({
      path: { agentId: 'your-agent-id' },
      body: {
        inputs: { task: 'Read the staged file' },
        tempFiles: staged?.tempFiles,
      },
    });
    const executionId = data!.executionId;

    await executionContextFilesUpload({
      path: { executionId },
      body: { files: [invoice] },
    });

    const { data: files } = await executionContextFilesGet({
      path: { executionId },
    });
    for (const file of files ?? []) {
      const response = await fetch(file.downloadUrl, {
        headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
      });
      if (!response.ok) throw new Error(`Download failed: ${response.status}`);
      writeFileSync(`./downloads/${file.fileName}`, Buffer.from(await response.arrayBuffer()));
    }
    ```
  </Tab>

  <Tab title="Profiles">
    ```ts theme={null}
    import {
      client,
      agentProfilesList,
      agentProfilesCreate,
      agentProfileUpdate,
    } from 'asteroid-odyssey';

    client.setConfig({
      headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
    });

    const { data: profiles } = await agentProfilesList({
      query: { organizationId: 'your-org-id', page: 1, pageSize: 20 },
    });
    console.log(profiles?.items?.map((p) => `${p.id}: ${p.name}`));

    const { data: created } = await agentProfilesCreate({
      body: {
        name: 'Shared Billing Profile',
        description: 'Reusable browser profile for billing workflows',
        organizationId: 'your-org-id',
        proxyCountryCode: 'us',
        proxyType: 'residential',
        captchaSolverActive: false,
        stickyIp: false,
        credentials: [],
        cookies: [],
      },
    });

    await agentProfileUpdate({
      path: { profileId: created!.id },
      body: { description: 'Updated description' },
    });
    ```
  </Tab>
</Tabs>

## Notes

* Use `inputs` for execution variables — `dynamicData` is deprecated.
* `executionActivitiesGet` returns `Array<AgentsExecutionActivity>` directly, not a wrapped object.
* `agentProfilesList` requires `organizationId` in the query.
* All functions return `{ data, error }`. Check `error` before using `data`.
* File list responses include a `downloadUrl` per file. Fetch it with your API key in the `X-Asteroid-Agents-Api-Key` header.

## Related Resources

<CardGroup>
  <Card title="Python SDK" icon="terminal" href="/sdks/python">
    See the Python SDK guide
  </Card>

  <Card title="API" icon="book" href="/api-reference">
    Browse the API landing page and common workflows
  </Card>
</CardGroup>


# Security & Compliance
Source: https://docs.asteroid.ai/support-security/security

Security measures and compliance information

<CardGroup>
  <Card title="HIPAA Compliance" icon="shield-check">
    <div>
      <a href="https://trust.oneleet.com/asteroid">
        <img alt="HIPAA Compliance Badge" />

        <img alt="HIPAA Compliance Badge" />
      </a>
    </div>

    Our platform is fully HIPAA compliant, ensuring all health information is properly protected according to federal requirements.
  </Card>

  <Card title="SOC II Type II" icon="certificate">
    <div>
      <a href="https://trust.oneleet.com/asteroid">
        <img alt="SOC II Type II Compliance Badge" />

        <img alt="SOC II Type II Compliance Badge" />
      </a>
    </div>

    We are SOC II Type II compliant, demonstrating our commitment to security, availability, and confidentiality controls.
  </Card>
</CardGroup>

We have also undergone a successful external penetration test. For complete documentation visit our [Trust Center](https://trust.oneleet.com/asteroid).

***

<Note>
  For security questions or to report an issue, please contact our [team](/support-security/support).
</Note>


# Support
Source: https://docs.asteroid.ai/support-security/support

Get help with Asteroid

Need help with Asteroid? We're here to assist you. Choose the best option for your needs:

<CardGroup>
  <Card title="Email Support" icon="envelope" href="mailto:founders@asteroid.ai?subject=Support Request">
    Get direct support from our team via email
  </Card>

  <Card title="Schedule a Call" icon="calendar" href="https://calendly.com/founders-asteroid-hhaf/30min">
    Book a call with our founders to get a custom demo of our product
  </Card>
</CardGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I get started with Asteroid?">
    Check out our [quickstart guide](/get-started/quickstart) to get up and running quickly. You can also [schedule a call](https://calendly.com/founders-asteroid-hhaf/30min) with our team for personalized onboarding.
  </Accordion>

  <Accordion title="How secure is my data?">
    Security is our top priority. We use enterprise-grade security protocols. Learn more about our security measures [here](/support-security/security).
  </Accordion>

  <Accordion title="Can I integrate Asteroid with my existing systems?">
    Yes! Asteroid is designed to integrate seamlessly with your existing workflows through our robust API. Check out our [SDKs](/sdks/setup) for more details.
  </Accordion>
</AccordionGroup>


# Changelog
Source: https://docs.asteroid.ai/whats-new/changelog

Product updates and announcements

<Update label="2026-04-26">
  **What's New**

  * Legacy migration helper: Added an in-app migration banner and modal to make moving older agents into the current experience easier.
  * Visual output schema builder: You can now build JSON output schemas from a structured UI instead of editing raw JSON only.

  **Improvements**

  * More predictable long-running executions: Soft timeout controls are now available, so runs end more gracefully when they exceed expected duration.
  * Better run transparency in Activity: Handoff arguments and script-variable substitution steps are now surfaced, making it easier to understand why an execution behaved a certain way.

  **Fixes**

  * Fixed key run-flow UI issues in execution views, including missing upload access in the run modal and sticky headers not tracking the active node consistently.
  * Fixed multiple edge-case input issues (including dropped first characters after click-and-type in batch CUA flows) to improve automation accuracy.
</Update>

<Update label="2026-04-19">
  **What's New**

  * New Overview page: You can now see a high-level summary of agent and execution performance in one place.
  * More powerful command palette: Quick actions and navigation are faster and easier to access.

  **Improvements**

  * More stable long-running runs: timeout handling, provider fallback behavior, and execution pipeline routing were tightened to reduce stalled runs.
  * Better instruction quality for form/data entry tasks: prompt guardrails were refined to reduce incorrect field handling during automation.

  **Fixes**

  * Fixed memory file preview staleness and improved recording/execution status alignment for more trustworthy run monitoring.
</Update>

<Update label="2026-04-12">
  **What's New**

  * Build from empty: You can now generate an agent starting from a blank state.
  * Email inbox view: Execution mode now includes an inbox view for email-driven automations.

  **Improvements**

  * Faster heavy runs: snapshot compression and larger snapshot support improved performance for complex sessions.
  * Run modal is simpler and now remembers batch settings between runs.
  * Re-runs link more clearly to previous executions, making comparisons easier.
  * Prompt updates improved action batching and script execution guidance, which helps agents complete multi-step tasks with fewer retries.
</Update>

<Update label="2026-04-05">
  **What's New**

  * Dashboard outcome cards now show totals for faster at-a-glance monitoring.

  **Improvements**

  * More reliable high-volume automation: file-sync and download handling were hardened to better recover from rate limits and transient storage failures.
  * Output result and activity visuals were refined for clearer execution feedback.
  * Handoff and file-path prompt guidance was clarified so agents transfer work between phases more reliably in remote browser environments.

  **Fixes**

  * Fixed empty script results not displaying correctly.
</Update>

<Update label="2026-03-29">
  **What's New**

  * Unified file workspace: Memory and files are now combined into one file experience with richer previews.
  * Better tab management: Added tab context menus and drag-and-drop tab reordering.
  * Added TOTP QR code reader support for easier MFA setup in automations.

  **Improvements**

  * Faster execution paths: optimized mode defaults and reduced unnecessary model calls improved throughput on simpler workflows.
  * Playwright code and script-failure cards are clearer, making debugging easier.
  * Pause actions feel more responsive with optimistic UI updates.
  * Prompt updates improved cross-node data flow and script output conventions, making multi-step workflows more predictable.
</Update>

<Update label="2026-03-22">
  **What's New**

  * Google Sheets import for batch runs: You can now launch bulk jobs directly from Sheets data.
  * Added custom proxy gateway controls with better egress-IP visibility in profile setup.

  **Improvements**

  * Better batch throughput controls: concurrent batch execution limits and per-agent defaults now make large runs more predictable.
  * Batch execution settings are remembered per agent to reduce repeated setup work.
  * Run modal prefill and execution results layout were cleaned up for faster review.
  * Prompt behavior for selector transitions and learning/script modes was refined so agents finalize tasks more consistently.

  **Fixes**

  * Fixed cancelled-message behavior and reliability issues that could cause confusing execution outcomes.
</Update>

<Update label="2026-03-15">
  **What's New**

  * Command palette and quick search: Navigate and run common actions faster.
  * Mermaid diagram viewer: Diagram content now renders directly in the app.

  **Improvements**

  * Improved execution traceability: activity logs now show richer assistant/turn context so slow or failed runs are easier to diagnose.
  * Activity logs now group turns more clearly and include assistant text messages for better traceability.
  * Workflow version differences are easier to review.

  **Fixes**

  * Fixed hanging and multi-tab execution edge cases, with matching prompt updates to reduce instruction drift during long tasks.
</Update>

<Update label="2026-03-08">
  **What's New**

  * Shared files now support full in-app management, including creating, updating, and deleting files.
  * New execution mode controls give you more flexibility over how runs are executed.
  * File tooling expanded with a dedicated files tab and node-level file explorer.

  **Improvements**

  * Faster startup for file-heavy runs: execution initialization and tool timeout behavior were improved for better stability.
  * You can now export all files as a ZIP for easier sharing and archival.
  * Prompt system updates introduced clearer execution-mode guidance and stronger save/script instructions, improving agent follow-through on complex runs.

  **Fixes**

  * Reduced deterministic-mode failures by tightening fallback and script-format guidance in prompts.
</Update>

<Update label="2026-03-01">
  **What's New**

  * Shared files across runs: You can now store and reuse files across executions from the new shared files area.
  * Organization renaming: Organizations can now be renamed directly.
  * More graph-building flexibility: You can now drag a transition onto empty canvas space to create and connect a new node in one step.

  **Improvements**

  * Better run stability controls: Long-running executions now handle timeouts, cancellation, and budget limits more reliably.

  **Fixes**

  * Clearer context-window failures: When context limits are exceeded in Astro, the UI now shows a clear error state with recovery flow.
</Update>

<Update label="2026-02-22">
  **What's New**

  * Agent file manager: You can now browse agent files with a directory tree and manage files directly in the platform.
  * Excel batch uploads: Batch runs now support `.xlsx` and `.xls` files in addition to CSV.
  * Save PDF tool: Agents can now save page content as PDFs and surface those files in the file manager.
  * Larger file support: Execution-start file uploads now support significantly larger files (up to 200MB).

  **Improvements**

  * More reliable recordings: Execution recordings now use in-house storage with more stable playback links.

  **Fixes**

  * Fixed re-run flow so previous execution variables are prefilled correctly.
  * Fixed workflow editing so agents with disconnected nodes can still be saved when appropriate.
</Update>

<Update label="2026-02-15">
  **What's New**

  * Duplicate agent profiles across organizations: You can now copy an existing profile into another org instead of recreating it from scratch.
  * Smarter batch setup: CSV columns can now auto-map to workflow input fields, making large batch runs faster to configure.
  * Webhook targeting filters: You can now set metadata-based filters for webhook notifications so events route to the right destination more precisely.

  **Improvements**

  * Better activity clarity: Transition activity now shows clearer node summaries, making execution timelines easier to understand.

  **Fixes**

  * More accurate analytics dates: Stats now respect your browser timezone to prevent misleading daily grouping.
</Update>

<Update label="2026-02-08">
  **What's New**

  * Agent profile pools: You can now group and manage profile pools, and use them directly from the run dialog.
  * Batch executions: You can now launch and manage batch runs with CSV mapping tools from the platform.
  * Rich instruction editing: Instruction fields now support rich markdown editing for easier prompt authoring.

  **Improvements**

  * Better tab continuity: The app now remembers your last active tab and preserves search/filter state when navigating.
  * Better profile configurability: Agent profiles now expose tracing and Tailscale proxy settings in the UI.
</Update>

<Update label="2026-02-01">
  **What's New**

  * New agent layout: Redesigned UI with tab management for a cleaner, more organized agent building experience.
  * Scheduled executions: Schedule agents to run at specific times with the new scheduling system.
  * Captcha handling: Agents can now detect, pause and handle CAPTCHA challenges during automation.
  * PDF viewer toggle: Enable or disable PDF viewing in agent profile settings.
  * Slack approval buttons: Execution notifications in Slack now include View and Approve action buttons.
  * Schedule toggle: Enable or disable scheduled executions without deleting them.

  **Improvements**

  * Refreshed UI layout with improved navigation and visual hierarchy.
  * Rescheduling support for cancelled scheduled executions.
  * Optimized activity component re-renders with memoization.
  * Better error handling for validation failures in agent profiles.

  **Fixes**

  * Fixed non-retryable failures when LLM didn't perform any action.
  * Fixed laggy search filter and pagination in model overrides modal.
</Update>

<Update label="2026-01-25">
  **What's New**

  * User profiles: First name and last name fields added to user accounts.
  * Run from table: Execute agents directly from the agents table actions menu.
  * Browser IP display: See the IP address used by the browser in execution environment details.
  * JSON schema validation: Validate workflow data against JSON schemas.

  **Improvements**

  * Enhanced proxy configuration options in agent profiles.
  * Execution list now shows agent profile ID and inputs.
  * Better agent workflow handling and state management.
  * Improved model type definitions with enhanced language model support.
</Update>

<Update label="2026-01-18">
  **What's New**

  * Execution environment API: New API endpoints for managing agent execution environments.
  * Key-value filters: Filter executions by custom metadata key-value pairs.
  * Temporary file uploads: Upload temporary files when running evaluations.

  **Improvements**

  * Enhanced execution table with agent and human label filtering options.
  * Agent actions menu provides quick access to common agent operations.
  * Better accessibility with aria-labels throughout the UI.
  * Streamlined UI component library with workspace package migration.
</Update>

<Update label="2026-01-11">
  **What's New**

  * Recent execution outcomes: Agent stats now show the last 5 execution outcomes at a glance.
  * Stop conversations: Pause or stop active Astro conversations.
  * Graph diff visualization: See workflow changes visualized in the graph view.
  * Output format validation: Validate output schemas with format constraints.
  * Sandbox browser option: Choose between sandboxed and direct browser connections.

  **Improvements**

  * Enhanced workflow publishing with better version handling.
  * Improved Astro websocket reliability with hidden transient errors.
  * Increased page size for agent profiles to 1000 for faster loading.
  * Enhanced billing page usage tracking and visualization.
</Update>

<Update label="2026-01-04">
  **What's New**

  * Asteroid MCP server Beta: New Model Context Protocol server for LLM agent interaction.
  * Sandbox environments: Run agents in isolated sandbox environments.
  * Rename agent tool: Astro can now automatically suggest and apply agent names.
  * List executions tool: Query execution history with workflow version filtering directly from Astro.
  * Continue on node: New transition option allows agents to stay on the current node and continue processing.
  * Execution status updates: Update execution status programmatically via the SDK.

  **Improvements**

  * Advanced model search with text highlighting for easier selection.
  * Connection status indicator shows real-time Astro connection state.
  * Enhanced copy-paste in graph editor filters transitions based on connected nodes.

  **Fixes**

  * Resolved file download condition to check for browser availability.
</Update>

<Update label="2025-12-28">
  **What's New**

  * New authentication system for improved security and enterprise SSO support.
  * Increased token limits: Maximum tokens increased to 128,000 for more complex agent tasks.
  * YAML file uploads: Upload YAML configuration files to your agents.
  * Auto-accept workflow changes: Automatically accept Astro's suggested workflow modifications.
  * Auto-expanding chat input: Text area grows as you type for a better editing experience.

  **Improvements**

  * Adblock enabled by default to prevent popup interference during browser automation.
  * Renamed "dynamic data" to "inputs" for clearer terminology across the platform.
  * Version history component replaces version selector for better workflow tracking.
  * Responsive sidebar layout adapts to portrait and landscape modes.
  * Enhanced credential management UI in agent profiles.
  * Better scroll management in chat components.

  **Fixes**

  * Resolved date range logic in average duration and outcomes charts.
  * Fixed workflow state handling in operating context.
  * Corrected agent workflows list invalidation on workflow commit.
</Update>

<Update label="2025-12-21">
  **What's New**

  * Screenshot tool: New `browser_take_screenshot` tool for capturing page screenshots during automation.
  * Script evaluation: Execute JavaScript directly on web pages with the new script eval action.
  * PDF viewer settings: Configure PDF viewing behavior in browser settings.
  * Author tracking: Workflows now track who created and modified them.
  * Workflow version display: Executions now show which workflow version was used.

  **Improvements**

  * PDF URL validation prevents accidentally navigating to PDFs in URL nodes.
  * Lightweight workflow reference listing for faster agent loading.
  * Enhanced query context support in activity tracking.
  * Removed deprecated execution workflow update endpoints for cleaner API.
  * Better error handling for display button tool instructions.

  **Fixes**

  * Fixed execution stats queries to properly join on workflow table.
  * Prevented deleting draft versions that have active executions.
</Update>

<Update label="2025-12-14">
  **What's New**

  * Browser live view: See real-time browser activity with the new live view URL.
  * Create agent profiles from Astro: Build and configure agent profiles directly from the assistant.
  * Workflow diff review: Visual overlay showing pending workflow changes before committing.
  * Edit mode requests: Request edit access to workflows when viewing executions.
  * Session from execution: Create new Astro sessions directly from execution mode.

  **Improvements**

  * Character count with progress visualization when typing messages.
  * Dynamic labels change based on your current operating context.
  * Enhanced template agents with clearer login instructions.
  * Improved outcomes distribution chart layout.

  **Fixes**

  * Fixed form reset issues during auto-save in execution mode.
  * Corrected proxy country code handling when creating agent profiles.
</Update>

<Update label="2025-12-07">
  **What's New**

  * Astro AI assistant: New intelligent assistant panel with interactive demo prompts, welcome header, and capability chips to help you get started faster.
  * Auto-layout for graphs: New nodes are automatically arranged in a clean layout when added to the workflow.
  * Initial prompts: Set an initial prompt when creating new agents to jumpstart workflows.
  * Version notifications: Get notified when new platform updates are available.
  * File attachments in chat: Send files up to 24MB through the WebSocket connection.
  * Conversation management: Update and rename conversations directly from the UI.

  **Improvements**

  * Markdown support in chat messages for richer formatting.
  * Copy-to-clipboard button for UUIDs with improved UI feedback.
  * Workflow validation now returns multiple errors at once for faster debugging.
  * Force edit mode: Continue editing agents even when executions are running.
  * Auto-select most recent conversation when opening the chat panel.
  * Better loading and error states in the execution panel.

  **Fixes**

  * Fixed tab reconnection issues when switching browser tabs.
  * Resolved flashing when changing query params on agent page.
  * Fixed mention menu dismissing when clicking scrollbar.
  * Prevented message submission when mention menu is closed.
</Update>

<Update label="2025-11-30">
  **What's New**

  * Execution status counts: New API endpoint to get counts of executions by status.
  * Publish workflow: Publish your staged workflow changes directly from the builder.
  * Copy-paste for nodes: Copy and paste nodes and sticky notes in the graph editor.
  * Script timeout: Set custom timeout values for script execution.
  * Concurrent execution limits: Subscription tiers now include concurrent execution limits.

  **Improvements**

  * Enhanced execution table with better data fetching and pagination experience.
  * Centralized filter state management for cleaner execution filtering.
  * Improved browser playback controls for landscape orientation.
  * Better dialog sizing on small screens.

  **Fixes**

  * Fixed current node handling in execution graph extraction.
  * Resolved issues with expired subscription migrations.
  * Fixed human labels dropdown placeholder text.
  * Corrected execution stats dashboard click event handling.
</Update>

<Update label="2025-11-23">
  **What's New**

  * Slack channel management: Select specific Slack channels for your integration notifications.
  * Event notification filtering: Filter notifications by specific event fields and values.
  * Webhook v2: Expanded execution events with standardized webhook format.
  * Output schema validation: Support for regex pattern validation in output properties.
  * Resizable panels: New resizable panel components for flexible layouts.
  * Billing management: View and manage your subscription directly in the platform.

  **Improvements**

  * Simplified webhook configuration UI with streamlined settings.
  * Enter key now sends messages in chat input.
  * Activity stream shows transition types when moving between nodes.
  * Improved conversation selector with smooth scrolling and sorting.
  * Better button sizing and styling consistency across the platform.
  * Enhanced execution overlay with double-click to expand.

  **Fixes**

  * Fixed WebSocket "close sent" errors during connection closure.
  * Fixed notification mapper errors in v2 notifications.
</Update>

<Update label="2025-11-16">
  **What's New**

  * Slack integration: Connect your Slack workspace to receive agent notifications directly in your channels.
  * Documentation search: Agents can now query Asteroid documentation to help answer questions about the platform.
  * Undo/redo support: Graph editor now supports undo/redo with keyboard shortcuts (Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z).
  * Keyboard shortcuts modal: View all available keyboard shortcuts in the graph editor.
  * Agent profile visibility: Executions table now shows which agent profile was used for each run.

  **Improvements**

  * LLM call tracking: Activity stream now shows when agents are making AI model calls and for what purpose.
  * Enhanced activity auto-scroll: Activity progress panel now auto-scrolls to follow agent actions in real-time.
  * Streaming messages: Improved real-time streaming when sending messages to running agent executions.
  * Better navigation tracking: Browser navigation actions now show timing and status in activity logs.
  * Sidebar context: Sidebar items now show helpful subtitles for better navigation context.
  * Improved duration charts: Average duration analytics now have better tooltips and layout.

  **Fixes**

  * Fixed double scrolling issue on tables with pagination.
  * Corrected line number display in scriptpad content.
  * Resolved datetime formatting errors in certain timezones.
  * Fixed streaming message handling in agent conversations.
</Update>

<Update label="2025-11-09">
  **What's New**

  * Execution filtering: Filter runs by agent, status, and date range.
  * Execution metadata: Add custom key–value metadata to runs for better organization and searchability.
  * Version selection when running agents.
  * New unified Stats page with full historical analytics.
  * Auto-generated node descriptions for clearer, easier-to-understand workflows.

  **Improvements**

  * Playwright scripts now surface browser console logs for easier debugging.
  * More detailed workflow failure diagnostics, with line-level script errors.
  * Execution statistics now include average-duration metrics and support filtering by agent version.
  * More reliable selector transitions with built-in retry logic.
  * Better page-state capture during rapid navigation.

  **Fixes**

  * Resolved failures caused by LLM calls returning only reasoning content.
  * Corrected file listing display issues.
  * Fixed date/time formatting in activity logs.
</Update>

<Update label="2025-10-31">
  **What's New**

  * **Output Node Type:** Define structured workflow outputs and custom outcomes beyond simple success/failure.
  * **Query Context Tool:** AI Task nodes can agentically retrieve information from previous steps.
  * **Node-Level Context Management:** More targeted, step-specific behavior control.
  * **get\_datetime Tool:** Retrieve current date/time in any timezone.
  * **freeze\_script Option:** Prevent unwanted script regeneration in Learn & Compile mode.
  * Email tools: `send_mail` and `get_mail`.
  * Sticky notes for annotating workflows.

  **Improvements**

  * Upgraded AI model for Playwright script generation: higher reliability, better selectors, clearer flows.
  * AI Task tools reorganized into capability categories.
  * Improved workflow activity logs with richer details (API calls, file ops).
  * Agents now signal more clearly when they’re blocked and require user assistance.

  **Fixes**

  * Cookie handling during browser initialization.
  * Transition failures in specific workflow patterns.
  * Occasional browser disconnection issues.
  * Workflow rendering issues affecting agent navigation.
  * Better reasoning-mode alignment across model types.
  * String-variable quoting issues in Playwright scripts.
  * Error wrapping in API responses.
  * Summarization performance improvements.
</Update>

<Update label="2025-09-30">
  **What's New**

  * **Agent Listing API:** Paginated, sortable agent listings through the External API.
  * **Real-time Graph Updates:** Live updates to the workflow graph as you edit.
  * **Learn & Compile Mode:** Combines AI-driven decisions with cached Playwright scripts for stable automation.
  * AI-optimized node descriptions for more readable workflows.

  **Improvements**

  * Raised file upload limits: 20MB/file and 100MB total.
  * Faster, more reliable real-time streaming with better concurrency handling.
  * Optional proxy settings in agent profiles.
  * Enhanced Playwright script logs with detailed execution output.
  * More reliable WebSocket activity updates.
  * More specific API error messages and validations.

  **Fixes**

  * More detailed error handling for workflow-graph update failures.
  * Execution cancellation reliability improvements.
  * Empty proxy fields no longer cause errors.
  * More stable long-running automation sessions.
  * Playwright LLM variable migration stability improvements.
  * TOTP secret generation bug fixes.
</Update>

<Update label="2025-09-13">
  **What's New**

  * Added cookie management to agent profiles, allowing you to store and manage website cookies for your automation workflows
  * Added new list\_files and read\_files tools for agents to work with context files during execution
  * Added browser\_fill\_form action for simplified form completion
  * Added support for JavaScript evaluation on web pages with the new browser\_evaluate tool
  * File uploads and downloads are now tracked in the activity stream, showing important metadata like filename, size, and type
  * You can now use longer agent names up to 100 characters
  * Special characters are now supported in agent names (previously limited to alphanumeric, #, -, \_, and spaces)

  **Improvements**

  * Enhanced file handling with better error messages and more consistent processing
  * Browser form filling now shows field details in the activity log for better visibility
  * Large model responses now automatically retry with increased token limits when needed
  * Improved error handling and reliability for streaming connections
  * File uploads for agent executions are more efficient and reliable
  * Enhanced agent cancellation with more specific reasons (timeout, max steps, or user-requested)
  * Improved reasoning display when the agent is thinking through complex tasks
  * Enhanced WebSocket connection handling for more reliable real-time activity updates
  * Workflow Flexibility: You can now have multiple end success and end failure nodes in your workflows.
  * Better reliability for real-time updates during agent execution - the system now processes messages more efficiently and reliably, ensuring you get immediate updates about your agent's activities

  **Fixes**

  * Fixed duplicate activity messages that were incorrectly appearing in execution logs
  * Fixed an issue where duplicate credential names could cause conflicts
  * Fixed occasional connection errors during real-time activity streaming
  * Fixed an issue where execution status was incorrectly displayed as "Starting" instead of "Running" when activities begin, providing more accurate status information in the interface
  * Fixed issues with image handling in agent conversations
  * Resolved a potential issue during execution cancellation that could prevent proper cancellation in certain cases
</Update>

<Update label="2025-08-25">
  **What's New**

  * Real-time activity updates for agent executions with the new activity streaming endpoint
  * You can now send messages to a running agent execution via a new API endpoint
  * Enhanced activity tracking with filtering options to view execution activities in your preferred order
  * Improved file upload capabilities in agents, allowing for more seamless handling of user-provided files within agent workflows.
  * Enhanced browser file download features that enable agents to access and work with files downloaded during browsing sessions.
  * You can now select Windows as the operating system for your agent profiles, allowing you to run browser sessions that emulate Windows instead of macOS

  **Improvements**

  * Activity streams now show detailed step progress, node transitions, and agent actions
  * Agent statistics now include average execution time metrics
  * Enhanced error messages for troubleshooting agent issues
  * Added comprehensive API documentation to make integration easier
  * Introduced API versioning with a new v2 endpoint structure for better backwards compatibility
  * Better file metadata handling with improved MIME type detection and extension processing for more accurate file identification.
  * Streamlined file notifications for agents, making it clearer when new files are available for use.
  * More robust file handling with improved validation, sanitization, and error handling for increased reliability.
  * Enhanced file activity messaging.

  **Fixes**

  * Fixed reliability issues with browser actions by improving error handling
  * Resolved problems with file downloading
  * Fixed an issue where expired subscriptions couldn't be upgraded without contacting support
</Update>