Flow HITL Management ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.crewai.com/llms.txt Use this file to discover all available pages before exploring further.

Enterprise-grade human review for Flows with email-first notifications, routing rules, and auto-response capabilities

Flow HITL Management features require the @human_feedback decorator, available in CrewAI version 1.8.0 or higher. These features apply specifically to Flows, not Crews.

CrewAI Enterprise provides a comprehensive Human-in-the-Loop (HITL) management system for Flows that transforms AI workflows into collaborative human-AI processes. The platform uses an email-first architecture that enables anyone with an email address to respond to review requests—no platform account required.

Overview#

<span class=“card-start” data-card-raw=“title=“Email-First Design” icon=“envelope”"> Responders can reply directly to notification emails to provide feedback

<span class=“card-start” data-card-raw=“title=“Flexible Routing” icon=“route”"> Route requests to specific emails based on method patterns or flow state

<span class=“card-start” data-card-raw=“title=“Auto-Response” icon=“clock”"> Configure automatic fallback responses when no human replies in time

Key Benefits#

• Simple mental model: Email addresses are universal; no need to manage platform users or roles
• External responders: Anyone with an email can respond, even non-platform users
• Dynamic assignment: Pull assignee email directly from flow state (e.g., sales_rep_email)
• Reduced configuration: Fewer settings to configure, faster time to value
• Email as primary channel: Most users prefer responding via email over logging into a dashboard

Setting Up Human Review Points in Flows#

Configure human review checkpoints within your Flows using the @human_feedback decorator. When execution reaches a review point, the system pauses, notifies the assignee via email, and waits for a response.

from crewai.flow.flow import Flow, start, listen, or_
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult

class ContentApprovalFlow(Flow):
    @start()
    def generate_content(self):
        return "Generated marketing copy for Q1 campaign..."

    @human_feedback(
        message="Please review this content for brand compliance:",
        emit=["approved", "rejected", "needs_revision"],
    )
    @listen(or_("generate_content", "needs_revision"))
    def review_content(self):
        return "Marketing copy for review..."

    @listen("approved")
    def publish_content(self, result: HumanFeedbackResult):
        print(f"Publishing approved content. Reviewer notes: {result.feedback}")

    @listen("rejected")
    def archive_content(self, result: HumanFeedbackResult):
        print(f"Content rejected. Reason: {result.feedback}")

For complete implementation details, see the Human Feedback in Flows guide.

Decorator Parameters#

Platform Configuration#

Access HITL configuration from: Deployment → Settings → Human in the Loop Configuration

Email Notifications#

Toggle to enable or disable email notifications for HITL requests.

When disabled, responders must use the dashboard UI or you must configure webhooks for custom notification systems.

SLA Target#

Set a target response time for tracking and metrics purposes.

Leave empty to disable SLA tracking.

Email Notifications & Responses#

The HITL system uses an email-first architecture where responders can reply directly to notification emails.

How Email Responses Work#

When a HITL request is created, an email is sent to the assigned responder with the review content and context.

The email includes a special reply-to address with a signed token for authentication.

The responder simply replies to the email with their feedback—no login required.

The platform receives the reply, verifies the signed token, and matches the sender email.

The feedback is recorded and the flow continues with the human’s input.

Response Format#

Responders can reply with:

• Emit option: If the reply matches an emit option (e.g., “approved”), it’s used directly
• Free-form text: Any text response is passed to the flow as feedback
• Plain text: The first line of the reply body is used as feedback

Confirmation Emails#

After processing a reply, the responder receives a confirmation email indicating whether the feedback was successfully submitted or if an error occurred.

Email Token Security#

• Tokens are cryptographically signed for security
• Tokens expire after 7 days
• Sender email must match the token’s authorized email
• Confirmation/error emails are sent after processing

Routing Rules#

Route HITL requests to specific email addresses based on method patterns.

Rule Structure#

{
  "name": "Approvals to Finance",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "finance@company.com",
  "assign_from_input": "manager_email"
}

Matching Patterns#

Assignment Priority#

1. Dynamic assignment (assign_from_input): If configured, pulls email from flow state
2. Static email (assign_to_email): Falls back to configured email
3. Deployment creator: If no rule matches, the deployment creator’s email is used

Dynamic Assignment Example#

If your flow state contains {"sales_rep_email": "alice@company.com"}, configure:

{
  "name": "Route to Sales Rep",
  "match": {
    "method_name": "review_*"
  },
  "assign_from_input": "sales_rep_email"
}

The request will be assigned to alice@company.com automatically.

Use Case: Pull the assignee from your CRM, database, or previous flow step to dynamically route reviews to the right person.

Auto-Response#

Automatically respond to HITL requests if no human responds within a timeout. This ensures flows don’t hang indefinitely.

Configuration#

Use Cases#

• SLA compliance: Ensure flows don’t hang indefinitely
• Default approval: Auto-approve low-risk requests after timeout
• Graceful degradation: Continue with a safe default when reviewers are unavailable

Use auto-response carefully. Only enable it for non-critical reviews where a default response is acceptable.

Review Process#

Dashboard Interface#

The HITL review interface provides a clean, focused experience for reviewers:

• Markdown Rendering: Rich formatting for review content with syntax highlighting

• Context Panel: View flow state, execution history, and related information

• Feedback Input: Provide detailed feedback and comments with your decision

• Quick Actions: One-click emit option buttons with optional comments

  

Response Methods#

Reviewers can respond via three channels:

History & Audit Trail#

Every HITL interaction is tracked with a complete timeline:

• Decision history (approve/reject/revise)
• Reviewer identity and timestamp
• Feedback and comments provided
• Response method (email/dashboard/API)
• Response time metrics

Analytics & Monitoring#

Track HITL performance with comprehensive analytics.

Performance Dashboard#

<span class=“card-start” data-card-raw=“title=“Response Times” icon=“stopwatch”"> Monitor average and median response times by reviewer or flow.

<span class=“card-start” data-card-raw=“title=“Volume Trends” icon=“chart-bar”"> Analyze review volume patterns to optimize team capacity.

<span class=“card-start” data-card-raw=“title=“Decision Distribution” icon=“chart-pie”"> View approval/rejection rates across different review types.

<span class=“card-start” data-card-raw=“title=“SLA Tracking” icon=“chart-line”"> Track percentage of reviews completed within SLA targets.

Audit & Compliance#

Enterprise-ready audit capabilities for regulatory requirements:

• Complete decision history with timestamps
• Reviewer identity verification
• Immutable audit logs
• Export capabilities for compliance reporting

Common Use Cases#

{
  "event": "new_request",
  "request": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_id": "flow_abc123",
    "method_name": "review_article",
    "message": "Please review this article for publication.",
    "emit_options": ["approved", "rejected", "request_changes"],
    "state": {
      "article_id": 12345,
      "author": "john@example.com",
      "category": "technology"
    },
    "metadata": {},
    "created_at": "2026-01-14T12:00:00Z"
  },
  "deployment": {
    "id": 456,
    "name": "Content Review Flow",
    "organization_id": 789
  },
  "callback_url": "https://api.crewai.com/...",
  "assigned_to_email": "reviewer@company.com"
}

POST {callback_url}
Content-Type: application/json

{
  "feedback": "Approved. Great article!",
  "source": "my_custom_app"
}

import hmac
import hashlib

expected = hmac.new(
    signing_secret.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected, signature):
    # Valid signature