> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 06.2 builder

# Workflow Builder

The **Workflow Builder** is the primary way to create workflows in BindAI.

It provides a fluent API for constructing workflow graphs by connecting nodes together in a readable and maintainable way.

Instead of manually managing workflow objects and connections, the builder handles the structure for you.

***

# Why Use the Builder?

A workflow is fundamentally a graph.

Managing nodes and connections manually quickly becomes difficult as workflows grow.

The builder simplifies this process by allowing workflows to be constructed step by step.

***

# Builder Pattern

The builder follows a fluent interface.

Conceptually:

```text id="wb1n4p" theme={null}
Create Builder

↓

Add Nodes

↓

Connect Nodes

↓

Validate

↓

Build Workflow
```

Each operation returns the builder, allowing calls to be chained together.

***

# Creating a Builder

A workflow begins with a builder instance.

```python id="x6d9pt" theme={null}
from bindai_workflow import WorkflowBuilder

builder = WorkflowBuilder(
    name="Customer Support",
)
```

At this point the workflow exists only in memory.

***

# Defining a Start Node

Every workflow begins with a start node.

```python id="m2q8rc" theme={null}
builder.start_node()
```

This creates the workflow entry point.

***

# Adding Nodes

Nodes are added sequentially.

Example:

```python id="t5v1ke" theme={null}
builder.start_node()

builder.agent(
    support_agent,
)

builder.end_node()
```

Each node becomes connected to the previous node automatically.

***

# Fluent Chaining

Because the builder is fluent, workflows can also be written as a chain.

```python id="y4w7bf" theme={null}
workflow = (
    WorkflowBuilder()
    .start_node()
    .agent(agent)
    .end_node()
    .build()
)
```

This style is common for simple workflows.

***

# Building the Workflow

When construction is complete:

```python id="k9e3xm" theme={null}
workflow = builder.build()
```

The builder validates the workflow before returning it.

If validation fails, an exception is raised describing the problem.

***

# Validation

The builder automatically checks common workflow errors.

Examples include:

* missing start node
* unreachable nodes
* duplicate node identifiers
* invalid connections
* missing end node

Validation helps detect problems before execution begins.

***

# Registering Agents

When an agent node is added, the builder automatically registers the agent with the workflow.

Conceptually:

```text id="wb2f7u" theme={null}
Agent

↓

Builder

↓

Workflow Registry
```

This allows agent nodes to reference the registered agent during execution.

***

# Conditional Branches

Builders can create branching workflows.

Conceptually:

```text id="wb3k5m" theme={null}
Agent

↓

Condition

↙       ↘

Yes     No
```

The condition determines which branch executes next.

***

# Loops

Loops allow sections of a workflow to repeat.

```text id="wb4c8q" theme={null}
Node

↓

Condition

↓

Repeat

↓

Continue
```

The loop exits when its predicate evaluates to false.

***

# Parallel Execution

Builders also support parallel branches.

```text id="wb5x2n" theme={null}
Parallel

↙      ↓      ↘

A      B      C

↓

Join
```

Each branch executes independently before synchronization.

***

# Human Tasks

Human approval can be inserted into a workflow.

```text id="wb6p4j" theme={null}
Agent

↓

Human Task

↓

Resume

↓

Continue
```

The workflow pauses until the human task is completed.

***

# Variables

The builder does not manage workflow data directly.

Instead, nodes communicate through workflow variables stored in the execution context.

```text id="wb7h9r" theme={null}
Node A

↓

Variables

↓

Node B
```

This keeps nodes independent and reusable.

***

# Large Workflows

As workflows become larger, organizing related sections together improves readability.

Example structure:

```text id="wb8m6y" theme={null}
Start

↓

Preparation

↓

Processing

↓

Validation

↓

Completion
```

Grouping related steps makes workflows easier to maintain.

***

# Best Practices

* Start with a clear workflow objective.
* Keep nodes focused on a single responsibility.
* Use fluent chaining for small workflows.
* Use intermediate variables for complex workflows.
* Validate workflows before deployment.
* Prefer multiple small workflows over one extremely large workflow.
* Separate orchestration logic from business logic.

***

# Summary

The Workflow Builder provides a simple, fluent interface for constructing workflow graphs.

It automatically manages node registration, connections, and validation, allowing developers to focus on workflow behavior rather than graph implementation details.