Human in the Loop Step

The Human in the Loop step pauses flow execution and requests manual approval or review from designated team members. Use it for high-stakes decisions, quality control, compliance requirements, or any situation where human judgment is required.

Agent + Human Collaboration: Let agents handle routine decisions automatically, but pause for human review when decisions are critical, uncertain, or require empathy and judgment.

How It Works

Human in the Loop pauses the flow, sends notification to reviewers, waits for their decision, then continues based on their response:

Agent: Analyzes refund request
  Output: {decision: "approve", amount: 150, reason: "..."}
↓
Human in the Loop: Manager approval
  Reviewers: [manager@company.com]
  Context: Refund request for $150
  Pause until: Manager approves/rejects
↓ (approved)
HTTP Request: Process refund

Agent: Generates customer email
  Output: {subject: "...", body: "..."}
↓
Human in the Loop: Review email content
  Reviewers: [support-lead@company.com]
  Show: Generated email
  Options: Approve, Edit, Reject
↓ (approved)
Agent: Send email

Agent: Processes large order
↓
Condition: Order > $10,000?
↓ (true)
Human in the Loop: Sales manager approval
↓ (approved)
Condition: Order > $50,000?
↓ (true)
Human in the Loop: Director approval
↓ (approved)
HTTP Request: Process order

When to Use Human in the Loop

Use When	Don’t Use When
High-stakes decisions (large refunds, deletions)	Routine, low-risk decisions
Compliance requirements (financial approvals)	High-volume operations
Low confidence from agent (< 70%)	Agent is consistently accurate
Customer complaints or escalations	Standard inquiries
Sensitive content (legal, medical, HR)	Generic content generation
Quality control on agent outputs	Agents have proven reliability
Edge cases outside normal rules	Common scenarios

Configuration

Reviewers

reviewers

array

required

Email addresses of people who can approveExamples:

["manager@company.com"]

["support-lead@company.com", "support-manager@company.com"]

// Dynamic based on data
["${customer.account_manager}", "fallback@company.com"]

Add multiple reviewers - any one can approve (OR logic, not AND)

requiredApprovals

number

default:"1"

Number of approvals required before continuingExamples:

1 - Any single reviewer can approve (most common)
2 - Two reviewers must approve
all - All reviewers must approve

Use multi-approval for: Very high-stakes decisions, compliance requirements

Request Details

title

string

required

Short description of what needs approvalExamples:

“Refund Request Approval”
“Content Review Required”
“High-Value Order Approval”
“Customer Escalation Review”

description

string

Detailed context for reviewersCan include data from previous steps:

Customer ${customer.name} has requested a refund of $${refund.amount} for order #${order.id}.

Agent recommendation: ${agent.decision}
Reason: ${agent.reason}
Customer tier: ${customer.tier}
Order date: ${order.date}

data

object

Structured data to display to reviewersExample:

{
  "customer": {
    "name": "${customer.name}",
    "email": "${customer.email}",
    "tier": "${customer.tier}",
    "lifetime_value": "${customer.ltv}"
  },
  "request": {
    "type": "refund",
    "amount": "${refund.amount}",
    "reason": "${refund.reason}"
  },
  "agent_analysis": {
    "recommendation": "${agent.decision}",
    "confidence": "${agent.confidence}",
    "reasoning": "${agent.reasoning}"
  }
}

Displayed in structured format for easy review

Response Options

approvalOptions

array

default:"[\"approve\", \"reject\"]"

Custom approval optionsDefault: Approve or RejectCustom examples:

["approve", "reject", "request_more_info"]

["approve", "approve_with_conditions", "reject"]

["low_priority", "medium_priority", "high_priority"]

allowComments

boolean

default:"true"

Let reviewers add commentsComments are included in the step output and can be used in subsequent steps.

allowEdit

boolean

default:"false"

Let reviewers edit the submitted dataUse when: Reviewers might need to modify details (e.g., adjust refund amount, edit generated content)

Timeout

timeout

number

How long to wait before auto-action (in hours)Examples:

24 - Wait 24 hours
72 - Wait 3 days
No timeout - Wait indefinitely

timeoutAction

enum

What to do when timeout is reachedOptions:

auto_approve - Automatically approve
auto_reject - Automatically reject
escalate - Send to escalation reviewers
notify - Send reminder notification

Response Structure

Human in the Loop returns the reviewer’s decision:

