DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Decorators / @human_feedback
Decorator crewai.flow.human_feedback

@human_feedback: Reference Guide

By DevShelfHub

Pauses a Flow method to await human input via a provider (CLI, webhook, Slack, etc.).

See the CrewAI API reference index, CrewAI introduction, hooks and events tutorial, and core concepts for surrounding context.

What is @human_feedback?

@human_feedback turns an ordinary Flow method into a suspension point. When execution reaches it, CrewAI hands control to a HumanFeedbackProvider implementation that knows how to collect a decision — interactive CLI for local work, signed webhooks for staging, Slack or email bridges for distributed teams, or a bespoke UI backed by your API. The pending context surfaces prompts, attachments, and routing metadata so providers can render rich reviewer experiences without re-querying upstream services.

The decorator is how you implement governance without abandoning Flow ergonomics: models can draft freely, but publishing, refunds, or customer-visible sends wait for explicit human signals. Combine the pattern with @router downstream so approve versus reject paths fan out cleanly, and always persist Flow state when waits might exceed process lifetimes so reviewers can answer asynchronously.

Operational maturity means treating providers like production endpoints: authenticate callbacks, deduplicate delivery IDs, log decisions with actor attribution, and enforce SLAs so stuck approvals do not hold workers indefinitely. Testing should cover timeout, retry, and malicious replay attempts the same way you would for payment webhooks.

When to Use

Approval gates, content review, escalation points.

Use Cases

  • • Content approval
  • • Sensitive-action gates
  • • Quality review

Key Features

  • ✓ Suspends execution
  • ✓ Pluggable providers
  • ✓ State preserved while pending

When NOT to Use

High-throughput automated paths.

Notes

Provider security

Webhook endpoints must verify signatures and reject stale nonces. Treat approval URLs like privileged actions — rate limit, authenticate, and persist decisions before acknowledging delivery.

Resource pinning

Paused flows may retain memory, connections, or GPU leases. Set watchdog timers, escalation queues, and explicit cancel paths so one forgotten approval does not starve a worker pool.

Resume idempotency

Humans double-click approve in UIs. Make downstream side effects idempotent with business keys so duplicate provider callbacks cannot publish twice or charge twice.

Auditability

Capture reviewer identity, timestamp, rationale, and diff snapshots alongside the returned value. Compliance teams expect immutable audit trails, not only the final model output.

Import

python 
from crewai.flow.human_feedback import human_feedback

How to Apply

python 
@human_feedback
def approve(self, draft):
    return draft

What It Enables

  • ✓ Human gates
  • ✓ Webhook approvals
  • ✓ Slack/email reviews

Code Examples

Approval

python 
@human_feedback
def review(self, draft):
    return draft

Structured payload for reviewers

python 
@human_feedback
def legal_review(self, contract: str) -> str:
    """Pause until counsel records structured feedback on the contract text."""
    return contract

Router after human feedback

python 
from crewai.flow.flow import router
from crewai.flow.human_feedback import human_feedback

@human_feedback
def review(self, draft: str) -> str:
    return draft

@router(review)
def decide(self):
    return 'publish' if self.state.approved else 'revise'

Integration Patterns

With @persist for durability
With WebhookProvider for async approvals

Common Mistakes

❌ Using @human_feedback without @persist on a long-running flow

✅ Pair with @persist so state survives the wait.

Related: Task class reference, Agent class reference, and the first Crew tutorial.

@human_feedback FAQ

What is @human_feedback in CrewAI?

Pauses a Flow method to await human input via a provider (CLI, webhook, Slack, etc.). @human_feedback turns an ordinary Flow method into a suspension point. When execution reaches it, CrewAI hands control to a HumanFeedbackProvider implementation that knows how to collect a decision — interactive CLI for local work, signed webhooks for staging, Slack or email bridges for distributed teams, or a bespoke UI backed by your API. The pending context surfaces prompts, attachments, and routing metadata so providers can render rich reviewer experiences without re-quer…

Which module defines the CrewAI decorator @human_feedback?

DevShelfHub maps @human_feedback to Python module crewai.flow.human_feedback. Pin your installed crewai version and match imports to the import snippet on this page.

When should I use @human_feedback?

Approval gates, content review, escalation points.

When should I avoid @human_feedback?

High-throughput automated paths.

How do I apply @human_feedback in Python?

@human_feedback def approve(self, draft): return draft

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.