docs/en/enterprise/features/flow-hitl-management.mdx
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.
sales_rep_email)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.
| Parameter | Type | Description |
|---|---|---|
message | str | The message displayed to the human reviewer |
emit | list[str] | Valid response options (displayed as buttons in UI) |
Access HITL configuration from: Deployment → Settings → Human in the Loop Configuration
<Frame> </Frame>Toggle to enable or disable email notifications for HITL requests.
| Setting | Default | Description |
|---|---|---|
| Email Notifications | Enabled | Send emails when feedback is requested |
Set a target response time for tracking and metrics purposes.
| Setting | Description |
|---|---|
| SLA Target (minutes) | Target response time. Used for dashboard metrics and SLA tracking |
Leave empty to disable SLA tracking.
The HITL system uses an email-first architecture where responders can reply directly to notification emails.
Responders can reply with:
emit option (e.g., "approved"), it's used directlyAfter processing a reply, the responder receives a confirmation email indicating whether the feedback was successfully submitted or if an error occurred.
Route HITL requests to specific email addresses based on method patterns.
<Frame> </Frame>{
"name": "Approvals to Finance",
"match": {
"method_name": "approve_*"
},
"assign_to_email": "[email protected]",
"assign_from_input": "manager_email"
}
| Pattern | Description | Example Match |
|---|---|---|
approve_* | Wildcard (any chars) | approve_payment, approve_vendor |
review_? | Single char | review_a, review_1 |
validate_payment | Exact match | validate_payment only |
assign_from_input): If configured, pulls email from flow stateassign_to_email): Falls back to configured emailIf your flow state contains {"sales_rep_email": "[email protected]"}, configure:
{
"name": "Route to Sales Rep",
"match": {
"method_name": "review_*"
},
"assign_from_input": "sales_rep_email"
}
The request will be assigned to [email protected] automatically.
Automatically respond to HITL requests if no human responds within a timeout. This ensures flows don't hang indefinitely.
| Setting | Description |
|---|---|
| Enabled | Toggle to enable auto-response |
| Timeout (minutes) | Time to wait before auto-responding |
| Default Outcome | The response value (must match an emit option) |
The HITL review interface provides a clean, focused experience for reviewers:
Reviewers can respond via three channels:
| Method | Description |
|---|---|
| Email Reply | Reply directly to the notification email |
| Dashboard | Use the Enterprise dashboard UI |
| API/Webhook | Programmatic response via API |
Every HITL interaction is tracked with a complete timeline:
Track HITL performance with comprehensive analytics.
Enterprise-ready audit capabilities for regulatory requirements:
- AI generates responses to security questionnaires
- Security team reviews and validates accuracy via email
- Approved responses are compiled into final submission
- Full audit trail for compliance
- AI generates marketing copy or social media content
- Route to brand team email for voice/tone review
- Automatic publishing upon approval
- AI pre-processes and categorizes financial requests
- Route based on amount thresholds using dynamic assignment
- Maintain complete audit trail for financial compliance
- Flow fetches account owner email from CRM
- Store email in flow state (e.g., `account_owner_email`)
- Use `assign_from_input` to route to the right person automatically
- AI generates customer-facing content or responses
- QA team reviews via email notification
- Feedback loops improve AI performance over time
When your Flows pause for human feedback, you can configure webhooks to send request data to your own application. This enables:
You can configure multiple webhooks. Each active webhook receives all HITL events.
Your endpoint will receive HTTP POST requests for these events:
| Event Type | When Triggered |
|---|---|
new_request | A flow pauses and requests human feedback |
All webhooks receive a JSON payload with this structure:
{
"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": "[email protected]",
"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": "[email protected]"
}
To submit feedback, POST to the callback_url included in the webhook payload.
POST {callback_url}
Content-Type: application/json
{
"feedback": "Approved. Great article!",
"source": "my_custom_app"
}
Each webhook request includes these headers:
| Header | Description |
|---|---|
X-Signature | HMAC-SHA256 signature: sha256=<hex_digest> |
X-Timestamp | Unix timestamp when the request was signed |
Verify by computing:
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
Your webhook endpoint should return a 2xx status code to acknowledge receipt:
| Your Response | Our Behavior |
|---|---|
| 2xx | Webhook delivered successfully |
| 4xx/5xx | Logged as failed, no retry |
| Timeout (30s) | Logged as failed, no retry |
HITL access is controlled at the deployment level:
| Permission | Capability |
|---|---|
manage_human_feedback | Configure HITL settings, view all requests |
respond_to_human_feedback | Respond to requests, view assigned requests |
For email replies:
All HITL actions are logged:
Use Dynamic Assignment: Pull assignee emails from your flow state for flexible routing.
Configure Auto-Response: Set up a fallback for non-critical reviews to prevent flows from hanging.
Monitor Response Times: Use analytics to identify bottlenecks and optimize your review process.
Keep Review Messages Clear: Write clear, actionable messages in the @human_feedback decorator.
Test Email Flow: Send test requests to verify email delivery before going to production.