Skip to content

README.md

Latest commit

 

History

History
211 lines (157 loc) · 7.96 KB

README.md

File metadata and controls

211 lines (157 loc) · 7.96 KB

BrowserAct-Workflow-API-Python-Demos

Note: this code runs successfully in Python version 3.13.5

API documentation: https://www.browseract.com/reception/integrations/api-workflow
Site: https://www.browseract.com

Environment Requirements

  • Python 3.8 or higher
  • pip (comes with Python)

Installation

  1. Install Python from python.org
  2. Verify installation: 
    python --version
pip --version

Project Setup

  1. Navigate to the Workflow-Python directory:

    cd Workflow-Python

  2. Install dependencies:

    pip install -r requirements.txt

Running Examples

🎯 Scenario-Based Examples (Recommended for New Users)

If you're new to BrowserAct API, we recommend starting with scenario-based examples that demonstrate how to combine multiple APIs to accomplish real-world use cases:

📖 View Scenario Guide: Scenarios-Python/README.md

Quick Start with Scenario Examples:

# Scenario 1: Run custom workflow task and wait for completion
python ../Scenarios-Python/scenario_1_run_and_wait.py

# Scenario 2: Run template task and wait for completion (Recommended for beginners)
python ../Scenarios-Python/scenario_2_run_template_and_wait.py

📚 Individual API Examples (Learn Specific API Usage)

If you want to understand how each specific API works, you can run the following examples:

# Run specific example
python 1.run_task.py
python 2.stop_task.py
python 3.get_task.py
python 4.get_task_status.py
python 5.list_tasks.py
python 6.list_workflows.py
python 7.get_workflow.py
python 8.resume_task.py
python 9.run_task_by_template.py
python 11.list_official_workflow_templates.py
python 12.get_region_list.py

🚀 Quick Start Guide

Option 1: Using Custom Workflows

  1. Get your workflow ID: Run 6.list_workflows.py or visit https://www.browseract.com/reception/workflow-list
  2. Get workflow details: Run 7.get_workflow.py to see required input parameters
  3. Run the task: Run 1.run_task.py with your workflow ID and parameters
  4. Check status: Run 3.get_task.py or 4.get_task_status.py to monitor progress

Option 2: Using Official Templates (Easier for beginners)

  1. List available templates: Run 11.list_official_workflow_templates.py to see all templates
  2. Run template task: Run 9.run_task_by_template.py with a template ID from step 1
  3. Check status: Run 3.get_task.py or 4.get_task_status.py to monitor progress

Recommended: Start with Scenario Examples in ../Scenarios-Python/ directory for complete examples that combine multiple APIs.

Project Structure

Workflow-Python/
├── README.md                                # This file
├── requirements.txt                         # Python dependencies
├── 1.run_task.py                            # Start a new workflow task
├── 2.stop_task.py                           # Permanently terminate a task
├── 3.get_task.py                            # Get detailed task information
├── 4.get_task_status.py                     # Get task status only
├── 5.list_tasks.py                          # List all workflow tasks
├── 6.list_workflows.py                      # List all workflows
├── 7.get_workflow.py                        # Get workflow details
├── 8.resume_task.py                         # Resume a paused task
├── 9.run_task_by_template.py                # Start a new workflow task using template
├── 11.list_official_workflow_templates.py    # List official workflow templates
└── 12.get_region_list.py                    # Get supported region list

Example Files

Task Management

File Description API Endpoint
1.run_task.py Start a new workflow task (custom workflow) POST /v2/workflow/run-task
9.run_task_by_template.py Start a new workflow task using official template POST /v2/workflow/run-task-by-template
2.stop_task.py Permanently terminate a task PUT /v2/workflow/stop-task
8.resume_task.py Resume a paused task PUT /v2/workflow/resume-task
3.get_task.py Get detailed task information GET /v2/workflow/get-task
4.get_task_status.py Get task status only GET /v2/workflow/get-task-status
5.list_tasks.py List all workflow tasks GET /v2/workflow/list-tasks

Workflow Management

File Description API Endpoint
6.list_workflows.py List all custom workflows GET /v2/workflow/list-workflows
7.get_workflow.py Get workflow details GET /v2/workflow/get-workflow
11.list_official_workflow_templates.py List official workflow templates GET /v2/workflow/list-official-workflow-templates

Utility APIs

File Description API Endpoint
12.get_region_list.py Get supported region list for proxy GET /v2/workflow/get-region-list

Configuration

Before running the examples, you need to:

  1. Get your API key from: https://www.browseract.com/reception/integrations
  2. Get your workflow ID or workflow template ID:
  3. Update the following variables in each example file:
    • authorization: Replace "app-abcdefghijklmn" with your actual API key
    • workflow_id: Replace 1234567890 with your actual workflow ID (for custom workflows)
    • workflow_template_id: Replace "1234567890" with your actual template ID (for template-based tasks)
    • task_id: Replace the actual task ID returned by 1.run_task.py or 9.run_task_by_template.py

API Key Security

Important: The examples use placeholder API keys for demonstration purposes. In production:

  1. Never hardcode API keys in your source code
  2. Use environment variables or secure configuration files
  3. Keep your API keys confidential and rotate them regularly

Example of using environment variables:

import os
authorization = os.getenv("BROWSERACT_API_KEY")

Using Official Templates

BrowserAct provides official workflow templates that you can use without creating your own workflows:

  1. List available templates:

    python 11.list_official_workflow_templates.py

    This will show you all available official templates with their IDs, names, and descriptions.

  2. Run a task using a template:

    python 9.run_task_by_template.py

    Make sure to:

    • Set workflow_template_id to a template ID from step 1
    • Configure input_parameters according to the template's requirements

Note: Template-based tasks don't support save_browser_data and profile_id parameters. These features are only available for custom workflows.

Error Handling

All examples include comprehensive error handling for:

  • Network connectivity issues
  • API authentication errors
  • Invalid parameters
  • Server errors

Dependencies

  • Requests: HTTP library for making API requests
  • JSON: Built-in JSON parsing for API responses

Troubleshooting

Common Issues

  1. Python Version Error: Ensure Python 3.8+ is installed
  2. Module Not Found: Verify you're in the correct directory and dependencies are installed
  3. API Error 401: Check your API key and ensure it's valid
  4. API Error 10118: Verify the workflow ID exists and is accessible with your API key
  5. Template Not Found: Ensure the workflow_template_id is valid. Use 11.list_official_workflow_templates.py to get available template IDs

Getting Help

License

This demo code is provided as-is for educational and development purposes.