Execution Engine

The PLai Framework’s workflow execution engine is built on a tick-based scheduling model driven by Pub/Sub messaging. This design enables asynchronous, scalable execution of complex multi-step workflows.

Execution Model Overview

Client executes workflow — POST /workflows/{id}/execute
Create TrackedExecution (status PENDING) — publish message to Pub/Sub
Pub/Sub triggers ProcessWorkflow — engine processes a tick (ready nodes)
- Sync nodes (plai_agent, http, markdown_report) — complete immediately
- Async nodes (firecrawl) — marked RUNNING, wait for a webhook, then call complete_node()
More work?
- Yes — republish to Pub/Sub and repeat from step 3
- No — workflow is COMPLETED

Key Concepts

Tick-Based Scheduling

A tick is a single execution cycle where the engine:

Loads the current execution context and step states
Determines which nodes are ready to run (dependencies satisfied)
Executes up to 5 nodes in parallel per tick
Updates step executions and workflow metadata
Republishes a continuation message if work remains

Why ticks?

Prevents any single tick from consuming too many resources
Enables fair scheduling across multiple workflows
Allows for monitoring and intervention between steps

Batch Processing

The engine processes nodes in batches:

Batch size: 5 nodes per tick
Execution: Parallel within the batch
Continuation: Automatic via Pub/Sub when more nodes are ready

Asynchronous Continuation

For long-running operations:

Synchronous nodes complete within the same tick
Asynchronous nodes (like firecrawl) mark their status as RUNNING and wait
External services complete the work and call a webhook
The webhook endpoint completes the node and republishes to Pub/Sub
Next tick processes dependent nodes

Execution Lifecycle

Step 1: Workflow Trigger

POST /workflows/{workflow_id}/execute
{
  "input": {
    "topic": "Artificial Intelligence",
    "depth": 2
  }
}

Response:

{
  "success": true,
  "execution_id": "exec-uuid-789"
}

What happens:

Workflow definition is resolved
TrackedExecution is created with status PENDING
Initial context stores the input
Pub/Sub message published

Step 2: First Tick Processing

Engine loads the execution and:

Identifies root nodes (no dependencies)
Executes them in parallel
Stores outputs in context
Updates step execution records

Example first tick: Status after tick 1:

fetch_data: COMPLETED
search_web: COMPLETED
analyze_a: PENDING (waiting for fetch_data)
analyze_b: PENDING (waiting for fetch_data)
analyze_c: PENDING (waiting for search_web)

Step 3: Subsequent Ticks

Each tick:

Checks which nodes have satisfied dependencies
Executes ready nodes (up to 5 per tick)
Repeats until terminal state

Example later tick: Status after tick 2:

fetch_data: COMPLETED
search_web: COMPLETED
analyze_a: COMPLETED
analyze_b: COMPLETED
analyze_c: RUNNING (async firecrawl)
report: PENDING (waiting for analyze_a, analyze_b, analyze_c)

Step 4: Async Completion

For firecrawl nodes:

Node starts firecrawl job
Returns is_waiting=True
Engine marks step as RUNNING
Waits for webhook callback

(External: Firecrawl completes work)

Webhook receives completion
Calls complete_node(step_id, result)
Republishes to Pub/Sub
Next tick processes dependents

Step 5: Workflow Completion

Final state:

All sync nodes: COMPLETED
All async nodes: COMPLETED or FAILED
Workflow status: COMPLETED or FAILED

Terminal conditions:

COMPLETED: All nodes succeeded
FAILED: At least one node failed

Execution States

Each workflow execution has a status:

Status	Meaning	What to do
`PENDING`	Created, waiting to start	Wait for first tick
`RUNNING`	Processing nodes	Monitor via GET request
`COMPLETED`	All nodes succeeded	Retrieve outputs
`FAILED`	At least one node failed	Check error logs

Each node execution has step-level states:

Status	Meaning
`PENDING`	Dependencies not ready
`RUNNING`	Currently executing
`COMPLETED`	Finished successfully
`FAILED`	Encountered an error
`SKIPPED`	Not executed (e.g., branch not taken)

Monitoring Execution

Get Execution Status

GET /usage/executions/{execution_id}

Response:

{
  "id": "exec-uuid-789",
  "type": "WORKFLOW_EXECUTION",
  "status": "RUNNING",
  "project_id": "proj-456",
  "meta": {
    "workflow_id": "workflow-uuid-123",
    "input": {
      "topic": "Artificial Intelligence"
    },
    "context": {
      "input": { /* original input */ },
      "nodes": {
        "fetch_data": {
          "markdown": "# AI Overview...",
          "url": "https://example.com"
        },
        "analyze": {
          "output": "Analysis: ...",
          "message_id": "msg-123"
        }
      },
      "workflow": {
        "id": "workflow-uuid-123",
        "name": "Research Workflow"
      }
    }
  },
  "created_at": "2026-02-21T10:00:00.000Z",
  "updated_at": "2026-02-21T10:05:30.000Z"
}

Get Detailed Logs

GET /usage/executions/{execution_id}/logs

