Workflow Basic Template

The Workflow Basic template demonstrates the simplest linear workflow you can build with BindAI. It introduces the core concepts of the workflow engine by defining a workflow containing nodes that execute sequentially. This template is the recommended starting point for understanding how BindAI workflows are created, executed, and extended. Once the basic execution model is understood, additional workflow features such as conditions, loops, parallel execution, retries, timeout protection, human tasks, and scheduling can be introduced.

Purpose

This template demonstrates how to:

Create a workflow
Add workflow nodes
Establish the starting node
Execute nodes sequentially
Share variables through the workflow context
Produce a WorkflowResult
Observe workflow execution through workflow events

The example intentionally avoids advanced control-flow and execution-management features.

Workflow Structure

A basic workflow consists of workflow nodes connected through their next_nodes. Conceptually:

First Node
    |
    v
Second Node
    |
    v
Third Node

BindAI does not require special built-in StartNode or EndNode objects for a basic workflow. Instead, the first node added to a Workflow automatically becomes its starting node. For example:

workflow = Workflow("basic")

workflow.add_node(first_node)
workflow.add_node(second_node)
workflow.add_node(third_node)

When the first node is added, the workflow records that node as start_node if no start node has been configured yet. The nodes themselves determine the next execution path through their next_nodes relationships.

Creating a Workflow

A workflow can be created with an optional name:

workflow = Workflow("basic")

The workflow maintains:

id
version
name
nodes
start_node
agents
executor

The workflow executor is responsible for executing workflow instances.

Adding Nodes

Nodes are added to the workflow with:

workflow.add_node(node)

The workflow stores nodes by their identifiers. The first node added becomes the starting node:

workflow.add_node(first_node)

After that call:

workflow.start_node

references the first node’s identifier. Adding additional nodes does not automatically connect them. The node relationships must be established through the node implementation and its next_nodes configuration.

Execution Flow

A basic workflow execution follows this general sequence:

Workflow.run()
      |
      v
Create Workflow Instance
      |
      v
Copy Context Variables
      |
      v
WorkflowExecutor.execute()
      |
      v
Add Start Node to Queue
      |
      v
Execute Nodes
      |
      v
WorkflowResult

The executor maintains an execution queue for pending nodes. The starting node is added to that queue when execution begins.

Running a Workflow

A workflow can be executed with:

result = workflow.run()

When no context is provided, Workflow.run() creates a new ExecutionContext. A context can also be supplied explicitly:

context = ExecutionContext()

result = workflow.run(context)

The workflow copies variables from the supplied context into the workflow instance context before execution.

Workflow Context

Each workflow instance has an execution context. The context contains execution state used by the workflow runtime. Variables are particularly important for sharing data between nodes. Conceptually:

Node A
  |
  | writes variables
  v
Workflow Context
  |
  | reads variables
  v
Node B

For example, a node may write:

context.variables["customer"] = customer

A later node can then access that value through the same workflow context. The exact variables available depend on the nodes and application logic.

Workflow Result

A successful workflow execution returns a WorkflowResult. The current executor returns the workflow context variables as the result output:

result.output

Conceptually:

Workflow
   |
   v
Execution Context
   |
   v
Variables
   |
   v
WorkflowResult.output

A successful result has:

result.success is True

A failed execution has:

result.success is False

and provides an error:

result.error

Node Execution

The executor processes one node at a time from the workflow execution queue. The general flow is:

Get Next Node
     |
     v
Execute Node
     |
     v
Node Completed
     |
     v
Add Next Nodes
     |
     v
Repeat

For each node, the executor calls:

node.execute(context)

After successful execution, the node’s next-node relationships are used to determine what executes next. A node can also influence execution through the workflow context.

Workflow Events

The workflow executor emits workflow events during execution. Important events include:

workflow.started
node.started
node.completed
workflow.completed
workflow.failed

Conceptually:

workflow.started
       |
       v
node.started
       |
       v
node.completed
       |
       v
...
       |
       v
workflow.completed

Failures produce:

workflow.failed

These events are stored on the workflow execution context and can be used by application-level observability and event handling.

Execution State

The workflow runtime maintains execution state in the workflow instance context. Important execution information includes:

Current execution queue
Variables
Completion state
Waiting state
Errors
Retry attempt
Timeout policy
Retry policy
Execution timestamps
Events

This state allows the executor to determine what should happen next.

In-Memory Storage

The current Workflow implementation creates a WorkflowExecutor using a MemoryWorkflowStore. The executor also uses a MemoryHistoryStore by default. Conceptually:

Workflow
   |
   v
WorkflowExecutor
   |
   +---- MemoryWorkflowStore
   |
   └---- MemoryHistoryStore

The workflow instance is saved during execution and at completion or failure. Execution history is also recorded. These are in-memory implementations and should not be interpreted as durable distributed workflow storage.

Execution History

The executor records workflow execution history after completion or failure. A history entry contains information such as:

Workflow ID
Workflow version
Instance ID
Start time
Finish time
Success state
Error information when execution fails

This provides a basic execution-history mechanism for the current runtime. The default history store is in memory.

Failure Handling

If a node raises an exception and no retry policy is configured, the workflow fails. Conceptually:

Execute Node
     |
     v
Exception
     |
     v
Workflow Failed

The failure is recorded in the workflow context and a workflow.failed event is emitted. The resulting WorkflowResult contains:

result.success is False
result.error

Retry

A workflow can use a retry policy for node failures. The executor checks the configured retry policy when a node raises an exception. For example:

