Human Tasks

Human Tasks allow a workflow to pause automated execution and wait for a human decision before continuing. BindAI V1 supports Human Tasks as a real workflow control-flow mechanism. A workflow can reach a Human Task, persist its execution state, remain in a waiting state, and later resume after an approval or rejection is submitted. This makes Human Tasks useful for approval, review, validation, and other human-in-the-loop workflows.

What Is a Human Task?

A Human Task is a workflow node that pauses execution until a human action is provided. A typical flow is:

Workflow
   |
   v
Human Task
   |
   v
Waiting
   |
   v
Human Decision
   |
   +---- Approved ----> Continue
   |
   +---- Rejected ----> Alternative Path

Unlike an ordinary node, a Human Task does not complete the workflow immediately. When execution reaches the node, the workflow creates a task, marks the execution as waiting, and stops progressing until the task is completed.

Why Use Human Tasks?

Human Tasks are useful when automated processing should pause for human review or approval. Common examples include:

Reviewing AI-generated content
Approving a proposed action
Reviewing a classification
Validating a workflow result
Approving a publishing action
Handling exceptions
Requiring confirmation before continuing

The important distinction is that the human decision becomes part of workflow control flow.

Human Task Execution

A Human Task participates directly in the workflow graph. For example:

Start
  |
  v
Agent
  |
  v
Human Task
  |
  +---- Approved ----> Tool
  |
  +---- Rejected ----> End

When the workflow reaches the Human Task:

A Human Task is created.
The workflow context records the task.
The workflow enters a waiting state.
Downstream nodes do not execute.
An external caller submits a decision.
The workflow resumes.
The selected outcome determines the next workflow path.

Waiting State

The runtime exposes the waiting state through the workflow execution result. Conceptually:

Running
   |
   v
Human Task
   |
   v
Waiting = True
   |
   | Human action
   v
Waiting = False
   |
   v
Continue

A waiting workflow is not treated as successfully completed. It is an execution that has paused until the required human action is supplied.

Human Task Data

The runtime task contains information identifying the task and its workflow node. The verified task state includes:

Task identifier
Node identifier
Assignee
Role
Completion status
Result
Creation timestamp

For example, the Studio API can expose a task in a response similar to:

{
  "id": "3c99dc8f-6e31-4caa-bbd1-6adf2acb2f44",
  "node_id": "human",
  "assignee": "v1-test",
  "role": "",
  "completed": false,
  "result": null,
  "created_at": "2026-10-03T20:08:05.978833+00:00"
}

The exact identifiers and timestamps naturally differ for every execution.

Human Task Outcomes

BindAI V1 supports decision outcomes that can be represented by workflow edges. The verified Studio workflow path uses:

approved
rejected

For example:

Human Task
     |
     +---- approved ----> Continue
     |
     +---- rejected -----> Alternative Path

The workflow definition determines what happens after each outcome.

Approval Workflow

A typical approval workflow can be structured as:

Start
  |
  v
Agent
  |
  v
Human Task
 /       \
approved rejected
 |          |
 v          v
Tool       End

The workflow pauses at the Human Task. When approved is submitted, execution follows the approved path. When rejected is submitted, execution follows the rejected path.

Human Tasks and Conditions

Human Tasks and Conditions provide different forms of decision-making.

Human Task	Condition
Waits for an external human decision	Evaluates workflow state
Pauses workflow execution	Normally evaluates during execution
Produces a human outcome	Produces a programmatic branch
Useful for approval and review	Useful for deterministic control flow

They can also be combined.

Agent
  |
  v
Human Task
  |
  v
Condition
 /      \
Yes      No
 |        |
 v        v
Continue Alternative

The Human Task can first obtain human input, after which a Condition can evaluate workflow state and select a path.

Human Tasks and Agents

Human Tasks work naturally with Agent nodes. For example:

Start
  |
  v
Agent
  |
  v
Human Task
  |
  +---- approved ----> End
  |
  +---- rejected -----> Agent

The Agent can prepare a recommendation, classification, draft, or other result. The Human Task then provides an explicit human decision before the workflow continues.

Human Tasks and Tools

A Tool can execute before or after a Human Task. For example:

Agent
  |
  v
Human Task
  |
  +---- approved ----> Tool
  |
  +---- rejected -----> End

This is useful when an external action should only happen after human approval. For example:

Prepare Action
     |
     v
Human Approval
     |
     v
Webhook Tool

The approval therefore becomes a control-flow boundary before the external operation.

Human Tasks and Connections

Human Tasks can be combined with connection-backed tools. For example:

Agent
  |
  v
Human Task
  |
  +---- approved ----> Webhook Tool

