Human-in-the-Loop Workflows - Pinkfish - AI Agents & Workflows for Getting Work Done

What is Human-in-the-Loop?

Human-in-the-Loop (HITL) workflows combine the efficiency of automation with human judgment and oversight. Pinkfish enables you to seamlessly integrate human decision points, approvals, and interventions into your automated processes through dynamic web applications, notifications, and data-driven workflow resumption. Pinkfish supports HITL two ways:

The Approval node — a built-in control-flow node for agentic workflows that pauses the run, shows a hosted approval form, and branches on the approver’s response. This is the fastest way to add a single approval gate.
The pattern-based approach — manually generate an HTML form, store it in the filestore, write the decision to a datastore, and resume via a datastore trigger. Use this when you need a custom review UI or want to collect more than a yes/no decision.

Start with the Approval node; drop down to the pattern when you outgrow it.

Approval Node (Agentic Editor)

The Approval node is the fastest way to add a “wait for a human” gate to an agentic workflow. It handles the approval form, the secure link, the notification hand-off, the timeout, and the branching so you do not have to build any of it yourself.

When to use it

You need a simple approve / deny decision before continuing the run.
You want to send the approver a link over Slack, Teams, or email and let them act without logging in.
The decision should expire automatically (for example, if nobody responds in 24 hours, deny by default).

Adding the node

Open an agentic workflow in the agentic editor.
Click Add Node on the canvas and expand Flow Control.
Pick Approval (Human-in-the-Loop).

The node drops onto the canvas with three output handles:

Approval node on the agentic editor canvas with three labeled output handles — notify (blue), approved (green), and denied (red) — wired next to the Manual Trigger.

Handle	Color	When it fires
`notify`	Blue (top)	Fires once when the run reaches the node — use it to send the approver the approval link.
`approved`	Green	Fires if the approver clicks Approve on the form.
`denied`	Rose / Red	Fires if the approver clicks Deny or the link expires without a response.

Wire notify to a messaging node (Slack, Teams, email, SMS) that includes the {{approvalLink}} variable from the node’s output. Wire approved and denied to the next steps you want for each outcome.

Configuration

Open the node’s settings panel to configure:

Approval node settings panel in the agentic editor showing Name, Preamble textarea, Link expiration (minutes), and the Allow public access toggle.

Field	Default	Purpose
Preamble	empty	Text shown to the approver on the form. Up to 5,000 characters. Supports Markdown.
Expiration (minutes)	60	How long the approval link stays valid. Minimum 1 minute, maximum 43,200 (30 days). After expiration the `denied` handle fires.
Allow public access	off	When on, anyone with the link can respond without signing in. When off, only authenticated org members can approve.
Name	`Approval`	Label that appears on the canvas. Does not affect behavior.

What the approver sees

The approver clicks the link from the notification and lands on a hosted form at /approve/{token} served by Pinkfish. The form shows the preamble text (rendered as Markdown) with Approve and Deny buttons. Submitting either button closes the loop and the workflow resumes immediately on the corresponding handle. If Allow public access is off, the approver is prompted to sign in before the form renders.

Timeout behavior

If nobody submits the form before the expiration, Pinkfish marks the approval as expired and fires the denied handle. The expired link can no longer be used — a stale approver who follows the link later sees an expired-approval page.

Legacy note: the pattern-based approach

If you need more than a yes/no decision, a custom form layout, or multi-stage review, the pattern-based approach still works. It’s described below and relies on generating HTML forms into the filestore, writing responses to a datastore, and resuming with a datastore trigger.

How Human-in-the-Loop Works in Pinkfish

The HITL Pattern

Workflow Pause: Automation reaches a decision point or encounters an exception
Human Notification: System sends email, SMS, or other notification to relevant stakeholders
Dynamic Interface: Workflow generates an ephemeral HTML application hosted at a secure file storage link
Human Input: Stakeholder reviews context and provides input through the custom interface
Data Storage: Human decision is saved to the datastore
Workflow Resumption: Data change triggers workflow continuation with human input available

Key Components

Datastore: Stores human decisions and approval data
File Storage: Hosts ephemeral HTML applications
Data Collection Triggers: Automatically resume workflows when human input is received
Email/SMS Notifications: Alert humans when input is needed
HTML Generation: Create custom approval interfaces dynamically

Implementation Patterns

1. Approval Checkpoints

Add approval gates at critical workflow stages:

Step 1: Process initial data
Step 2: Generate approval request
  - Create HTML approval form
  - Save form to file storage with expiring link
  - Store pending approval record in datastore
  - Send email notification with approval link
  - PAUSE workflow execution

Trigger: On datastore change (approval record updated)
Step 3: Resume with approval decision
  - Check approval status from datastore
  - Continue or halt based on human decision

2. Exception Handling

Handle workflow failures with human intervention:

Step 1: Attempt automated process
Step 2: On failure, create intervention request
  - Generate diagnostic HTML interface
  - Include error details and suggested actions
  - Store intervention record in datastore
  - Notify operations team via email/SMS
  - PAUSE for human resolution

Trigger: On datastore change (intervention resolved)
Step 3: Resume with human guidance
  - Retrieve resolution instructions
  - Apply human-provided fixes
  - Continue automated process

3. Quality Review Gates

Add human quality checks for critical outputs:

Step 1: Generate automated report/output
Step 2: Create review interface
  - Display output in HTML review form
  - Provide approval/rejection options
  - Include feedback collection fields
  - Store review record in datastore
  - Send notification to reviewers

Trigger: On datastore change (review completed)
Step 3: Process review decision
  - If approved: finalize and distribute
  - If rejected: revise based on feedback

