Hybrid Mode (Browser + API)

CUGA's hybrid mode combines the power of both browser automation and API interactions, allowing you to seamlessly work with web pages while leveraging backend services.

🎯 What is Hybrid Mode?

Hybrid mode enables CUGA to:

🌐 Browser Automation: Navigate, interact with, and manipulate web pages
🔌 API Interactions: Make API calls to backend services
🔄 Combined Workflows: Use both capabilities in a single task
📊 Data Integration: Fetch data via APIs and display it on web pages

⚙️ Configuration

Enable Hybrid Mode

Edit your settings.toml file:

[features]
mode = "hybrid"  # Set to hybrid mode (browser + API)

[hybrid_mode]
enabled = true
browser_enabled = true
api_enabled = true
web_automation = true

Environment Variable

# Set via environment variable
export CUGA_MODE="hybrid"

🚀 Getting Started

1. Start CUGA in Hybrid Mode

# Start with hybrid mode
cuga start demo --mode hybrid

# Or set mode and start
export CUGA_MODE="hybrid"
cuga start demo

2. Verify Mode

# Check current mode
cuga mode current

# Expected output: "hybrid"

# Check configuration
cuga config show --section features

💬 Example Queries

Hybrid Mode Queries

These queries demonstrate the power of combining browser and API operations:

"what is the top account by revenue from digital sales and add it to current page"
"get customer data from the API and fill out the contact form on this page"
"fetch product inventory and update the shopping cart display"
"retrieve user profile from the backend and populate the profile page"
"get sales analytics and create a chart on the current page"

The Signature Example

Query: "what is the top account by revenue from digital sales and add it to current page"

What CUGA Does:

API Call: Queries the Digital Sales API for top revenue accounts
Data Processing: Analyzes and identifies the highest revenue account
Browser Interaction: Adds the account information to the current HTML page
Result Display: Shows the account details on the page

🌐 Browser + API Integration

How It Works

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Page      │    │   CUGA Agent    │    │   Digital       │
│   (Browser)     │◄──►│   (Hybrid)      │◄──►│   Sales API     │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Step-by-Step Process

Page Analysis: CUGA analyzes the current web page
API Query: Makes API call to Digital Sales service
Data Processing: Processes and formats the response
Page Update: Modifies the HTML page with new data
User Feedback: Provides confirmation of the operation

🔧 Setup for Hybrid Mode

Prerequisites

✅ CUGA running in hybrid mode
✅ Digital Sales API accessible
✅ Web page open in browser
✅ Browser automation tools enabled

Browser Setup

# Ensure browser automation is enabled
cuga config show --section hybrid_mode

# Verify browser tools
cuga tools list --type browser

# Check API connectivity
cuga apis test digital_sales

📄 HTML Page Example

Simple HTML Page

Create a simple HTML page to test the hybrid functionality:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CUGA Hybrid Mode Demo</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
        }
        .account-info {
            background-color: #f5f5f5;
            padding: 15px;
            border-radius: 5px;
            margin: 20px 0;
        }
        .highlight {
            background-color: #e3f2fd;
            padding: 10px;
            border-left: 4px solid #2196f3;
        }
    </style>
</head>
<body>
    <h1>🤖 CUGA Hybrid Mode Demo</h1>
    
    <div class="highlight">
        <h2>Current Page Status</h2>
        <p>This page is ready for CUGA to add account information.</p>
    </div>
    
    <div class="account-info" id="account-display">
        <h3>Account Information</h3>
        <p>No account data yet. Use CUGA to fetch and display account information.</p>
    </div>
    
    <div class="highlight">
        <h2>Try This Query</h2>
        <p>Say to CUGA: <strong>"what is the top account by revenue from digital sales and add it to current page"</strong></p>
    </div>
    
    <div class="account-info">
        <h3>Expected Result</h3>
        <p>CUGA will:</p>
        <ol>
            <li>Query the Digital Sales API</li>
            <li>Find the top revenue account</li>
            <li>Add the account details to this page</li>
            <li>Update the display above</li>
        </ol>
    </div>
</body>
</html>

Save and Open the Page

# Save the HTML content to a file
cat > demo_page.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CUGA Hybrid Mode Demo</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
        }
        .account-info {
            background-color: #f5f5f5;
            padding: 15px;
            border-radius: 5px;
            margin: 20px 0;
        }
        .highlight {
            background-color: #e3f2fd;
            padding: 10px;
            border-left: 4px solid #2196f3;
        }
    </style>
</head>
<body>
    <h1>🤖 CUGA Hybrid Mode Demo</h1>
    
    <div class="highlight">
        <h2>Current Page Status</h2>
        <p>This page is ready for CUGA to add account information.</p>
    </div>
    
    <div class="account-info" id="account-display">
        <h3>Account Information</h3>
        <p>No account data yet. Use CUGA to fetch and display account information.</p>
    </div>
    
    <div class="highlight">
        <h2>Try This Query</h2>
        <p>Say to CUGA: <strong>"what is the top account by revenue from digital sales and add it to current page"</strong></p>
    </div>
    
    <div class="account-info">
        <h3>Expected Result</h3>
        <p>CUGA will:</p>
        <ol>
            <li>Query the Digital Sales API</li>
            <li>Find the top revenue account</li>
            <li>Add the account details to this page</li>
            <li>Update the display above</li>
        </ol>
    </div>
