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

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

Via Workflow Configuration

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

{
  "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:

{
  "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

# 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

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

Get Approval Details

curl "https://api.thinnest.ai/approvals/42" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"

Approval History

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:

The agent tells the caller: “I need to verify this with my team. One moment please.”
A hold message or music plays while waiting.
The approver responds via the dashboard or Slack.
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:

{
  "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.

Introduction

Getting Started

Voice Agents

Agent Capabilities

Channels

Quality & Oversight

Platform

Approvals & Human-in-the-Loop

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

HITL Modes

How It Works

Blocking Mode

Confirm Tools Mode

Setting Up Approvals

From the Dashboard

Via Workflow Configuration

Approval Workflow

1. Approval Request Created

2. Human Reviews

3. Respond to Approval

4. Workflow Resumes

API Reference

List Pending Approvals

Get Approval Details

Approval History

Workflow Checkpoints

Voice Agent Approvals

Audit Mode

Best Practices

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

​HITL Modes

​How It Works

​Blocking Mode

​Confirm Tools Mode

​Setting Up Approvals

​From the Dashboard

​Via Workflow Configuration

​Approval Workflow

​1. Approval Request Created

​2. Human Reviews

​3. Respond to Approval

​4. Workflow Resumes

​API Reference

​List Pending Approvals

​Get Approval Details

​Approval History

​Workflow Checkpoints

​Voice Agent Approvals

​Audit Mode

​Best Practices

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

HITL Modes

How It Works

Blocking Mode

Confirm Tools Mode

Setting Up Approvals

From the Dashboard

Via Workflow Configuration

Approval Workflow

1. Approval Request Created

2. Human Reviews

3. Respond to Approval

4. Workflow Resumes

API Reference

List Pending Approvals

Get Approval Details

Approval History

Workflow Checkpoints

Voice Agent Approvals

Audit Mode

Best Practices