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

# Approvals & Human-in-the-Loop

> Add human oversight to your agent workflows — require approval before sensitive actions, review tool calls, and maintain control over automated processes.

# Approvals & Human-in-the-Loop (HITL)

The **Approvals** system lets you add human oversight to your agent workflows. Require approval before sensitive actions, review tool calls before they execute, or log all agent actions for audit review.

## HITL Modes

| Mode            | Behavior                                                                  | Use Case                                                       |
| --------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `disabled`      | No human oversight. Agent runs autonomously.                              | Low-risk tasks, internal tools                                 |
| `blocking`      | Pause workflow and wait for human approval before continuing.             | Sensitive actions (payments, emails to customers)              |
| `confirm_tools` | Only pause when the agent tries to use a tool. Conversation flows freely. | Tool calls that have side effects (database writes, API calls) |
| `audit`         | Log all actions but don't block execution.                                | Compliance, quality review                                     |

## How It Works

### Blocking Mode

```
User message → Agent processes → Agent wants to send email
                                       │
                                       ▼
                              ┌─────────────────┐
                              │ APPROVAL GATE    │
                              │ Waiting for      │
                              │ human review...  │
                              └────────┬────────┘
                                       │
                          Human approves / rejects
                                       │
                          ┌────────────┴────────────┐
                          ▼                         ▼
                    Email sent              Action cancelled
                    Flow continues          Agent responds with
                                           alternative
```

### Confirm Tools Mode

In this mode, regular conversation flows without interruption. The workflow only pauses when the agent attempts a tool call:

* **Search tool called** → Approved automatically (read-only)
* **Gmail send called** → Paused for approval (has side effects)

You can configure which specific tools require confirmation.

## Setting Up Approvals

### From the Dashboard

1. Go to your agent's **Flow Editor**.
2. Select a node that should require approval.
3. In the node settings, set **HITL Mode** to your desired mode.
4. Configure approved/blocked tool lists (for `confirm_tools` mode).
5. Save and deploy.

### Via Workflow Configuration

In your flow graph, add HITL configuration to any node:

```json theme={null}
{
  "id": "agent_send_email",
  "type": "agent",
  "data": {
    "instructions": "Send the confirmation email to the customer",
    "tools": ["gmail"],
    "hitl_mode": "blocking",
    "hitl_config": {
      "timeout_minutes": 30,
      "notify_channels": ["slack", "dashboard"],
      "auto_reject_on_timeout": true
    }
  }
}
```

## Approval Workflow

### 1. Approval Request Created

When the workflow hits an approval gate, a request is created:

```json theme={null}
{
  "id": 42,
  "agent_id": 123,
  "node_id": "agent_send_email",
  "status": "pending",
  "context_summary": "Agent wants to send email to john@example.com with subject 'Order Confirmation #12345'",
  "tool_name": "gmail_send",
  "tool_args": {
    "to": "john@example.com",
    "subject": "Order Confirmation #12345",
    "body": "Your order has been confirmed..."
  },
  "priority": "medium",
  "created_at": "2026-03-06T12:00:00Z",
  "expires_at": "2026-03-06T12:30:00Z"
}
```

### 2. Human Reviews

Approvers can review pending requests from:

* **Dashboard** — The Approvals panel shows all pending requests with context
* **Slack/Email notifications** — Receive alerts when approvals are needed
* **API** — Programmatically approve/reject

### 3. Respond to Approval

```bash theme={null}
# Approve
curl -X POST https://api.thinnest.ai/approvals/42/respond \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "comment": "Looks good, proceed with sending"
  }'

# Reject
curl -X POST https://api.thinnest.ai/approvals/42/respond \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reject",
    "comment": "Wrong email address, please correct"
  }'
```

### 4. Workflow Resumes

* **Approved** → The workflow continues from where it paused.
* **Rejected** → The agent receives the rejection reason and responds to the user with an alternative.
* **Timed out** → Based on configuration, either auto-rejects or escalates.

## API Reference

### List Pending Approvals

```bash theme={null}
curl "https://api.thinnest.ai/approvals?agent_id=agent_abc123&status=pending" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

### Get Approval Details

```bash theme={null}
curl "https://api.thinnest.ai/approvals/42" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

### Approval History

```bash theme={null}
curl "https://api.thinnest.ai/approvals?agent_id=agent_abc123&status=completed" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

## Workflow Checkpoints

The system automatically creates **checkpoints** at approval gates, saving the complete workflow state. This means:

* If the approval takes minutes or hours, the workflow resumes exactly where it left off
* No data is lost during the waiting period
* The user's conversation context is preserved

## Voice Agent Approvals

Approvals work with voice agents too. When a voice agent hits an approval gate during a phone call:

1. The agent tells the caller: "I need to verify this with my team. One moment please."
2. A hold message or music plays while waiting.
3. The approver responds via the dashboard or Slack.
4. The agent continues the conversation with the result.

For time-sensitive voice calls, set short timeouts (2-5 minutes) and configure fallback behavior.

## Audit Mode

In `audit` mode, all actions are logged without blocking:

```json theme={null}
{
  "audit_log": [
    {
      "timestamp": "2026-03-06T12:00:01Z",
      "node_id": "agent_1",
      "action": "tool_call",
      "tool": "gmail_send",
      "args": {"to": "john@example.com", "subject": "..."},
      "result": "success"
    },
    {
      "timestamp": "2026-03-06T12:00:03Z",
      "node_id": "agent_1",
      "action": "tool_call",
      "tool": "google_calendar_create",
      "args": {"title": "Meeting", "start": "..."},
      "result": "success"
    }
  ]
}
```

Review audit logs in the **Approvals** tab to identify patterns, catch errors, and improve your agent.

## Best Practices

* **Use `confirm_tools` for production** — Less intrusive than `blocking` while still catching side effects.
* **Set reasonable timeouts** — 30 minutes for async workflows, 2-5 minutes for voice calls.
* **Configure notifications** — Ensure approvers are notified immediately via Slack or email.
* **Start with `audit` mode** — Monitor your agent's behavior before enabling blocking.
* **Document approval criteria** — Train approvers on what to look for and when to approve/reject.
* **Review audit logs regularly** — Even in non-blocking mode, audits reveal quality issues.