Understanding Automate Event Flow

When you call the /v1/automate endpoint, the API streams real-time updates about task execution through Server-Sent Events (SSE). This guide explains how events flow during a typical automation task and how to use them effectively in your application.

How Event Streaming Works

The automate endpoint establishes a persistent connection and streams events as the task progresses. Each event represents a distinct phase or action in the automation lifecycle. Your client receives these events in real-time, allowing you to:

• Display progress updates to users
• Track the current state of the task
• Capture extracted data as it becomes available
• Handle errors gracefully

The Event Lifecycle

A typical automation task flows through these phases:

1. Initialization

When you submit a request, the first events establish the task context:

event: start
data: {"task": "Find the product price", "url": "https://example.com/product"}

event: task:setup
data: {}

event: task:started
data: {"task": "Find the product price", "url": "https://example.com/product"}

At this point, your client knows the task has been accepted and the browser is being prepared. You might display a "Starting task..." message to the user.

2. Planning and Processing

The agent analyzes the page and creates an execution plan:

event: agent:processing
data: {"operation": "Creating task plan", "hasScreenshot": true}

event: agent:status
data: {"message": "Task plan created", "plan": "1. Navigate to product page\n2. Locate price element\n3. Extract price value"}

The agent:processing event fires whenever the agent is thinking. The hasScreenshot field indicates whether the agent is analyzing visual content. Use this to show a "Thinking..." or "Analyzing page..." indicator.

The agent:status event provides the plan in human-readable format. You can display this to give users visibility into what the automation will do.

3. Execution Steps

As the agent executes the plan, it emits events for each step:

event: agent:step
data: {"iterationId": "abc123", "currentIteration": 0}

event: browser:navigated
data: {"title": "Product Details - Example Store", "url": "https://example.com/product/123"}

event: agent:action
data: {"action": "click", "value": "Clicking on price details button"}

event: browser:action_started
data: {}

event: browser:action_completed
data: {}

The agent:step event marks each iteration of the execution loop. Use currentIteration to show progress (e.g., "Step 1 of 5").

Browser events tell you what's happening in the automated browser:

• browser:navigated - The page URL or title changed
• browser:action_started / browser:action_completed - An interaction (click, type, scroll) is in progress

4. Data Extraction

When the agent extracts data from the page, you receive it immediately:

event: agent:action
data: {"action": "extract", "value": "Extracting product price"}

event: agent:extracted
data: {"extractedData": "{\"price\": \"$29.99\", \"currency\": \"USD\"}"}

The extractedData field contains a JSON string. Parse it to access the structured data:

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (event.type === 'agent:extracted') {
    const extracted = JSON.parse(data.extractedData);
    console.log('Price:', extracted.price); // "$29.99"
  }
};

You may receive multiple agent:extracted events if the task involves extracting data from different pages or elements.

5. Completion

When the task finishes successfully:

event: task:validated
data: {}

event: task:completed
data: {"success": true, "finalAnswer": "The product price is $29.99 USD"}

event: complete
data: {"success": true, "result": {"finalAnswer": "The product price is $29.99 USD"}, "stats": {"actions": 5}}

event: done
data: {}

The task:completed and complete events both indicate success, but serve different purposes:

• task:completed - The automation logic finished successfully
• complete - The final summary with statistics about the run

The done event signals the end of the stream. Close your EventSource connection when you receive this.

Handling Errors

If something goes wrong during execution:

event: error
data: {"error": "Unable to locate element", "code": "ELEMENT_NOT_FOUND"}

Errors can occur at any point. Your client should always have an error handler ready:

eventSource.addEventListener('error', (event) => {
  const data = JSON.parse(event.data);
  console.error('Task failed:', data.error);
  eventSource.close();
});

If a task is terminated early, you'll receive:

event: task:aborted
data: {}

Building a Client

Here's a pattern for handling the event stream:

const eventSource = new EventSource('/v1/automate', {
  // Include auth headers via fetch or use withCredentials
});

const state = {
  status: 'starting',
  plan: null,
  currentStep: 0,
  extractedData: [],
  result: null
};

eventSource.addEventListener('task:started', (e) => {
  state.status = 'running';
});

eventSource.addEventListener('agent:status', (e) => {
  const data = JSON.parse(e.data);
  state.plan = data.plan;
});

eventSource.addEventListener('agent:step', (e) => {
  const data = JSON.parse(e.data);
  state.currentStep = data.currentIteration + 1;
});

eventSource.addEventListener('agent:extracted', (e) => {
  const data = JSON.parse(e.data);
  state.extractedData.push(JSON.parse(data.extractedData));
});

eventSource.addEventListener('complete', (e) => {
  const data = JSON.parse(e.data);
  state.status = 'completed';
  state.result = data.result;
});

eventSource.addEventListener('error', (e) => {
  state.status = 'error';
  eventSource.close();
});

eventSource.addEventListener('done', () => {
  eventSource.close();
});

Key Takeaways

• Events stream in real-time - Update your UI as events arrive rather than waiting for completion
• Track state with agent:step - Use currentIteration to show progress
• Parse extractedData as JSON - It's a stringified JSON object
• Always handle errors - Tasks can fail at any point
• Close on done - The stream ends with the done event
• Use complete for final results - It contains the summary and statistics

For a complete list of all events and their data structures, see the Automation Events Reference.