Human-in-the-Loop

The Human-in-Loop node (HiL) pauses workflow execution at a critical decision point and waits for a human to review and approve or reject before continuing. This is the foundation of supervised AI automation — letting agents do the heavy lifting while keeping humans in control of consequential decisions.

---

When to Use Human-in-Loop

Use Case	Why HiL Matters
Code deployment	Agent writes and tests code; human reviews before pushing to production
Content publishing	AI drafts content; editor approves before it goes live
Financial actions	Agent prepares a transaction; human confirms before execution
Email campaigns	AI writes emails; marketing manager approves before sending
Security response	Agent identifies a threat and proposes action; security engineer approves
Research reports	Agent compiles research; analyst validates findings before distribution

Any time an AI action is consequential, irreversible, or high-stakes, a Human-in-Loop node is the right choice.

---

How It Works

Key behaviors:

• Execution fully pauses — no other nodes run while waiting
• The workflow can wait indefinitely (or until timeout)
• The reviewer can be anyone with project access (admin, editor, or reader)
• The decision is stored in the execution record permanently

---

HiL Node Configuration

In the canvas inspector:

Field	Type	Description
Title	string	Short description of what needs approval: "Review AI-generated code before deployment"
Description	string	Instructions for the reviewer: "Please verify the code is correct and safe to deploy to production."
Display Value	string	Content to show for review — supports expressions: {{writer.output}}
Notification Email	string	Email to notify when the HiL is triggered (optional, can be left empty)
Timeout Hours	int	Hours before auto-rejecting. 0 = no timeout (wait forever)

Display Value Examples

Show the AI-generated content directly:

{{writer.output}}

Show with context:

Agent analysis result:

{{analyzer.output}}

---
Original trigger input: {{trigger.output}}

Show structured data (if agent outputs JSON):

Security findings from {{analyzer.output}}

Recommended action: Please verify these findings and approve remediation.

---

Review Interface

In Executions Page

1. Go to Executions in the sidebar.
2. Paused executions show with a 🟡 yellow indicator ("Awaiting Approval").
3. Click the execution to open the detail view.
4. Scroll to the Human-in-Loop node.
5. The review panel shows:
   • Title and Description
   • Display Value (the AI content to review)
   • Approve button (green)
   • Reject button (red)
   • Comment field (optional)
6. Click Approve or Reject.

In Bridge

Bridge shows pending approvals in the sidebar as notification badges. You can review and approve/reject directly from Bridge:

1. Bridge shows a notification: "You have 1 pending approval"
2. Click the notification to open the review panel inline in Bridge
3. Review the content and click Approve or Reject

---

After the Decision

On Approve

• The HiL node's output becomes "approved" (or "approved: {reviewer_comment}")
• Execution continues from the Approved output handle of the HiL node
• Downstream nodes in the approve path run normally

On Reject

• The HiL node's output becomes "rejected: {comment}" (the comment explains why)
• Execution continues from the Rejected output handle of the HiL node
• If no rejected path is connected, the workflow ends

Connecting the Paths

The HiL node has two output handles:

• Approved handle (green) → connects to the "what to do when approved" nodes
• Rejected handle (red) → connects to "what to do when rejected" nodes (optional)

---

Common Patterns

Pattern 1: Simple Gate

Pattern 2: Rejection with Feedback Loop

When rejected, include the reviewer's comment in a re-run:

The reviser agent uses {{hil.output}} which contains "rejected: The tone is too formal, please make it more conversational" — giving specific feedback to improve the revision.

Pattern 3: Multi-Step Approval

For high-stakes decisions requiring multiple approvers:

Step 1: Manager approval HiL → Approved
Step 2: Legal review HiL → Approved  
Step 3: Execute

Pattern 4: Timeout-Based Auto-Reject

For time-sensitive workflows where delayed approval means the action is no longer relevant:

• Set Timeout Hours = 4 (auto-reject after 4 hours)
• Connect the Rejected path to a notification agent that explains the workflow timed out

---

Using the Reviewer Comment

The HiL node's output includes the reviewer's comment (if provided):

Action	{{hil.output}} value
Approved (no comment)	"approved"
Approved with comment	"approved: Looks good, but watch the third paragraph"
Rejected with comment	"rejected: The code has a SQL injection vulnerability in line 42"

This is extremely powerful for feedback loops:

# Reviser agent input:
The previous version was rejected. Here is the reviewer's feedback:
{{review_hil.output}}

Original content:
{{writer.output}}

Please revise the content based on the feedback.

---

Notification Setup

To receive email notifications when a HiL node triggers:

1. In the HiL node inspector, enter your email in Notification Email.
2. When the workflow reaches this node, TARX sends an email with:
   • Workflow name
   • HiL title
   • Direct link to the review interface
   • Preview of the display value (first 200 chars)

Use project-wide notification emails

Enter a team distribution list (e.g., approvals@yourcompany.com) rather than individual emails. This ensures the approval request goes to whoever is available, not a specific person who might be OOO.

---

Via API

Approvals can also be triggered via the API (for integration with external systems):

POST /api/v1/executions/{execution_id}/approve
Authorization: Bearer sk-tarx-YOUR_KEY
X-Project-ID: {project_id}
Content-Type: application/json

{
  "decision": "approved",
  "comment": "Reviewed and approved by automated compliance check"
}

Response:

{
  "status": "approved",
  "execution_id": "exec_abc123",
  "resumed": true
}

This lets external systems (your compliance tool, ticketing system, etc.) inject approvals.

---

Timeout Behavior

Timeout Setting	Behavior
0 (no timeout)	Waits forever until manually approved or rejected
> 0 hours	After the timeout, auto-rejects with message "timeout: Approval expired after {N} hours"

When a HiL node is reached, a timeout job is queued in the TARX backend. If the timeout fires before a human decision, the rejected path is taken automatically.

---

HiL in Large Teams

Who Can Approve?

Any project member with any role (admin, editor, reader) can approve/reject Human-in-Loop steps. Approval is not role-restricted.

Audit Trail

Every approval/rejection is recorded in the execution detail:

• Who approved/rejected (user email and UID)
• When (timestamp)
• Their comment
• The full display_value that was shown

This provides a complete audit trail for compliance-sensitive workflows.

Multiple Reviewers

The first person to respond wins. If multiple team members see the notification, the first approval/rejection takes effect. Subsequent attempts return a "This decision has already been made" message.