Workflow Human Template

The Workflow Human template demonstrates how BindAI can introduce a human interaction point into a workflow. The HumanTaskNode creates a HumanTask, associates it with the current workflow instance and node, stores it on the workflow context, and sets the context to a waiting state. The node provides the workflow-engine side of human interaction. The actual user interface, task handling, completion, and resumption mechanism are outside the HumanTaskNode implementation.

Purpose

This template demonstrates how to:

Create a human task
Associate the task with a workflow instance
Associate the task with a workflow node
Store the task in the workflow context
Put the workflow context into a waiting state
Configure an optional assignee
Configure an optional form identifier

Workflow Structure

A workflow can place a Human Task node between normal workflow nodes.

Previous Node
      |
      v
Human Task
      |
      v
Waiting

When the HumanTaskNode executes, it creates a task, stores it in the workflow context, and sets:

context.waiting = True

HumanTaskNode

The implementation is provided by HumanTaskNode. A node can be created with:

HumanTaskNode(
    node_id="approval",
    assignee="manager",
    form="approval-form",
)

The constructor accepts:

Parameter	Description
`node_id`	Identifier of the workflow node
`assignee`	Optional assignee identifier
`form`	Optional form identifier
`name`	Optional workflow node name

The assignee and form values are configuration stored on the node. The node itself does not perform assignment, notification, or form rendering.

Task Creation

When the node executes, it creates a new HumanTask. The task receives a generated UUID:

task = HumanTask(
    id=str(uuid.uuid4()),
    workflow_instance=context.instance.id,
    node_id=self.id,
    created_at=datetime.utcnow(),
)

The created task contains:

A generated task ID
The current workflow instance ID
The ID of the Human Task node
The task creation timestamp

The task is created each time the node executes.

Workflow Instance Association

The task records the ID of the current workflow instance:

workflow_instance=context.instance.id

This provides a link between the created task and the workflow execution that produced it. Conceptually:

Workflow Instance
       |
       v
HumanTaskNode
       |
       v
HumanTask
       |
       v
Workflow Instance ID

Node Association

The task also records the ID of the node that created it:

node_id=self.id

This allows the task to be associated with the specific HumanTaskNode in the workflow definition.

Task Storage

After creating the task, the node stores it on the workflow context:

context.task = task

Conceptually:

HumanTaskNode
      |
      v
HumanTask
      |
      v
context.task

The surrounding workflow/application infrastructure can therefore access the task through the current workflow context.

Waiting State

After storing the task, the node sets:

context.waiting = True

The resulting state is:

Execute Human Task
       |
       v
Create HumanTask
       |
       v
Store in context.task
       |
       v
context.waiting = True

This tells the workflow execution system that the context has entered a waiting state. The HumanTaskNode itself does not implement the external interaction or completion mechanism.

External Task Handling

HumanTaskNode does not provide a user interface. A surrounding application can use the created task in systems such as:

A web application
An administrative dashboard
An approval interface
A mobile application
An internal task-management system

The workflow node is responsible for creating the runtime task and entering the waiting state. The surrounding application is responsible for deciding how that task is presented and handled.

Assignee

A Human Task node can optionally specify an assignee:

HumanTaskNode(
    node_id="approval",
    assignee="manager",
)

The value is stored on the node:

self.assignee = assignee

The implementation does not itself:

Resolve the assignee
Notify the assignee
Assign the task through an external system
Enforce permissions

The value is configuration available to the surrounding application.

Form

A Human Task node can also specify an optional form identifier:

HumanTaskNode(
    node_id="review",
    form="review-form",
)

The value is stored on the node:

self.form = form

The node does not render or process the form. The surrounding application can use the form identifier to determine which external form or interface should be presented.

Task IDs

Each task receives a newly generated UUID:

str(uuid.uuid4())

Therefore, separate executions of the node produce separate task IDs. Conceptually:

Human Task execution 1
        |
        v
     Task ID A

Human Task execution 2
        |
        v
     Task ID B

Task Lifecycle

The lifecycle implemented directly by HumanTaskNode is intentionally small:

HumanTaskNode executes
        |
        v
Create HumanTask
        |
        v
Store task in context.task
        |
        v
Set context.waiting = True

The node does not implement a complete human-task lifecycle. In particular, it does not provide methods for:

Approving a task
Rejecting a task
Completing a task
Collecting form responses
Notifying an assignee
Persisting the task in an external task system
Resuming the workflow after human interaction

Those responsibilities belong to the surrounding workflow or application infrastructure.

Workflow Waiting

The node’s waiting behavior should be distinguished from task completion. The node only sets:

context.waiting = True

It does not define what external action clears that state or how a workflow is subsequently resumed. Therefore, a complete human-in-the-loop application needs additional infrastructure around the workflow runtime. Conceptually:

HumanTaskNode
      |
      v
Create Task
      |
      v
Waiting
      |
      v
External Application
      |
      v
Application-specific handling
      |
      v
Application-specific workflow continuation

The exact continuation mechanism depends on the surrounding workflow implementation.

Serialization

HumanTaskNode extends the normal workflow-node serialization. Its to_dict() method adds:

{
    "assignee": self.assignee,
    "form": self.form,
}

For example, a serialized node can contain:

{
    "assignee": "manager",
    "form": "approval-form",
}