{
  "approved": true,
  "decision": "approve",
  "reviewer": "manager@company.com",
  "comments": "Approved - customer has good history",
  "timestamp": "2025-10-16T10:30:00Z",
  "edited_data": {
    // Any edits made by reviewer (if editing enabled)
  }
}

Accessing Response

Reference in subsequent steps:

// Check if approved
${human_review.approved}

// Get decision
${human_review.decision}

// Get reviewer comments
${human_review.comments}

// Get who approved
${human_review.reviewer}

// Use in condition
${human_review.approved} == true

Common Patterns

Confidence-Based Review

Review when agent confidence is low

Agent: Analyze request
  Output: {decision, confidence, reasoning}
↓
Condition: Confidence check
├─ If confidence >= 0.9 → Auto-execute
└─ If confidence < 0.9 → Human review
    ↓
    Condition: Approved?
    ├─ Yes → Execute
    └─ No → Reject

Use when: Agent handles most cases, humans review uncertain ones

High-Value Approval

Require approval above threshold

Agent: Process transaction
↓
Condition: Amount > $10,000?
├─ Yes → Manager approval required
│   ↓
│   Human in the Loop
│   ↓
│   Continue if approved
└─ No → Auto-approve

Use when: Financial controls, spending limits

Quality Control

Review agent-generated content before sending

Agent: Generate email/content
↓
Human in the Loop: Content review
  Show: Generated content
  Options: Approve, Edit, Reject
↓
Condition: Approved?
├─ Yes → Send content
├─ Edit → Update content, then send
└─ Reject → Notify agent owner

Use when: Customer-facing content, compliance requirements

Escalation Path

Multi-tier approval for complex decisions

Agent: Analyze situation
↓
Condition: Risk level?
├─ Low → Auto-handle
├─ Medium → Team lead approval
│   ↓
│   Human in the Loop: Team lead
│   ↓
│   Continue if approved
└─ High → Director approval
    ↓
    Human in the Loop: Director
    ↓
    Continue if approved

Use when: Risk-based escalation, org hierarchy

Compliance Review

Required approval for regulated actions

Agent: Processes sensitive data
↓
Human in the Loop: Compliance approval
  Reviewers: [compliance@company.com]
  Required: All reviewers must approve
↓
Continue only if approved

Use when: GDPR, HIPAA, financial regulations

Customer Escalation

Human takeover for complex support issues

Agent: Handles customer inquiry
↓
Condition: Agent decision?
├─ Resolved → Close ticket
└─ Escalate → Human takeover
    ↓
    Human in the Loop: Support agent
      Context: Conversation history
      Data: Customer profile, order history
    ↓
    Support agent continues conversation

Use when: Complex issues, angry customers, ambiguous situations

Timeout with Escalation

Auto-escalate if not reviewed in time

Agent: Flags for review
↓
Human in the Loop: Manager review
  Timeout: 24 hours
  Timeout Action: Escalate
↓ (if timeout)
Human in the Loop: Director review
  Timeout: 12 hours
  Timeout Action: Auto-approve
↓
Continue

Use when: Time-sensitive approvals, SLA requirements

Real-World Examples

Example 1: Refund Approval Workflow

Customer: Requests refund via chat
↓
Agent: Analyzes refund request
  Tools: Order history, return policy
  Output: {
    decision: "approve",
    confidence: 0.75,
    amount: 299.99,
    reason: "Defective product",
    policy_compliant: true
  }
↓
Condition: Confidence >= 0.9?
├─ Yes → Auto-approve refund
└─ No → Manager review
    ↓
    Human in the Loop
      Reviewers: ["support-manager@company.com"]
      Title: "Refund Approval Required"
      Description: "Customer ${customer.name} requesting $${refund.amount} refund"
      Data: {
        customer: ${customer},
        order: ${order},
        agent_recommendation: ${agent.output}
      }
      Options: ["approve", "reject", "approve_partial"]
      Timeout: 24 hours
      Timeout Action: auto_approve
    ↓
    Condition: Approved?
    ├─ Yes → Process refund
    └─ No → Send rejection email

Example 2: Marketing Content Review

Trigger: Weekly content generation
↓
Agent: Generate social media posts
  Output: 7 days of posts
↓
Human in the Loop: Marketing manager review
  Reviewers: ["marketing@company.com"]
  Title: "Weekly Social Content Review"
  Description: "Review generated social posts for next week"
  Data: {posts: ${agent.output.posts}}
  Options: ["approve_all", "edit", "regenerate"]
  Allow Edit: true
