> ## 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.

# 10.2 workflow

# Workflow API Reference

The `Workflow` class represents an executable workflow definition in BindAI.

A workflow organizes nodes into an execution graph, allowing agents, tools, conditions, loops, parallel branches, human tasks, retries, and scheduling to work together as a single automated process.

This page documents the public Workflow API.

***

# Overview

A workflow coordinates execution between multiple nodes.

Conceptually:

```text id="api-workflow-1" theme={null}
Start

↓

Workflow Nodes

↓

End
```

Each node performs a specific task before passing execution to the next node.

***

# Creating a Workflow

Workflows are typically created using the `WorkflowBuilder`.

Example:

```python id="api-workflow-2" theme={null}
builder = WorkflowBuilder()

workflow = builder.build()
```

Using the builder is the recommended approach because it validates the workflow before execution.

***

# Workflow Components

A workflow generally contains:

* workflow identifier
* workflow name
* nodes
* start node
* workflow context
* registered agents
* execution metadata

These components define the workflow's structure and behavior.

***

# WorkflowBuilder

The builder provides a fluent interface for constructing workflows.

Typical methods include:

| Method    | Purpose                            |
| --------- | ---------------------------------- |
| `start()` | Defines the first node             |
| `then()`  | Connects the next node             |
| `add()`   | Adds an independent node           |
| `build()` | Validates and returns the workflow |

The builder simplifies workflow construction while preventing invalid structures.

***

# Executing a Workflow

A workflow is executed through its executor.

Example:

```python id="api-workflow-3" theme={null}
result = workflow.executor.run(
    input="Hello"
)
```

The executor traverses the workflow graph until execution completes.

***

# Workflow Context

Every execution receives a workflow context.

Conceptually:

```text id="api-workflow-4" theme={null}
Input

↓

Workflow Context

↓

Nodes

↓

Output
```

The context stores variables that are shared between nodes.

***

# Workflow Variables

Nodes communicate through workflow variables.

Example:

```text id="api-workflow-5" theme={null}
Agent

↓

result

↓

Condition

↓

approved
```

Variables remain available throughout workflow execution.

***

# Registered Agents

A workflow may contain one or more registered agents.

```text id="api-workflow-6" theme={null}
Workflow

↓

Agent Registry

↓

Agent Nodes
```

Agent nodes reference registered agents by name.

***

# Workflow Nodes

A workflow is composed of nodes.

Common node types include:

* Start
* End
* Agent
* Condition
* Loop
* Parallel
* Human Task

Each node performs a single responsibility within the execution graph.

***

# Execution Graph

Nodes are connected to form a directed execution graph.

```text id="api-workflow-7" theme={null}
Node A

↓

Node B

↓

Node C
```

Some nodes, such as Conditions and Parallel nodes, create multiple outgoing paths.

***

# Validation

Before execution, workflows should be validated.

The validator checks for:

* missing start node
* unreachable nodes
* invalid references
* structural errors

Validation helps detect problems during development rather than at runtime.

***

# Workflow Result

Workflow execution returns a result object.

Typical information includes:

| Property | Description                                        |
| -------- | -------------------------------------------------- |
| success  | Indicates whether execution completed successfully |
| output   | Workflow variables after execution                 |
| error    | Execution error, if any                            |

Applications should inspect the result before using workflow outputs.

***

# Serialization

Workflows can be serialized for storage or transport.

Typical methods include:

* `to_dict()`
* `load_dict()`

Serialization makes it possible to save workflow definitions or exchange them between systems.

***

# Human Tasks

If a Human Task node is encountered, execution pauses.

```text id="api-workflow-8" theme={null}
Workflow

↓

Human Task

↓

Waiting
```

The executor resumes only after the task has been completed.

***

# Scheduling

Workflows may be executed manually or by the scheduler.

```text id="api-workflow-9" theme={null}
Workflow Schedule

↓

Workflow

↓

Result
```

Scheduling is managed separately from workflow execution.

***

# Retry and Timeout

Workflows may use execution policies such as:

* RetryPolicy
* TimeoutPolicy

These improve reliability when interacting with external systems.

***

# Best Practices

* Build workflows using `WorkflowBuilder`.
* Keep nodes focused on one responsibility.
* Store shared state in workflow variables.
* Validate workflows before deployment.
* Separate orchestration from AI reasoning.
* Use conditions instead of embedding business logic in prompts.
* Combine retries and timeouts for production workflows.

***

# Related APIs

The Workflow API works closely with:

* Agent
* Project
* Tool
* WorkflowBuilder
* WorkflowExecutor

Together these components provide BindAI's orchestration capabilities.

***

# Summary

The `Workflow` class defines how tasks execute within BindAI.

By organizing nodes into a validated execution graph, workflows enable sequential processing, branching, loops, parallel execution, human approval, scheduling, and other advanced orchestration patterns while keeping business logic modular and reusable.