Working with Flows

Creating Flows

Flows are the core concept in Donobu - they represent automated sequences of browser interactions to accomplish a specific objective.

Basic Autonomous Flow

This example creates a flow that autonomously navigates and performs actions:

curl -X POST http://localhost:31000/api/flows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Search Flow",
    "targetWebsite": "https://example-ecommerce.com",
    "overallObjective": "Search for wireless headphones, filter by price under $100, and add the first result to cart",
    "initialRunMode": "AUTONOMOUS",
    "browser": {
      "using": {
        "type": "device",
        "headless": false
      }
    },
    "maxToolCalls": 20
  }'

Deterministic Flow with Predefined Actions

For repeatable automation, you can define specific actions upfront:

curl -X POST http://localhost:31000/api/flows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login Sequence",
    "targetWebsite": "https://app.example.com/login",
    "initialRunMode": "DETERMINISTIC",
    "envVars": ["USER_EMAIL", "USER_PASSWORD"],
    "toolCallsOnStart": [
      {
        "name": "click",
        "parameters": {
          "selector": "#email-input"
        }
      },
      {
        "name": "type",
        "parameters": {
          "text": "${USER_EMAIL}"
        }
      },
      {
        "name": "click",
        "parameters": {
          "selector": "#password-input"
        }
      },
      {
        "name": "type",
        "parameters": {
          "text": "${USER_PASSWORD}"
        }
      },
      {
        "name": "click",
        "parameters": {
          "selector": "#login-button"
        }
      }
    ]
  }'

Monitoring Flow Execution

Getting Flow Status

# Get detailed flow information
curl -X GET http://localhost:31000/api/flows/{flowId}

The response includes:

• Current execution state (RUNNING, SUCCESS, FAILED, etc.)
• Progress information
• Token usage
• Start and completion times

Listing All Flows

# Get all flows
curl -X GET http://localhost:31000/api/flows

# Filter flows by state
curl -X GET "http://localhost:31000/api/flows?state=RUNNING"

# Filter flows by date range
curl -X GET "http://localhost:31000/api/flows?startedAfter=1640995200000&limit=10"

Flow States

Understanding flow states helps monitor execution:

• UNSTARTED: Flow created but not yet initialized
• INITIALIZING: Setting up browser context and initial state
• RUNNING_ACTION: Executing a tool call
• QUERYING_LLM_FOR_NEXT_ACTION: AI determining next action (AUTONOMOUS mode)
• WAITING_ON_USER_FOR_NEXT_ACTION: Waiting for user input (INSTRUCT mode)
• PAUSED: Flow execution temporarily suspended
• RESUMING: Transitioning from paused to active state
• FAILED: Flow terminated unsuccessfully
• SUCCESS: Flow completed successfully

Retrieving Flow Data

Getting Tool Calls

View all actions performed during a flow:

curl -X GET http://localhost:31000/api/flows/{flowId}/tool-calls

Getting Screenshots

Retrieve screenshots taken during flow execution:

curl -X GET http://localhost:31000/api/flows/{flowId}/images/{imageId} \
  --output screenshot.png

Getting Video Recording

Download the complete video of the flow execution:

curl -X GET http://localhost:31000/api/flows/{flowId}/video \
  --output flow-recording.webm

Rerunning Flows

Get Rerun Configuration

Generate a configuration to rerun a completed flow:

curl -X GET http://localhost:31000/api/flows/{flowId}/rerun

This returns a CreateDonobuFlow object that can be used to create an identical flow.

Rerun with Modifications

# Get the rerun configuration
RERUN_CONFIG=$(curl -s -X GET http://localhost:31000/api/flows/{flowId}/rerun)

# Modify and create new flow
echo $RERUN_CONFIG | jq '.name = "Rerun - Modified"' | \
curl -X POST http://localhost:31000/api/flows \
  -H "Content-Type: application/json" \
  -d @-

Generating Test Code

Convert Flow to Playwright Script

curl -X GET http://localhost:31000/api/flows/{flowId}/code \
  --output test-script.js

Generate Complete Test Project

Create a full Playwright project from multiple flows:

curl -X POST http://localhost:31000/api/flows/project \
  -H "Content-Type: application/json" \
  -d '{
    "flowIds": ["flow-id-1", "flow-id-2", "flow-id-3"],
    "options": {
      "runInHeadedMode": true,
      "slowMotionDelay": 100,
      "disableSelfHealingTests": false
    }
  }' \
  --output playwright-project.zip

Advanced Flow Configuration

Custom Tools

Define custom JavaScript functions for specialized actions:

{
  "customTools": [
    {
      "name": "validatePriceRange",
      "description": "Validates that a price is within the specified range",
      "inputSchema": {
        "type": "object",
        "properties": {
          "selector": {"type": "string"},
          "minPrice": {"type": "number"},
          "maxPrice": {"type": "number"}
        }
      },
      "javascript": "const element = await page.locator(selector); const priceText = await element.textContent(); const price = parseFloat(priceText.replace(/[^0-9.]/g, '')); return price >= minPrice && price <= maxPrice;"
    }
  ]
}

Result Extraction

Define a JSON schema to extract structured data from the flow:

{
  "resultJsonSchema": {
    "type": "object",
    "properties": {
      "productName": {"type": "string"},
      "price": {"type": "number"},
      "availability": {"type": "boolean"},
      "productUrl": {"type": "string"}
    },
    "required": ["productName", "price"]
  }
}

Error Handling and Debugging

Common Issues

1. Flow Stuck in INITIALIZING: Check browser configuration
2. FAILED State: Review tool call errors in the flow details
3. GPT Timeout: Ensure GPT configuration is valid and accessible

Debugging Tips

• Use headless: false to watch flow execution
• Set slowMotionDelay to slow down actions
• Review screenshots and video recordings
• Check tool call results for error details

Best Practices

1. Start Simple: Begin with basic flows and add complexity gradually
2. Use Environment Variables: Store sensitive data and configuration in env vars
3. Set Reasonable Limits: Use maxToolCalls to prevent runaway flows
4. Monitor Resources: Long-running flows can consume significant compute resources
5. Test Incrementally: Use INSTRUCT mode to test individual steps
6. Save Browser State: Use persistState to save login sessions for reuse
7. Handle Dynamic Content: Use selectors that work reliably across page updates