The node configuration can therefore be included when the workflow definition is serialized.

Loading Configuration

The node restores its optional configuration through load_dict():

self.assignee = data.get("assignee")
self.form = data.get("form")

If either value is absent, it becomes None. Conceptually:

Serialized workflow data
        |
        v
HumanTaskNode.load_dict()
        |
        +----> assignee
        |
        +----> form

Human + AI Workflow

A common pattern is to place human review after an AI operation:

AI Agent
   |
   v
Human Task
   |
   v
Waiting

For example, an agent could produce a document and the workflow could then create a human review task. The HumanTaskNode does not perform the review. It creates the runtime task and places the workflow context into the waiting state.

Human Tasks vs Conditions

These nodes serve different purposes.

Human Task	Condition
Creates a `HumanTask`	Evaluates a predicate
Stores task in context	Selects a workflow path
Sets `context.waiting`	Routes execution
Represents external interaction	Represents automatic logic

They can be combined in a larger workflow. For example:

Human Task
    |
    v
Waiting
    |
    v
Application-specific continuation
    |
    v
Condition
   / \
  v   v
Approved  Rejected

The actual human completion and continuation mechanism is outside the HumanTaskNode.

Human Tasks vs Loops

Human Tasks and loops also have different purposes.

Human Task	Loop
Represents external human interaction	Repeats workflow logic
Creates a `HumanTask`	Evaluates a predicate
Sets `context.waiting`	Sets `context.current_node`
Depends on external handling	Controls workflow routing

A loop controls workflow routing based on its predicate. A Human Task introduces a waiting point for external interaction.

Example

A document-review workflow can be structured conceptually as:

Agent
  |
  v
Human Review
  |
  v
Waiting

When the Human Review node executes:

HumanTask created
       |
       v
context.task = task
       |
       v
context.waiting = True

The surrounding application can then inspect the task and provide the appropriate human interface.

Human Task Configuration Example

A node with both optional configuration values can be created as:

review = HumanTaskNode(
    node_id="human-review",
    assignee="manager",
    form="document-review",
    name="Document Review",
)

The node retains:

review.assignee
review.form
review.name

When executed, the runtime task is still created by the node’s execute() method and stored in:

context.task

The assignee and form values remain node configuration; they are not automatically copied into the HumanTask object by this implementation.

Important Implementation Boundaries

The current HumanTaskNode does:

Create a HumanTask
Generate a unique task ID
Associate the task with context.instance.id
Associate the task with the node ID
Set the task creation timestamp
Store the task in context.task
Set context.waiting = True
Serialize assignee and form
Restore assignee and form from serialized data

The current HumanTaskNode does not:

Approve a task
Reject a task
Complete a task
Collect form responses
Notify an assignee
Render a form
Persist tasks to an external task-management system
Automatically resume the workflow

These boundaries are important when integrating human interaction into an application.

Best Practices

Give each Human Task node a meaningful node_id.
Use assignee when surrounding application infrastructure needs an intended task owner.
Use form when an external interface needs to identify the appropriate form.
Keep human-facing UI outside the workflow node.
Use context.task to access the task created by the node during execution.
Provide application infrastructure for handling waiting workflows.
Define an explicit continuation strategy for human interactions.
Keep human interaction concerns separate from workflow-definition logic.
Avoid assuming that assignee or form automatically trigger external behavior.

Summary

The Workflow Human template demonstrates how BindAI introduces a human interaction point into workflow execution. HumanTaskNode creates a uniquely identified HumanTask, associates it with the current workflow instance and node, stores it in context.task, and sets:

context.waiting = True

The node supports optional assignee and form configuration and can serialize and restore those values. The node itself does not implement approval, rejection, form handling, notifications, task persistence, or workflow resumption. Those responsibilities belong to the surrounding workflow and application infrastructure.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

08.5 workflow human

Workflow Human Template

Purpose

Workflow Structure

HumanTaskNode

Task Creation

Workflow Instance Association

Node Association

Task Storage

Waiting State

External Task Handling

Assignee

Form

Task IDs

Task Lifecycle

Workflow Waiting

Serialization

Loading Configuration

Human + AI Workflow

Human Tasks vs Conditions

Human Tasks vs Loops

Example

Human Task Configuration Example

Important Implementation Boundaries

Best Practices

Summary

​Workflow Human Template

​Purpose

​Workflow Structure

​HumanTaskNode

​Task Creation

​Workflow Instance Association

​Node Association

​Task Storage

​Waiting State

​External Task Handling

​Assignee

​Form

​Task IDs

​Task Lifecycle

​Workflow Waiting

​Serialization

​Loading Configuration

​Human + AI Workflow

​Human Tasks vs Conditions

​Human Tasks vs Loops

​Example

​Human Task Configuration Example

​Important Implementation Boundaries

​Best Practices

​Summary

Workflow Human Template

Purpose

Workflow Structure

HumanTaskNode

Task Creation

Workflow Instance Association

Node Association

Task Storage

Waiting State

External Task Handling

Assignee

Form

Task IDs

Task Lifecycle

Workflow Waiting

Serialization

Loading Configuration

Human + AI Workflow

Human Tasks vs Conditions

Human Tasks vs Loops

Example

Human Task Configuration Example

Important Implementation Boundaries

Best Practices

Summary