In BindAI V1, Webhook is the implemented Studio connection provider. A workflow can therefore pause for approval and only send an external webhook after the approved path is selected. The connection itself is responsible for external delivery. The Human Task is responsible for workflow control flow.

Human Tasks and Memory

Human Tasks can appear in workflows that also use Memory-enabled agents. For example:

Agent
  |
  +--> Memory
  |
  v
Human Task
  |
  v
Continue

Memory and Human Tasks have separate responsibilities:

Memory preserves supported agent conversation context.
Human Tasks pause workflow execution for human input.

The Human Task does not replace workflow or agent memory.

Human Tasks and Knowledge

Human review can also follow an Agent that uses Knowledge. For example:

Knowledge
    |
    v
Agent
    |
    v
Human Task
    |
    v
Publish

This can be useful when a workflow uses retrieved information to generate a result that should be reviewed before continuing. Knowledge provides the information used by the Agent. The Human Task provides the human control point.

Persistence

Human Tasks require workflow state to survive the waiting period. BindAI V1 persists workflow instances through the workflow store used by the runtime. The Studio runtime uses FileWorkflowStore for persistent workflow execution state. The persisted state includes information required to identify and restore the workflow instance, including:

Workflow identity
Workflow version
Execution context
Workflow variables
Human Task state
Waiting state
Execution result information

This allows a workflow to remain waiting without requiring the original process call to remain active.

Resume After Approval

A Human Task can be completed through the Studio API. The workflow execution first returns a waiting response. For example:

{
  "workflow": "v1-integration-test",
  "instance_id": "1d866614-8683-4bc1-904e-d77522a69877",
  "waiting": true,
  "human_task": {
    "completed": false
  }
}

The application can then submit the human decision for that workflow instance. For an approval:

{
  "action": "approved"
}

After successful completion, the workflow resumes:

{
  "workflow": "v1-integration-test",
  "instance_id": "1d866614-8683-4bc1-904e-d77522a69877",
  "waiting": false,
  "human_task": {
    "completed": true,
    "result": "approved"
  }
}

The exact identifiers depend on the workflow execution.

Studio API

The verified Studio API for Human Tasks is:

POST
/api/v1/studio/projects/{project_id}/workflows/{workflow_id}/run

to start the workflow. The run response can indicate that execution is waiting for a Human Task. The decision is then submitted through:

POST
/api/v1/studio/projects/{project_id}/workflows/{workflow_id}/instances/{instance_id}/human-task

with a request body such as:

{
  "action": "approved"
}

or:

{
  "action": "rejected"
}

Authentication uses the Studio API authentication mechanism.

Human Task Lifecycle

The verified V1 lifecycle is:

Workflow Starts
      |
      v
Human Task Node
      |
      v
Task Created
      |
      v
Waiting
      |
      | Human action
      v
Task Completed
      |
      v
Workflow Resumes
      |
      v
Next Node

This is different from a normal node because execution is intentionally interrupted between task creation and task completion.

Workflow Restart and Persistence

Human Tasks are particularly important for long-running workflows because the workflow does not need to remain inside the original request while waiting. The persisted workflow instance can be loaded later and resumed after the Human Task is completed. A useful lifecycle is:

Start Workflow
      |
      v
Create Human Task
      |
      v
Persist Instance
      |
      v
Waiting
      |
      | Application continues operating
      |
      v
Complete Human Task
      |
      v
Load Instance
      |
      v
Resume Workflow

BindAI V1 has verified this persistence and resume behavior through the Studio runtime.

Example: Approval Before an External Action

A practical workflow can combine Agents, Human Tasks, and connections:

Start
  |
  v
Agent
  |
  v
Human Task
  |
  +---- approved ----> Webhook Tool
  |                         |
  |                         v
  |                        End
  |
  +---- rejected -----> End

The Agent prepares the information. The Human Task pauses execution. The reviewer chooses an outcome. Only the approved branch reaches the Webhook Tool. This creates a clear human authorization point inside the workflow.

Human Tasks and Parallel Workflows

Human Tasks can participate in workflows that also use Parallel and Join nodes. For example:

Parallel
 /      \
Agent   Agent
  \      /
   Join
     |
     v
Human Task
     |
     v
Continue

The Join waits for the parallel branches to complete. The Human Task then pauses the workflow after the joined result is available. The two mechanisms therefore have different responsibilities:

Parallel executes independent branches.
Join synchronizes those branches.
Human Task waits for external human input.

Human Tasks Inside Loops

A Human Task can also participate in repeated workflow logic. Conceptually:

Loop
  |
  v
Process Item
  |
  v
Human Task
  |
  +---- approved ----> Update State
  |
  +---- rejected -----> Update State
                           |
                           v
                         Loop