RetryPolicy(
    max_attempts=3,
    delay_seconds=5,
    exponential_backoff=True,
)

The current executor uses max_attempts to control the number of attempts. The configured delay_seconds and exponential_backoff values are not currently applied. Therefore, retries currently occur immediately. Retry behavior is covered in more detail by: 08.6 workflow-retry.md

Timeout

The workflow executor can check a configured timeout policy during execution. The timeout is evaluated before each node is executed. Conceptually:

Workflow Running
      |
      v
Check Elapsed Time
      |
      +---- Within Limit ----> Execute Node
      |
      └---- Exceeded --------> Workflow Failed

If the timeout is exceeded, the workflow fails with:

Workflow timeout.

Timeout checking does not forcibly terminate a node that is already running. Timeout behavior is covered in more detail by: 08.7 workflow-timeout.md

Waiting and Resuming

Some workflow nodes can place the workflow into a waiting state. When the executor encounters a waiting state, it can return the current workflow result instead of continuing normal execution. A paused workflow can later be resumed through:

executor.resume(instance)

The resume operation clears the waiting state and continues execution. This behavior is particularly important for human-in-the-loop workflows. Human-task behavior is covered in: 08.5 workflow-human.md

Cloning a Workflow

A workflow can be cloned with:

new_workflow = workflow.clone()

The current implementation creates a deep copy and increments the workflow version. Conceptually:

Workflow v1
    |
    | clone()
    v
Workflow v2

This can be useful when creating a new workflow version while preserving the existing workflow definition.

Basic Example

A minimal workflow follows this general structure:

from bindai_core.context import ExecutionContext
from bindai_workflow import Workflow

workflow = Workflow("basic")

workflow.add_node(first_node)
workflow.add_node(second_node)

context = ExecutionContext()

result = workflow.run(context)

The actual nodes determine:

What work is performed
What variables are written
Which nodes execute next
Whether execution waits
Whether execution succeeds or fails

The workflow itself provides the execution container and delegates execution to WorkflowExecutor.

When to Use

Use the Workflow Basic pattern when you want to:

Learn how BindAI workflows execute
Build a simple linear workflow
Test workflow nodes
Prototype workflow logic
Understand workflow context and variables
Build a foundation for more advanced workflows

It is particularly useful before introducing branching or execution-management features.

Extending the Workflow

Once the basic execution model is understood, additional workflow features can be introduced. For example:

Node
  |
  v
Condition
 /      \
A        B

Or:

Node
  |
  v
Loop
  |
  v
Next Node

Or:

       Parallel
       /      \
   Branch A  Branch B
       \      /
        Join
          |
          v
       Next Node

Other execution features include:

Human tasks
Retry policies
Timeout policies
Scheduling
Subworkflows
Workflow events

These features build on the same workflow execution model.

Best Practices

When building a basic workflow:

Start with a small number of nodes.
Give nodes clear identifiers.
Explicitly define node relationships.
Keep shared state in the workflow context when appropriate.
Handle node failures deliberately.
Test both successful and failing execution paths.
Use retry policies only for recoverable failures.
Use timeout policies for workflows that require execution limits.
Treat the default in-memory stores as development-oriented storage.
Add observability when workflows become more complex.

Current Implementation Boundaries

The basic workflow runtime currently has several important boundaries.

No special Start Node

The workflow does not require a built-in StartNode. The first node added to the workflow becomes the starting node.

No special End Node

The workflow does not require a built-in EndNode. Execution completes when the execution queue is exhausted or another terminal execution condition occurs.

In-memory persistence

The default workflow and history stores are in memory. They do not provide durable distributed workflow persistence.

Retry delay

Retry configuration exposes delay and exponential-backoff fields, but the current executor does not apply them.

Timeout interruption

Timeout checking happens between node executions. It does not forcibly terminate a currently running node.

The Workflow Basic template introduces the core execution model used throughout the workflow templates. The remaining templates build on these concepts:

08.2 workflow-condition.md
08.3 workflow-loop.md
08.4 workflow-parallel.md
08.5 workflow-human.md
08.6 workflow-retry.md
08.7 workflow-timeout.md
08.8 workflow-schedule.md

Each template focuses on a specific workflow capability while using the same underlying workflow execution model.

Summary

The Workflow Basic template demonstrates the fundamental BindAI workflow execution model. A workflow:

Workflow
   |
   v
Workflow Instance
   |
   v
Execution Context
   |
   v
Execution Queue
   |
   v
Workflow Nodes
   |
   v
WorkflowResult

The first node added becomes the workflow’s starting node. The executor processes nodes sequentially, updates the workflow context, records execution events, persists the current instance in the configured store, records execution history, and returns a WorkflowResult. This basic model provides the foundation for conditions, loops, parallel execution, human tasks, retries, timeout protection, and other workflow capabilities.

​Workflow Basic Template

​Purpose

​Workflow Structure

​Creating a Workflow

​Adding Nodes

​Execution Flow

​Running a Workflow

​Workflow Context

​Workflow Result

​Node Execution

​Workflow Events

​Execution State

​In-Memory Storage

​Execution History

​Failure Handling

​Retry

​Timeout

​Waiting and Resuming

​Cloning a Workflow

​Basic Example

​When to Use

​Extending the Workflow

​Best Practices

​Current Implementation Boundaries

​No special Start Node

​No special End Node

​In-memory persistence

​Retry delay

​Timeout interruption

​Related Templates

​Summary