Response:

[
  {
    "id": "log-1",
    "execution_id": "exec-uuid-789",
    "node_id": "fetch_data",
    "status": "COMPLETED",
    "input": {
      "url": "https://example.com"
    },
    "output": {
      "markdown": "# Content...",
      "url": "https://example.com"
    },
    "error": null,
    "started_at": "2026-02-21T10:00:10.000Z",
    "completed_at": "2026-02-21T10:00:45.000Z"
  },
  {
    "id": "log-2",
    "execution_id": "exec-uuid-789",
    "node_id": "analyze",
    "status": "RUNNING",
    "input": {
      "agent_name_slug": "analyzer"
    },
    "output": null,
    "error": null,
    "started_at": "2026-02-21T10:00:46.000Z",
    "completed_at": null
  }
]

Performance Characteristics

Execution Speed Factors

Node duration: How long each step takes
Parallelization: Nodes without dependencies run together
Batch size: 5 nodes per tick (limits parallelism)
Async operations: External APIs determine speed

Example Timings

Scenario 1: Sequential Pipeline

Node A: 3 seconds
Node B: 2 seconds — runs after Node A
Node C: 4 seconds — runs after Node B
Total: 9 seconds (3 + 2 + 4)
Ticks: 3 (A, B, C)

Scenario 2: Parallel Operations

Node A: 3 seconds — all run in Tick 1 (parallel)
Node B: 2 seconds — all run in Tick 1 (parallel)
Node C: 4 seconds — all run in Tick 1 (parallel)
Total: 4 seconds (max of all)
Ticks: 1

Scenario 3: Mixed

Tick 1: A (3s), B (2s)
Tick 2: C (depends on A+B, 4s)
Tick 3: D (depends on C, 2s)
Total: 9 seconds
Ticks: 3

Error Handling

Node Failure

When a node fails:

Step is marked as FAILED
Error details are logged
Dependent nodes become SKIPPED
Workflow status becomes FAILED
Execution stops processing

Example:

{
  "node_id": "analyze",
  "status": "FAILED",
  "error": "Agent timeout after 60 seconds",
  "error_code": "TIMEOUT",
  "started_at": "2026-02-21T10:00:46.000Z",
  "failed_at": "2026-02-21T10:01:46.000Z"
}

Timeout Handling

Each node has configurable timeout:

Default: 300 seconds (5 minutes)
Configurable: Per node in parameters
On timeout: Node marked as FAILED, workflow halted

Advanced Features

Tick Continuation

When a tick completes with remaining work:

{
  "execution_id": "exec-uuid-789",
  "next_tick": {
    "ready_nodes": ["analyze_a", "analyze_b", "parallel_container"],
    "count": 3
  }
}

The engine automatically publishes to Pub/Sub for next tick.

Context Persistence

Workflow context remains in memory and persistent storage:

input: Original input data
nodes: Outputs of all completed nodes
workflow: Workflow metadata
loop: Current loop iteration data (for loop nodes)

All variables are available via Jinja2 interpolation in downstream nodes.

Next Steps

Node Types - Available node types for workflows
Dependencies - How to define execution order
Execution Variables - Access data between nodes

Getting Started

Concepts

Agents

Tools

Datasources

Workflows

Jobs

Triggers

Monitor

Execution Model Overview

Key Concepts

Tick-Based Scheduling

Batch Processing

Asynchronous Continuation

Execution Lifecycle

Step 1: Workflow Trigger

Step 2: First Tick Processing

Step 3: Subsequent Ticks

Step 4: Async Completion

Step 5: Workflow Completion

Execution States

Monitoring Execution

Get Execution Status

Get Detailed Logs

Performance Characteristics

Execution Speed Factors

Example Timings

Error Handling

Node Failure

Timeout Handling

Advanced Features

Tick Continuation

Context Persistence

Next Steps

​Execution Model Overview

​Key Concepts

​Tick-Based Scheduling

​Batch Processing

​Asynchronous Continuation

​Execution Lifecycle

​Step 1: Workflow Trigger

​Step 2: First Tick Processing

​Step 3: Subsequent Ticks

​Step 4: Async Completion

​Step 5: Workflow Completion

​Execution States

​Monitoring Execution

​Get Execution Status

​Get Detailed Logs

​Performance Characteristics

​Execution Speed Factors

​Example Timings

​Error Handling

​Node Failure

​Timeout Handling

​Advanced Features

​Tick Continuation

​Context Persistence

​Next Steps

Execution Model Overview

Key Concepts

Tick-Based Scheduling

Batch Processing

Asynchronous Continuation

Execution Lifecycle

Step 1: Workflow Trigger

Step 2: First Tick Processing

Step 3: Subsequent Ticks

Step 4: Async Completion

Step 5: Workflow Completion

Execution States

Monitoring Execution

Get Execution Status

Get Detailed Logs

Performance Characteristics

Execution Speed Factors

Example Timings

Error Handling

Node Failure

Timeout Handling

Advanced Features

Tick Continuation

Context Persistence

Next Steps