This can be useful when each iteration requires human review. However, workflows should be designed carefully because a Human Task can cause each iteration to remain waiting until a human decision is supplied.

Human Tasks and Errors

A Human Task is different from an execution error. For example:

Human Task
    |
    v
Waiting

means the workflow is intentionally paused. It does not mean the workflow failed. By contrast:

Tool
  |
  v
Execution Error
  |
  v
Failed Result

represents an execution failure. Applications should distinguish:

Waiting
Successful completion
Rejected workflow path
Execution failure

These states have different meanings.

Approval and Rejection Are Workflow Outcomes

An approval or rejection should be treated as workflow control flow. For example:

Human Task
   |
   +---- approved ----> Publish
   |
   +---- rejected -----> Revise

The Human Task itself does not need to implement the business logic of publishing or revision. Those operations remain represented by downstream workflow nodes. This keeps the Human Task focused on collecting the human decision.

Human Task Assignment

The current V1 Human Task model contains task-level assignment information such as:

assignee
role

However, BindAI V1 does not provide a complete organizational task-management system. In particular, applications should not assume that BindAI automatically provides:

User directories
Teams
Department management
Permission administration
Task inboxes
Automatic reassignment
Escalation policies

Those concerns can be handled by the surrounding application when required.

User Interfaces

The workflow runtime does not require a particular Human Task user interface. An application can present a pending task using its own UI. Conceptually:

BindAI Workflow
      |
      v
Persisted Human Task
      |
      v
Application UI
      |
      v
Reviewer
      |
      v
Studio API
      |
      v
Workflow Resume

The workflow runtime remains responsible for execution state and control flow. The application UI is responsible for presenting the task to the human.

Long-Running Human Tasks

A Human Task can remain pending longer than a normal automated operation. For example:

Day 1
  |
  v
Human Task
  |
  | Waiting
  |
  |----------------|
                   |
                   v
                 Day 2
                   |
                   v
              Approval
                   |
                   v
                Resume

Because the workflow instance is persisted, the workflow does not need to complete the entire process during the initial API request. This makes Human Tasks suitable for workflows where human response may take an extended period.

Expiration and Escalation

BindAI V1 does not currently provide a verified built-in Human Task expiration or escalation system. Therefore, applications should not assume that a pending task will automatically:

Expire
Escalate
Reassign
Send reminders
Notify a manager
Cancel itself after a deadline

These behaviors can be added by a future workflow or application layer when the required runtime capabilities are implemented.

Auditability

Human Task state is persisted as part of the workflow instance. The verified state includes information such as:

Task identifier
Workflow instance
Node identifier
Assignee
Role
Completion state
Result
Creation time

A complete enterprise audit system is not currently part of the verified V1 Human Task feature. Applications requiring additional audit records should maintain those records at the application layer.

Security

Human Task completion should be protected by the application’s authorization model. The Studio API requires API authentication. Applications should additionally determine which authenticated users are allowed to submit decisions for a particular task or workflow. BindAI’s Human Task mechanism should not be interpreted as automatically providing:

Identity management
Role administration
Organization membership
Permission policies
User authentication

Those responsibilities belong to the application or deployment environment unless explicitly provided by another BindAI feature.

Duplicate Completion

Human Task completion should be treated as a state transition. Once a task has been completed, applications should not assume that submitting the same decision repeatedly is equivalent to creating a new decision. Application interfaces should therefore avoid presenting completed tasks as still actionable. For externally integrated approval systems, duplicate-submission protection should be handled explicitly.

Human Tasks and Retries

Human Tasks and retries solve different problems.

Human Task	Retry
Waits for a human decision	Re-executes failed work
Represents workflow control flow	Represents failure recovery
Can remain pending	Executes another attempt
Completes through a human action	Completes through successful execution

A Human Task should not be treated as a retry mechanism. Similarly, retrying task creation or completion is an application-level concern and should account for duplicate state transitions.

Human Tasks and Timeouts

Human Task waiting time is different from the execution time of a normal automated node. A workflow can legitimately remain waiting for a human decision. Therefore, applications should not assume that a pending Human Task represents a stalled workflow. The verified V1 Human Task behavior is based on an explicit waiting state and later resume. Advanced Human Task deadlines and timeout policies are not part of the verified V1 feature set.

Testing Human Tasks

Human Task workflows should test both sides of the waiting lifecycle. Important cases include:

Task creation
Waiting state
Approval
Rejection
Workflow resume
Persisted workflow state
Correct instance identification
Downstream execution after approval
Alternative path after rejection

A basic test looks like:

Start
  |
  v
Human Task
  |
  v
Waiting
  |
  v
Approve
  |
  v
Continue

