Skip to main content

​
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

ModeBehaviorUse Case
disabledNo human oversight. Agent runs autonomously.Low-risk tasks, internal tools
blockingPause workflow and wait for human approval before continuing.Sensitive actions (payments, emails to customers)
confirm_toolsOnly pause when the agent tries to use a tool. Conversation flows freely.Tool calls that have side effects (database writes, API calls)
auditLog 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: 
{
  "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:
  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: 
{
  "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.