> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getrilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Human-in-the-Loop

> Add human review and approval steps to your workflows with HITL blocks.

Human-in-the-Loop (HITL) blocks allow you to pause workflow execution for human review, approval, or modification of data before continuing. Perfect for content moderation, data validation, or any process that needs human oversight.

## Overview

HITL blocks:

* **Pause execution**: Workflow stops until human review is complete
* **Interactive forms**: Dynamic UI forms generated from data
* **Edit and approve**: Users can modify data before approval
* **Resume automatically**: Workflow continues after review submission

<Info>
  HITL blocks automatically generate dynamic review forms based on your data structure.
</Info>

## When to Use HITL

HITL blocks are ideal for:

* **Content Review**: Approve AI-generated content before publishing
* **Data Validation**: Review scraped data before adding to CRM
* **Quality Gates**: Human approval checkpoint before critical actions
* **Data Enrichment**: Review and correct AI-enriched data
* **Compliance**: Ensure content meets compliance requirements

## Creating HITL Blocks

### Via Natural Language

Simply describe what needs review:

```
"After scraping leads, add a human review step to approve them before adding to the CRM"
```

The AI agent automatically creates a HITL block with the appropriate configuration based on your description.

## Display Formats

HITL blocks support multiple display layouts:

<CardGroup cols={2}>
  <Card title="Table" icon="table">
    Best for quick scanning and comparing items. Shows data in rows and columns.
  </Card>

  <Card title="Card Grid" icon="grid">
    Good for items with images or detailed content. Displays items as cards in a grid.
  </Card>

  <Card title="List" icon="list">
    For sequential review of complex items. Shows items in a vertical list.
  </Card>

  <Card title="Carousel" icon="arrow-right">
    For horizontal scrolling through items. Useful for image-heavy content.
  </Card>
</CardGroup>

### Configuring Display Format

Specify display format in your instructions:

```
"Display as cards with 2 columns showing image and title"
```

## Review Process

### 1. Data Generation

Previous block generates data:

```json theme={null}
{
  "items": [
    {
      "id": "1",
      "name": "John Doe",
      "email": "john@example.com",
      "company": "Acme Corp"
    }
  ]
}
```

### 2. Form Generation

Rilo automatically generates a review form:

* Analyzes data structure
* Creates appropriate input fields
* Adds approve/reject buttons
* Configures layout based on display\_format

### 3. User Review

User sees the review form:

* **Editable fields**: Can modify data before approval
* **Action buttons**: Approve, reject, or skip items
* **Draft saving**: Save progress and return later

### 4. Submission

After review:

* Modified data is captured
* Approval status is recorded
* Workflow resumes automatically

### 5. Output

HITL block outputs reviewed data:

```json theme={null}
{
  "summary": {
    "total_items": 10,
    "approved": 7,
    "rejected": 3
  },
  "items": [
    {
      "id": "1",
      "original_data": {
        "name": "John",
        "email": "john@example.com"
      },
      "final_data": {
        "name": "John Doe",
        "email": "john@example.com",
        "status": "approved"
      }
    }
  ]
}
```

## Block Execution States

HITL blocks have specific execution states:

| Status                | Description                          |
| --------------------- | ------------------------------------ |
| `pending`             | Block not yet started                |
| `running`             | Block is executing                   |
| `form_generating`     | Generating the review form           |
| `awaiting_input`      | Waiting for human review             |
| `processing_response` | Processing submitted response        |
| `completed`           | Review completed, workflow continues |
| `failed`              | Block encountered an error           |

<Info>
  The `awaiting_input` state is unique to HITL blocks. The workflow pauses here until the user completes the review.
</Info>

## Reminder System

HITL blocks support email reminders for pending reviews:

### Configuration

When creating a HITL block, you can configure reminders by describing your preferences. The system will automatically set up email and in-app notifications based on your needs.

### Reminder Intervals

* `[1, 24, 72]`: Reminders at 1 hour, 24 hours, 72 hours
* `[24]`: Single reminder at 24 hours (default)
* `[]`: No reminders

### Notification Modes

| Mode       | Description                      |
| ---------- | -------------------------------- |
| `in_app`   | Notification in the app UI       |
| `email`    | Email to workflow owner          |
| `slack`    | Slack message (if configured)    |
| `whatsapp` | WhatsApp message (if configured) |

<Info>
  See [Email Reminder](/features/email-reminder) for more details on the reminder system.
</Info>

## Example Workflows

### Example 1: Content Review

**Workflow:**

1. Generate quotes (Code block)
2. Review quotes (HITL block)
3. Post approved quotes (Code block)

**HITL Configuration:**
Simply describe what needs review: "Review generated quotes. Edit if needed, then approve for posting. Display as cards with quote and author."

### Example 2: Lead Validation

**Workflow:**

1. Scrape leads (Code block)
2. Review leads (HITL block)
3. Add to CRM (Code block)

**HITL Configuration:**
Simply describe what needs review: "Review scraped leads. Verify email addresses and company names. Display as table with name, email, company columns. Make email editable."

## Best Practices

<AccordionGroup>
  <Accordion title="Clear Review Instructions">
    Write clear instructions about what to review. Users should understand what they're approving.
  </Accordion>

  <Accordion title="Appropriate Display Format">
    Choose the display format that best fits your data. Tables for structured data, cards for rich content.
  </Accordion>

  <Accordion title="Enable Reminders">
    Enable reminders for time-sensitive reviews. Don't let reviews sit indefinitely.
  </Accordion>

  <Accordion title="Limit Review Items">
    Keep review batches manageable. Too many items can be overwhelming.
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  HITL blocks can only depend on exactly one code block. They cannot depend on other HITL blocks or start blocks.
</Warning>

* **Single dependency**: Must depend on exactly one code block
* **No chaining**: Cannot chain HITL blocks directly (use code blocks between)
* **Data structure**: Input data should be structured (list of items)

### Workaround for Multiple Reviews

To create multiple review stages:

```
code-1 → hitl-1 → code-2 (processes approved items) → hitl-2
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Form not generating">
    * Check that previous block output is structured correctly
    * Verify data format matches expected structure
    * Ensure HITL block depends on a code block
  </Accordion>

  <Accordion title="Review not submitting">
    * Check that all required fields are filled
    * Verify action buttons are configured correctly
    * Review browser console for errors
  </Accordion>

  <Accordion title="Reminders not sending">
    * Verify reminder configuration is correct
    * Check email settings in account
    * Ensure reminder intervals are set
  </Accordion>
</AccordionGroup>

## Related Features

* [Email Reminder](/features/email-reminder) - Configure reminders for HITL blocks
* [Configs](/features/configs) - Configure HITL block settings
* [Graph Mode](/features/graph-mode) - Visualize HITL blocks in workflows

***

<Note>
  HITL blocks are a powerful way to add human oversight to automated workflows. Use them when you need quality control or compliance checks.
</Note>