↓
Condition: Decision?
├─ Approve → Schedule posts
├─ Edit → Use edited version, schedule
└─ Regenerate → New agent generation

Example 3: High-Value Sales Approval

Form: Quote request submitted
↓
Agent: Generate pricing quote
  Output: {
    customer: {...},
    products: [...],
    subtotal: 45000,
    discount: 0.15,
    total: 38250
  }
↓
Condition: Total >= $25,000?
├─ No → Auto-send quote
└─ Yes → Sales director approval
    ↓
    Human in the Loop
      Reviewers: ["sales-director@company.com"]
      Title: "High-Value Quote Approval"
      Description: "Quote for ${agent.customer.name}: $${agent.total}"
      Data: {
        customer: ${agent.customer},
        quote_details: ${agent.output},
        margin_analysis: ${calculated_margin}
      }
      Options: ["approve", "adjust_discount", "reject"]
      Allow Edit: true
    ↓
    Condition: Approved?
    ├─ Yes → Send quote
    ├─ Adjust → Update pricing, send
    └─ Reject → Notify sales rep

Best Practices

Use Sparingly

Only require human approval when truly necessary. Over-use creates bottlenecks and reduces efficiency.

Provide Context

Give reviewers all information needed to make informed decisions. Include agent reasoning, data, and recommendations.

Set Reasonable Timeouts

Don’t let requests sit forever. Set timeouts with appropriate fallback actions.

Make It Easy

Simple approve/reject options work best. Complex choices slow decisions.

Notify Appropriately

Use email, Slack, or your team’s communication channel. Don’t rely on reviewers checking the platform.

Track and Optimize

Monitor approval rates and times. If humans always approve, consider removing the step.

Troubleshooting

Reviewers not receiving notifications

Causes:

Email address incorrect
Notifications in spam
Email service configuration issue

Solutions:

Verify email addresses
Check spam folders
Add noreply@quiva.ai to contacts
Check notification settings

Flow stuck waiting for approval

Causes:

Reviewers haven’t responded
No timeout set
Notification not received

Solutions:

Set reasonable timeouts
Add reminder notifications
Add multiple reviewers
Contact reviewers directly

Can't access approval decision

Causes:

Wrong variable path
Step not completed

Solutions:

Use ${step_name.approved} or ${step_name.decision}
Check step executed in logs
Verify step name matches

Too many approval requests

Causes:

Threshold too low
Agent confidence not high enough
Unnecessary approvals

Solutions:

Raise approval threshold
Improve agent prompts for higher confidence
Review if approvals are truly needed
Consider batch approvals for similar requests

Next Steps

Condition Step

Route based on approval decision

Agents

Configure agents that recommend decisions

Delay Step

Add time-based pauses to flows

Notifications

Configure notification channels

Get Started

Assistants

Flows

Account Management

Advanced

Human in the Loop

Human in the Loop Step

How It Works

When to Use Human in the Loop

Configuration

Reviewers

Request Details

Response Options

Timeout

Response Structure

Accessing Response

Common Patterns

Real-World Examples

Example 1: Refund Approval Workflow

Example 2: Marketing Content Review

Example 3: High-Value Sales Approval

Best Practices

Use Sparingly

Provide Context

Set Reasonable Timeouts

Make It Easy

Notify Appropriately

Track and Optimize

Troubleshooting

Next Steps

Condition Step

Agents

Delay Step

Notifications

​Human in the Loop Step

​How It Works

​When to Use Human in the Loop

​Configuration

​Reviewers

​Request Details

​Response Options

​Timeout

​Response Structure

​Accessing Response

​Common Patterns

​Real-World Examples

​Example 1: Refund Approval Workflow

​Example 2: Marketing Content Review

​Example 3: High-Value Sales Approval

​Best Practices

Use Sparingly

Provide Context

Set Reasonable Timeouts

Make It Easy

Notify Appropriately

Track and Optimize

​Troubleshooting

​Next Steps

Condition Step

Agents

Delay Step

Notifications

Human in the Loop Step

How It Works

When to Use Human in the Loop

Configuration

Reviewers

Request Details

Response Options

Timeout

Response Structure

Accessing Response

Common Patterns

Real-World Examples

Example 1: Refund Approval Workflow

Example 2: Marketing Content Review

Example 3: High-Value Sales Approval

Best Practices

Troubleshooting

Next Steps