Creating Dynamic HTML Applications

Ephemeral Web Interfaces

Workflows can generate custom HTML applications for human interaction:

Generate HTML approval form:
- Include workflow context and data
- Create form fields for human input
- Add styling for professional appearance
- Include security tokens for validation
- Save as HTML file to file storage
- Generate secure, expiring access link

Example HTML Generation

<!DOCTYPE html>
<html>
  <head>
    <title>Workflow Approval Required</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        max-width: 600px;
        margin: 50px auto;
      }
      .approval-form {
        background: #f9f9f9;
        padding: 20px;
        border-radius: 8px;
      }
      .btn {
        padding: 10px 20px;
        margin: 10px;
        border: none;
        border-radius: 4px;
        cursor: pointer;
      }
      .approve {
        background: #28a745;
        color: white;
      }
      .reject {
        background: #dc3545;
        color: white;
      }
    </style>
  </head>
  <body>
    <div class="approval-form">
      <h2>Purchase Order Approval</h2>
      <p><strong>Vendor:</strong> {{vendor_name}}</p>
      <p><strong>Amount:</strong> ${{amount}}</p>
      <p><strong>Description:</strong> {{description}}</p>

      <form action="javascript:submitApproval()">
        <label>Comments:</label>
        <textarea name="comments" rows="3" cols="50"></textarea><br />

        <button type="button" class="btn approve" onclick="approve()">
          Approve
        </button>
        <button type="button" class="btn reject" onclick="reject()">
          Reject
        </button>
      </form>
    </div>

    <script>
      function approve() {
        submitDecision("approved");
      }
      function reject() {
        submitDecision("rejected");
      }

      function submitDecision(decision) {
        // Update datastore record via API call
        // This triggers workflow resumption
      }
    </script>
  </body>
</html>

Notification Strategies

Multi-Channel Notifications

Alert stakeholders through multiple channels:

Email Notifications: Detailed context with approval links
SMS Alerts: Urgent notifications for time-sensitive approvals
Slack Messages: Team notifications with workflow context
Microsoft Teams: Enterprise collaboration notifications

Escalation Patterns

Implement approval escalation workflows:

Initial Approval Request:
- Send to primary approver
- Set 24-hour timeout in datastore

Escalation Trigger (if no response):
- Check approval status after timeout
- Send escalation notification to manager
- Update approval record with escalation flag

Final Escalation:
- Auto-approve after extended timeout, or
- Route to emergency approval process

Advanced HITL Patterns

Collaborative Decision Making

Enable multiple stakeholders to provide input:

Multi-Stakeholder Approval:
- Generate approval requests for multiple people
- Track individual responses in datastore
- Resume workflow when all approvals received
- Handle partial approvals and conflicts

Conditional Human Intervention

Add smart intervention triggers:

Risk-Based Approval:
- Analyze transaction risk score
- If high risk: require human approval
- If low risk: auto-approve
- If medium risk: require manager approval

Audit Trail Integration

Maintain complete audit trails:

Approval Audit Trail:
- Log all human decisions with timestamps
- Record approver identity and comments
- Store approval artifacts (forms, emails)
- Generate compliance reports

Security and Compliance

Secure Access

Expiring Links: HTML applications use time-limited access URLs
Authentication: Integrate with organization’s identity systems
Audit Logging: Complete trail of human interactions
Data Encryption: Sensitive approval data encrypted in datastore

Compliance Features

Role-Based Approvals: Route to appropriate stakeholders based on rules
Approval Hierarchies: Multi-level approval workflows
Regulatory Compliance: SOX, GDPR, and other regulatory requirement support
Evidence Collection: Maintain approval artifacts for auditing

Best Practices

Design Principles

Clear Context: Provide complete information for informed decisions
Simple Interfaces: Make approval forms easy to understand and use
Mobile-Friendly: Ensure HTML applications work on mobile devices
Timeout Handling: Always include escalation and timeout mechanisms

User Experience

Professional Appearance: Use consistent styling and branding
Progress Indicators: Show workflow status and next steps
Help Documentation: Include guidance for approvers
Confirmation Messages: Provide clear feedback after decisions

Operational Excellence

Monitor Approval Times: Track and optimize approval processes
Handle Exceptions: Plan for approver unavailability
Test Regularly: Validate approval workflows in staging environments
Document Processes: Maintain clear approval workflow documentation

Integration with Orchestration

Human-in-the-Loop workflows integrate seamlessly with Pinkfish’s orchestration capabilities:

Queue Management: Pause and resume workflows efficiently
Monitoring: Track approval status and bottlenecks
Triggers: Automatic workflow resumption on human input
State Management: Persistent approval state across workflow executions

Ready to add human oversight to your automations? Start with our Workflow Creation Guide or explore Trigger Configuration. Questions? Join our community on Discord

​What is Human-in-the-Loop?

​Approval Node (Agentic Editor)

​When to use it

​Adding the node

​Configuration

​What the approver sees

​Timeout behavior

​Legacy note: the pattern-based approach

​How Human-in-the-Loop Works in Pinkfish

​The HITL Pattern

​Key Components

​Implementation Patterns

​1. Approval Checkpoints

​2. Exception Handling

​3. Quality Review Gates

​Creating Dynamic HTML Applications

​Ephemeral Web Interfaces

​Example HTML Generation

​Notification Strategies

​Multi-Channel Notifications

​Escalation Patterns

​Advanced HITL Patterns

​Collaborative Decision Making

​Conditional Human Intervention

​Audit Trail Integration

​Security and Compliance

​Secure Access

​Compliance Features

​Best Practices

​Design Principles

​User Experience

​Operational Excellence

​Integration with Orchestration