Automate Features

The Automate operator executes complex browser automation tasks using natural language instructions. It provides real-time streaming updates as the automation progresses.

All Automate methods are async generators and should be used with async for.

Overview

import asyncio
import os
from tabstack import TABStack

async def main():
    async with TABStack(api_key=os.getenv('TABSTACK_API_KEY')) as tabs:
        # Execute automation (async generator)
        async for event in tabs.automate.execute(task, url=None, guardrails=None, max_iterations=50):
            # Handle streaming events
            pass

asyncio.run(main())

Execute Automation

The execute method returns an async generator that streams events as the automation runs.

Basic Usage

import asyncio
import os
from tabstack import TABStack

async def main():
    async with TABStack(api_key=os.getenv('TABSTACK_API_KEY')) as tabs:
        async for event in tabs.automate.execute(
            task='Find the top 3 trending repositories on GitHub and extract their names and star counts',
            url='https://github.com/trending',
            guardrails='browse and extract only'
        ):
            print(f"Event: {event.type}")

            if event.type == 'task:completed':
                result = event.data.get('finalAnswer')
                print(f'Automation completed: {result}')

asyncio.run(main())

Event Types

Event Type	Description	Key Data Fields
start	Automation starting	-
task:completed	Task finished successfully	finalAnswer, status
agent:status	Status update	message
agent:action	Performing an action	action, target
agent:extracted	Data was extracted	extractedData
browser:navigated	Page navigation occurred	url
error	An error occurred	error

Real-World Examples

Example 1: Web Scraping

async def scrape_trending():
    async with TABStack(api_key=os.getenv('TABSTACK_API_KEY')) as tabs:
        print('Starting GitHub trending scraper...\n')

        async for event in tabs.automate.execute(
            task='Navigate to GitHub trending, find the top 5 repositories, and extract: name, description, primary language, and star count',
            url='https://github.com/trending',
            guardrails='browse and extract only',
            max_iterations=50
        ):
            if event.type == 'agent:status':
                print(f"Status: {event.data.get('message')}")

            elif event.type == 'agent:action':
                print(f"Action: {event.data.get('action')}")

            elif event.type == 'browser:navigated':
                print(f"Navigated to: {event.data.get('url')}")

            elif event.type == 'agent:extracted':
                extracted = event.data.get('extractedData')
                print(f'Extracted data: {extracted}')

            elif event.type == 'task:completed':
                result = event.data.get('finalAnswer')
                print('\n✅ Automation completed!')
                print(f'Final result: {result}')

            elif event.type == 'error':
                print(f"❌ Error: {event.data.get('error')}")

asyncio.run(scrape_trending())

Example 2: Form Filling

async def fill_contact_form():
    form_data = {
        'name': 'Alex Johnson',
        'email': '[email protected]',
        'company': 'Example Corp',
        'message': 'I am interested in learning more about your products.'
    }

    async with TABStack(api_key=os.getenv('TABSTACK_API_KEY')) as tabs:
        print('Filling contact form...\n')

        async for event in tabs.automate.execute(
            task='Fill out the contact form with the provided data and submit it',
            url='https://company.example.com/contact',
            data=form_data,
            guardrails='do not navigate away from the domain',
            max_iterations=30
        ):
            if event.type == 'agent:action':
                action = event.data.get('action')
                target = event.data.get('target')
                print(f"Action: {action} on {target or 'page'}")

            elif event.type == 'task:completed':
                print('\n✅ Form submitted successfully!')
                confirmation = event.data.get('finalAnswer')
                print(f'Confirmation: {confirmation}')

asyncio.run(fill_contact_form())

Example 3: Progress Tracking

async def track_progress():
    progress = {
        'status': 'Starting...',
        'current_step': 0,
        'last_action': '',
        'is_complete': False,
        'error': None
    }

    async with TABStack(api_key=os.getenv('TABSTACK_API_KEY')) as tabs:
        try:
            async for event in tabs.automate.execute(
                task='Find and extract the top 5 blog posts',
                url='https://blog.example.com'
            ):
                if event.type == 'agent:status':
                    progress['status'] = event.data.get('message', 'Processing...')

                elif event.type == 'agent:step':
                    progress['current_step'] = event.data.get('step', 0)

                elif event.type == 'agent:action':
                    progress['last_action'] = event.data.get('action', '')

                elif event.type == 'task:completed':
                    progress['is_complete'] = True
                    progress['status'] = 'Completed'

                elif event.type == 'error':
                    progress['error'] = event.data.get('error')

                # Display progress
                print(f"Status: {progress['status']}")
                print(f"Step: {progress['current_step']}")
                print(f"Last Action: {progress['last_action']}\n")

        except Exception as error:
            print(f"Automation failed: {error}")

asyncio.run(track_progress())

Working with EventData

Each event includes an EventData object with helper methods:

async for event in tabs.automate.execute(task, url):
    # Get a specific field
    message = event.data.get('message')

    # Get with a default value
    step = event.data.get('step', 0)

    # Get the raw data dict
    raw_data = event.data.get_raw()
    print(f'All event data: {raw_data}')

    # Check if a field exists
    if event.data.get('extractedData'):
        data = event.data.get('extractedData')
        # Process extracted data

Options Reference

automate.execute()

Parameter	Type	Default	Description
task	str	required	Natural language description of the task
url	str	None	Starting URL for the automation
data	dict	None	Context data (e.g., form fields to fill)
guardrails	str	None	Safety constraints for automation behavior
max_iterations	int	50	Maximum iterations (range: 1-100)
max_validation_attempts	int	3	Maximum validation retry attempts (range: 1-10)

Guardrails

# Examples of guardrails:

# Browse only
guardrails='browse and extract only'

# Stay on domain
guardrails='do not navigate away from the domain'

# No purchases
guardrails='do not add items to cart or make purchases'

# Read-only
guardrails='read-only operations, do not submit forms'

Best Practices

1. Be Specific with Instructions

# ❌ Vague
task = 'Get some products'

# ✅ Specific
task = 'Find the top 5 best-selling products in Electronics and extract names, prices, and ratings'

2. Always Use Guardrails

# ✅ Good
async for event in tabs.automate.execute(
    task='Extract data',
    guardrails='browse and extract only, do not submit forms'
):
    pass

3. Handle All Event Types

async for event in tabs.automate.execute(task):
    if event.type == 'agent:status':
        # Show progress
        pass
    elif event.type == 'task:completed':
        # Handle success
        pass
    elif event.type == 'error':
        # Handle errors
        break

Next Steps

• Error Handling: Build robust applications
• Extract Features: Learn about data extraction
• Generate Features: Discover AI transformations
• REST API Reference: See the REST API endpoint