</body>
</html>
EOF

# Open the page in your browser
open demo_page.html  # macOS
# OR
xdg-open demo_page.html  # Linux
# OR
start demo_page.html  # Windows

🧪 Testing the Hybrid Example

1. Open the Demo Page

# Open the HTML page in your browser
open demo_page.html

2. Start CUGA in Hybrid Mode

# Start CUGA with hybrid mode
cuga start demo --mode hybrid

3. Execute the Query

In the CUGA interface, say:

"what is the top account by revenue from digital sales and add it to current page"

4. Watch the Magic Happen

CUGA will:

Analyze the current page
Query the Digital Sales API
Process the account data
Update the HTML page
Display the top account information

🔍 How the Integration Works

Page Analysis

CUGA analyzes the current page to understand:

Page Structure: HTML elements and their IDs
Content Areas: Where to place new information
Styling: How to format the new content
Interactivity: What elements can be modified

API Integration

# Example of how CUGA processes the request
def process_hybrid_request(query, current_page):
    # 1. Parse the query
    if "top account by revenue" in query:
        # 2. Make API call
        account_data = digital_sales_api.get_top_account_by_revenue()
        
        # 3. Format the data
        formatted_data = format_account_display(account_data)
        
        # 4. Update the page
        update_page_content(current_page, formatted_data)
        
        return f"Added top account ({account_data['name']}) to the current page"

Page Update Process

// Example of how CUGA updates the page
function updateAccountDisplay(accountData) {
    const displayElement = document.getElementById('account-display');
    
    displayElement.innerHTML = `
        <h3>Account Information</h3>
        <div class="account-details">
            <h4>${accountData.name}</h4>
            <p><strong>Revenue:</strong> $${accountData.revenue.toLocaleString()}</p>
            <p><strong>Industry:</strong> ${accountData.industry}</p>
            <p><strong>Location:</strong> ${accountData.location}</p>
            <p><strong>Last Updated:</strong> ${new Date().toLocaleString()}</p>
        </div>
    `;
}

📊 Use Cases

Perfect for Hybrid Mode

Data Display: Fetch data via API and show on web pages
Form Population: Get data from backend and fill web forms
Dynamic Content: Update page content based on API responses
User Experience: Combine real-time data with web interfaces
Workflow Automation: Navigate pages and interact with APIs

Example Scenarios

Customer Dashboard: Fetch customer data and display on profile page
Product Catalog: Get inventory from API and update product listings
Analytics Display: Retrieve metrics and create charts on web pages
Form Automation: Fill out forms with data from multiple sources
Content Management: Update web content based on backend data

🔧 Advanced Configuration

Hybrid Mode Settings

[hybrid_mode]
# Core settings
enabled = true
browser_enabled = true
api_enabled = true

# Browser settings
headless = false
browser_timeout = 60
page_load_timeout = 30

# API settings
api_timeout = 30
max_concurrent_requests = 5
retry_attempts = 3

# Integration settings
auto_page_update = true
content_injection = true
style_preservation = true

Performance Tuning

[hybrid_mode.performance]
# Browser optimization
lazy_loading = true
resource_blocking = false
image_loading = false

# API optimization
connection_pooling = true
response_caching = true
request_batching = true

# Page update optimization
batch_updates = true
update_throttling = 100
change_detection = true

🚨 Troubleshooting

Common Hybrid Mode Issues

Issue	Solution
🔴 Browser not responding	Check browser automation setup
🔴 API calls failing	Verify API configuration
🔴 Page updates not working	Check page structure and IDs
🔴 Performance issues	Optimize browser and API settings

Debug Commands

# Check hybrid mode status
cuga mode current

# Verify browser tools
cuga tools list --type browser

# Test API connectivity
cuga apis test

# Check page interaction
cuga browser test --page demo_page.html

📈 Performance Considerations

Resource Usage

Hybrid mode uses more resources than API-only mode:

Memory: Browser automation requires significant memory
CPU: Page rendering and interaction processing
Network: Both API calls and web page loading
Storage: Browser cache and page snapshots

Optimization Tips

Limit Concurrent Operations: Don't run too many browser operations simultaneously
Use Headless Mode: For production environments without UI
Implement Caching: Cache API responses and page elements
Monitor Resources: Keep track of memory and CPU usage

📚 Next Steps

After mastering hybrid mode:

Browser Only Mode: Focus purely on web automation
API Only Mode: Optimize for server-side operations
Save & Reuse: Optimize hybrid workflows
Advanced Features: Explore execution modes

Hybrid mode working? Explore Browser Only Mode next!

Hybrid Mode (Browser + API)

On this page