CrewAI Human in the Loop: Implementing Approval Handoffs
Source: mortalapps.com- CrewAI human-in-the-loop (HITL) patterns allow explicit pauses in multi-agent executions to solicit human validation before executing high-risk actions.
- It solves the problem of non-deterministic agent outputs causing unintended side effects in production environments, such as unauthorized database writes or unreviewed client communications.
- In production, this shifts agents from fully autonomous black boxes to governed, human-supervised workflows, ensuring compliance and safety.
- This tutorial demonstrates how to configure CrewAI tasks with human approval flags, intercept the execution loop, and resume state with human feedback.
Why This Matters
Implementing a robust "crewai human in the loop" architecture is critical when transitioning multi-agent systems from sandboxed environments to production-grade enterprise deployments. While fully autonomous agents excel at processing unstructured data and generating drafts, their non-deterministic nature presents severe risks when interacting with external APIs, financial ledgers, or customer-facing communication channels. Without a structured approval mechanism, a single hallucination or tool-use error can result in unauthorized transactions, data corruption, or brand damage.
Historically, multi-agent frameworks treated execution as an all-or-nothing process. CrewAI addresses this by providing native human-in-the-loop hooks, allowing developers to designate specific tasks as requiring human verification. This approach is invented to balance the efficiency of autonomous agent execution with the safety of human oversight.
If ignored in production, enterprises face catastrophic failures such as infinite loops executing paid API calls, prompt injection attacks hijacking agent goals, and compliance violations under frameworks like the EU AI Act or DORA. By inserting explicit pause-and-wait nodes, engineers establish a hard boundary where execution halts, state is preserved, and a human operator can review, edit, or reject the agent's proposed action. This pattern is preferred over post-hoc auditing because it prevents the damage before it occurs, rather than merely logging it after the fact. Use this pattern for any high-risk tool execution, financial transaction, or external system write.
Core Concepts
Core Concepts of CrewAI Human-in-the-Loop Systems
- Human-in-the-Loop (HITL): The design pattern of inserting a human checkpoint into an automated process to validate, correct, or reject agent decisions.
- Task-Level Human Approval (
human_input=True): CrewAI's built-in configuration parameter that forces a task to pause and prompt for console input before finalizing its output. - Interrupt Trigger Conditions: Specific criteria (e.g., transaction value thresholds, semantic classification of risk) that programmatically decide whether a task requires human intervention.
- State Resumption: The mechanism of capturing the agent's execution state, pausing the thread, and resuming execution with injected human feedback or modifications.
- Custom Tool Interceptors: Overriding tool execution methods to inject approval gates at the tool level rather than the task level.
- Console vs. API-Driven HITL: Console-driven relies on standard input (
sys.stdin), whereas production systems require API-driven HITL where state is persisted to a database and resumed via a webhook or REST endpoint.
| Feature | Console-Based HITL | API-Driven HITL |
|---|---|---|
| Trigger | Native human_input=True |
Custom Tool/Task Wrapper |
| Execution Thread | Blocks synchronously | Yields/Terminates and Resumes |
| State Storage | In-memory | Database (PostgreSQL/Redis) |
| UI Channel | Terminal CLI | Web UI, Slack, Teams |
How It Works
The Human Approval Lifecycle in CrewAI
An execution flow with human approval follows a strict state transition model. The process ensures that agents do not proceed to downstream tasks until the human gate has been cleared.
Phase 1: Task Initialization and Flag Detection
When the Crew starts execution, it parses the task dependency graph. If a task is configured with human_input=True, the execution engine wraps the final output generation phase in an interrupt handler.
Phase 2: Agent Execution and Draft Generation
The assigned agent executes its role autonomously. It utilizes its defined tools, reasoning loops, and planning capabilities to generate a proposed draft or action. At this stage, no external side effects (like database writes or email dispatches) should be executed if they are protected by the approval gate.
Phase 3: The Interrupt Gate
Instead of passing the output directly to the next task, CrewAI halts execution.
- In local CLI mode: The framework prints the agent's proposed output to the terminal and blocks on a synchronous
input()call. - In production API mode: A custom tool or task interceptor serializes the current execution context, writes it to a persistent database, dispatches an alert (e.g., via Webhook or Slack), and terminates the active worker thread to free up system resources.
Phase 4: Human Evaluation and Feedback Injection
The human reviewer inspects the proposed output. They have three options:
- Approve: The human confirms the output is correct. The execution engine marks the task as complete and passes the output to the next task.
- Feedback: The human rejects the output and provides natural language feedback (e.g., "Correct the spelling of the client's name"). The execution engine injects this feedback back into the agent's context.
- Terminate: The human aborts the run entirely, triggering rollback procedures.
Phase 5: State Resumption or Iteration
If feedback was provided, the agent receives the human's input as a high-priority prompt. It re-runs its reasoning loop to correct the draft and returns to Phase 3. This loop continues until the human issues an explicit approval.
Architecture
The architecture of a production-grade CrewAI human approval system decouples the execution engine from the human interface using an asynchronous, event-driven pattern.
The system consists of five primary components: the Crew Execution Engine, the State Store (PostgreSQL or Redis), the Event Broker (RabbitMQ or AWS EventBridge), the Approval Web Portal, and the Notification Gateway (Slack or Email).
Execution begins when a client triggers a multi-agent run. The Crew Execution Engine processes tasks sequentially. When it encounters a task requiring human approval, the engine does not block. Instead, it serializes the current agent state, memory, and task context, and writes this payload to the State Store with a status of 'PENDING_APPROVAL'.
Next, the engine publishes a 'TaskApprovalRequested' event to the Event Broker and gracefully exits, freeing up container resources. The Event Broker routes this event to the Notification Gateway, which alerts the human reviewer, and to the Approval Web Portal, which renders the agent's draft.
Once the human submits their decision (Approve, Reject with Feedback, or Terminate) via the Approval Web Portal, the portal sends a POST request to the Callback API. The Callback API updates the task status in the State Store. If approved, it spins up a new worker instance of the Crew Execution Engine, loads the serialized state from the State Store, and resumes execution from the next task. If rejected, it resumes the agent with the feedback injected as a new prompt.
Native Console-Based HITL vs. Production API-Driven HITL
CrewAI's native human-in-the-loop implementation is activated by setting human_input=True on a Task. While this is highly effective for local debugging, it is fundamentally unsuitable for production environments. The native implementation uses Python's synchronous input() function, which blocks the execution thread. In a web application context (such as a FastAPI or Django backend), a blocked thread prevents the server from handling other concurrent requests, leading to rapid resource exhaustion and timeouts.
To build a production-ready system, you must implement an asynchronous pause-and-resume pattern. This requires subclassing CrewAI's task execution or implementing custom tools that yield execution. Instead of blocking, the agent must save its state to a database and terminate its active process. A separate callback endpoint must be exposed to receive the human's decision and trigger a new execution worker that resumes from the saved state.
Implementing Custom Tool-Level Approvals
Often, pausing an entire task is too coarse-grained. You may want the agent to perform research, compile data, and draft a report autonomously, but pause only when it attempts to execute a high-risk tool, such as execute_wire_transfer or delete_user_account.
This is achieved by implementing an approval gate directly inside the tool's _run method. The tool checks if the proposed action meets specific risk thresholds (e.g., transaction amount > $1,000). If the threshold is crossed, the tool writes the request to an approval queue database, marks the transaction as pending, and returns a message to the agent: "Action pending human approval. Do not proceed with downstream tasks until approval is confirmed.". The agent then yields or enters a polling state.
State Persistence and Resumption Mechanics
Because CrewAI does not natively support distributed state checkpointers like LangGraph, developers must implement custom serialization. To serialize a CrewAI run, you must capture:
- The Task Context: The inputs, outputs, and current position in the sequential or hierarchical process.
- Agent Memory: The short-term memory buffer and episodic memory vectors associated with the current run.
- The LLM Conversation History: The raw prompt-response history of the agent.
This data should be serialized to JSON and stored in a relational database like PostgreSQL. When resuming, you instantiate a new Crew and Agent instance, pre-populate the agent's memory and task context from the database, and trigger the execution.
Designing the Human Feedback Loop
When a human rejects an agent's output, the feedback must be structured so the agent can act on it without losing its original goal. A common anti-pattern is simply appending the feedback to the prompt, which can confuse the agent's system instructions.
Instead, format the feedback as a system correction:
[SYSTEM CORRECTION]
Your previous output was rejected by the human supervisor.
Reason/Feedback: <Human Feedback Here>
Please revise your output to address this feedback. Do not repeat the mistakes of the previous draft.This explicit formatting forces the agent's reasoning model (e.g., via ReAct loops) to treat the feedback as a constraint violation that must be resolved in the next iteration.
Code Example
import os
from crewai import Agent, Task, Crew, Process
# Ensure API keys are retrieved from environment variables
if not os.environ.get("OPENAI_API_KEY"):
raise ValueError("OPENAI_API_KEY environment variable is not set")
# Define an agent with a specific role and goal
writer_agent = Agent(
role="Senior Content Writer",
goal="Draft high-quality technical articles on software architecture.",
backstory="You are an expert technical writer who explains complex systems simply.",
verbose=True
)
# Define a task that requires human approval before completion
draft_article_task = Task(
description="Write a 300-word introduction to Event-Driven Microservices.",
expected_output="A clean, technically accurate markdown introduction.",
agent=writer_agent,
# Setting human_input=True activates the native terminal approval gate
human_input=True
)
# Assemble the crew
crew = Crew(
agents=[writer_agent],
tasks=[draft_article_task],
process=Process.sequential,
verbose=True
)
if __name__ == "__main__":
print("Starting Crew execution. The process will pause for human input at the end of the task.")
result = crew.kickoff()
print("
Final Approved Output:
", result)The agent executes, generates the draft, and then pauses, printing: 'Please review the output and provide your feedback or press Enter to approve:' If you provide feedback, the agent refines the text. If you press Enter, execution completes.
import os
import uuid
import logging
from typing import Dict, Any
from pydantic import BaseModel, Field
from crewai.tools import BaseTool
from crewai import Agent, Task, Crew
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
# Mock Database to simulate persistent state store
mock_db: Dict[str, Dict[str, Any]] = {}
class TransactionApprovalPayload(BaseModel):
transaction_id: str = Field(..., description="Unique ID of the transaction")
amount: float = Field(..., description="The dollar amount of the transaction")
recipient: str = Field(..., description="The recipient of the funds")
status: str = Field("PENDING", description="Approval status")
class SecurePaymentTool(BaseTool):
name: str = "Secure Payment Tool"
description: str = "Executes financial transactions. High-value transfers require human approval."
def _run(self, amount: float, recipient: str) -> str:
# Define a risk threshold for human intervention
risk_threshold = 1000.0
transaction_id = str(uuid.uuid4())
if amount >= risk_threshold:
# Persist the state to the database instead of blocking the thread
mock_db[transaction_id] = {
"transaction_id": transaction_id,
"amount": amount,
"recipient": recipient,
"status": "PENDING_HUMAN_APPROVAL"
}
logging.warning(f"High-value transaction {transaction_id} flagged for approval.")
return (
f"TRANSACTION_PAUSED: The transfer of ${amount} to {recipient} requires human approval. "
f"Transaction ID: {transaction_id}. Do not attempt to re-run this tool. "
f"Wait for the system administrator to approve this transaction."
)
# Low-value transactions proceed autonomously
return f"TRANSACTION_SUCCESS: Successfully transferred ${amount} to {recipient}."
# Define the agent equipped with the secure payment tool
finance_agent = Agent(
role="Financial Operations Agent",
goal="Process corporate payments securely and efficiently.",
backstory="You manage corporate disbursements. You strictly adhere to security thresholds.",
tools=[SecurePaymentTool()],
verbose=True
)
# Define the task
payment_task = Task(
description="Process a payment of $5000.00 to Vendor_A for server hosting fees.",
expected_output="Confirmation message of the payment status.",
agent=finance_agent
)
crew = Crew(
agents=[finance_agent],
tasks=[payment_task],
verbose=True
)
if __name__ == "__main__":
# Run the crew
result = crew.kickoff()
print("
Crew Execution Result:
", result)
print("
Database State for Verification:
", mock_db)The agent attempts to run the tool with $5000.00. The tool intercepts the call, writes the transaction to the mock database with status 'PENDING_HUMAN_APPROVAL', and returns the pause message. The crew completes its run without blocking the thread, leaving the transaction safely pending in the database.