The test should verify that the workflow does not execute downstream nodes while it is waiting.

Testing Rejection

Rejection should be tested separately from approval. For example:

Start
  |
  v
Human Task
  |
  +---- approved ----> Success
  |
  +---- rejected -----> Rejected Path

This verifies that the workflow graph correctly represents both outcomes.

Testing Persistence

A Human Task should also be tested across persistence boundaries. A useful V1 test pattern is:

Start
  |
  v
Human Task
  |
  v
Persist
  |
  v
Waiting
  |
  v
Complete Task
  |
  v
Resume
  |
  v
End

BindAI V1 has verified this behavior using the file-backed workflow store. The workflow instance can be persisted while waiting and resumed after the human action is submitted.

Testing API Execution

The Studio API can be tested end to end. Example flow:

POST /run
     |
     v
waiting = true
     |
     v
POST /instances/{id}/human-task
     |
     v
action = approved
     |
     v
waiting = false
     |
     v
Workflow continues

This verifies the complete API-level lifecycle rather than testing only the Human Task node in isolation.

Current BindAI V1 Scope

BindAI V1 supports Human Tasks with:

Human Task workflow nodes
Task creation during execution
Waiting workflow state
Approved outcomes
Rejected outcomes
Workflow resume
Persistent workflow instances
Studio API execution
Studio API Human Task completion
Human Task state persisted with workflow execution
Integration with Agents
Integration with Tools
Integration with Conditions
Integration with Loops
Integration with Parallel and Join
Integration with Memory-enabled workflows
Integration with Knowledge-enabled workflows
Integration with Webhook connection-backed tools

This is a functional workflow capability rather than a UI-only task model.

Deferred Features

The following Human Task capabilities are outside the verified V1 scope:

Task expiration
Automatic escalation
Automatic reassignment
Notification management
Organization-wide task inboxes
Advanced task assignment
Advanced audit administration
Human Task deadlines
Distributed task management
Advanced cancellation APIs

These should only be documented as implemented features after they exist in the runtime and are covered by tests.

API Accuracy

The verified Studio API is:

POST /api/v1/studio/projects/{project_id}/workflows/{workflow_id}/run

to start workflow execution. When the workflow reaches a Human Task, the response can contain:

waiting = true

and a Human Task object. The decision is submitted through:

POST /api/v1/studio/projects/{project_id}/workflows/{workflow_id}/instances/{instance_id}/human-task

with:

{
  "action": "approved"
}

or:

{
  "action": "rejected"
}

The runtime and persisted workflow instance then determine the continuation of the workflow. Applications should not assume additional APIs such as:

TaskStore(...)
assign(...)
complete(...)
expire(...)
escalate(...)

unless those APIs are explicitly added and verified in a future BindAI release.

Summary

Human Tasks allow BindAI workflows to pause automated execution and wait for a human decision. The verified V1 lifecycle is:

Workflow
   |
   v
Human Task
   |
   v
Waiting
   |
   v
Human Decision
   |
   +---- approved ----> Continue
   |
   +---- rejected -----> Alternative Path

The workflow state is persisted while waiting, allowing the task to be completed later and the workflow to resume. Human Tasks can be combined with Agents, Tools, Conditions, Loops, Parallel/Join, Memory, Knowledge, and connection-backed tools. The Studio API provides the verified V1 mechanism for starting a workflow and submitting a Human Task decision. BindAI V1 does not currently provide a complete task-management system with automatic expiration, escalation, reassignment, notifications, or organizational task administration.

Human Tasks provide a persistent pause point in workflow execution where an external human decision determines how the workflow continues.

​Human Tasks

​What Is a Human Task?

​Why Use Human Tasks?

​Human Task Execution

​Waiting State

​Human Task Data

​Human Task Outcomes

​Approval Workflow

​Human Tasks and Conditions

​Human Tasks and Agents

​Human Tasks and Tools

​Human Tasks and Connections

​Human Tasks and Memory

​Human Tasks and Knowledge

​Persistence

​Resume After Approval

​Studio API

​Human Task Lifecycle

​Workflow Restart and Persistence

​Example: Approval Before an External Action

​Human Tasks and Parallel Workflows

​Human Tasks Inside Loops

​Human Tasks and Errors

​Approval and Rejection Are Workflow Outcomes

​Human Task Assignment

​User Interfaces

​Long-Running Human Tasks

​Expiration and Escalation

​Auditability

​Security

​Duplicate Completion

​Human Tasks and Retries

​Human Tasks and Timeouts

​Testing Human Tasks

​Testing Rejection

​Testing Persistence

​Testing API Execution

​Current BindAI V1 Scope

​Deferred Features

​API Accuracy

​Summary