Human-in-the-Loop (HITL)

Human-in-the-Loop (HITL) is LangCrew’s high-level human oversight component built on top of LangGraph’s native interrupt system. It provides an easy-to-use interface for adding human approval workflows to AI agent executions.

What is HITL?

HITL is a high-level abstraction that wraps LangGraph’s interrupt mechanisms to provide strategic control points where humans can:

• Approve or deny tool executions before they run
• Modify parameters before tool execution
• Review and edit tool results after execution
• Implement safety policies for production environments
• Multi-language support with Chinese and English UI elements

Core Architecture

HITL provides a high-level wrapper around LangGraph’s interrupt system with enhanced approval workflows:

from langcrew.hitl import HITLConfig

# Basic configuration
hitl_config = HITLConfig(
    interrupt_before_tools=["file_write", "database_query"],
    interrupt_after_tools=["data_analysis"]
)

Execution Modes

LangCrew supports two execution modes that determine which interrupts are effective:

Mode	When Used	Effective Interrupts	Ignored Interrupts
Task Mode	When you provide both agents and tasks	interrupt_before_tasks interrupt_after_tasks	interrupt_before_agents interrupt_after_agents
Agent Mode	When you provide only agents (no tasks)	interrupt_before_agents interrupt_after_agents	interrupt_before_tasks interrupt_after_tasks

Important: Tool-level and node-level interrupts work in both modes.

Six Interrupt Types

1. Task-Level Interrupts

interrupt_before_tasks

Effective in: Task Mode only

Pause before specific tasks execute to review or modify task inputs:

from langcrew import Crew, HITLConfig

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    hitl=HITLConfig(
        interrupt_before_tasks=["research_task"]  # Review before research starts
    )
)

interrupt_after_tasks

Effective in: Task Mode only

Pause after specific tasks complete to review or modify outputs:

hitl=HITLConfig(
    interrupt_after_tasks=["research_task"]  # Review research results
)

2. Agent-Level Interrupts

interrupt_before_agents

Effective in: Agent Mode only

Pause before specific agents execute:

from langcrew import Crew, HITLConfig

crew = Crew(
    agents=[coordinator, specialist],  # No tasks - Agent Mode
    hitl=HITLConfig(
        interrupt_before_agents=["specialist"]  # Approve before specialist runs
    )
)

interrupt_after_agents

Effective in: Agent Mode only

Pause after specific agents complete their work:

hitl=HITLConfig(
    interrupt_after_agents=["coordinator"]  # Review coordinator's decisions
)

3. Tool-Level Interrupts

interrupt_before_tools

Effective in: Both modes

Pause before specific tools execute (most common for sensitive operations):

hitl=HITLConfig(
    interrupt_before_tools=["send_email", "make_payment", "delete_file"]
)

interrupt_after_tools

Effective in: Both modes (with session limitations)

Pause after specific tools complete to review results:

hitl=HITLConfig(
    interrupt_after_tools=["data_analysis"]  # Review analysis results
)

Session Limitation

interrupt_after_tools only works within a single execution session and cannot resume from the interrupt point after workflow restarts.

4. Node-Level Interrupts

interrupt_before_nodes / interrupt_after_nodes

Effective in: Both modes

Pause at specific LangGraph nodes for workflow-level control:

hitl=HITLConfig(
    interrupt_before_nodes=["decision_node"],
    interrupt_after_nodes=["processing_node"]
)

Key Components

HITLConfig

Unified configuration for all interrupt and approval settings.

Configuration Parameters

Parameter	Type	Description	Default
interrupt_before_tasks	List[str]	Tasks to interrupt before (Task Mode only)	[]
interrupt_after_tasks	List[str]	Tasks to interrupt after (Task Mode only)	[]
interrupt_before_agents	List[str]	Agents to interrupt before (Agent Mode only)	[]
interrupt_after_agents	List[str]	Agents to interrupt after (Agent Mode only)	[]
interrupt_before_tools	List[str]	Tools requiring approval before execution	[]
interrupt_after_tools	List[str]	Tools requiring review after execution	[]
interrupt_before_nodes	List[str]	Nodes to interrupt before	[]
interrupt_after_nodes	List[str]	Nodes to interrupt after	[]

Tool-Level Interrupts

Control tool execution with human approval workflows.

# Interrupt before/after specific tools
hitl_config = HITLConfig(
    interrupt_before_tools=["file_write", "web_search"],
    interrupt_after_tools=["data_analysis"]
)

• Before interrupts: Parameter approval and modification
• After interrupts: Result review and editing

Session-Level Limitation

interrupt_after_tools only works within a single execution session. The interrupt occurs during tool node execution, before the next checkpoint is saved. After workflow restarts, the system cannot resume from the interrupt point and must restart from the last checkpoint, potentially causing duplicate tool executions.

For tools that need post-execution review across restarts, consider:

• Using interrupt_before_tools for critical operations
• Implementing re-entrant tools that can handle multiple review cycles
• Using node-level interrupts for workflow-level control points

Node-Level Interrupts

Integration with LangGraph’s native interrupt system for workflow control.

# Interrupt before/after specific workflow nodes
hitl_config = HITLConfig(
    interrupt_before_nodes=["decision_node"],
    interrupt_after_nodes=["validation_node"]
)

Node-level interrupts provide granular control over workflow execution, allowing human intervention at specific decision points or validation steps in your agent workflows.

UserInputTool

Dynamic user interaction tool for agent-initiated input requests.

from langcrew_tools.hitl import UserInputTool

# Agent can request user input during execution
user_input_tool = UserInputTool()
agent = Agent(tools=[user_input_tool, ...])

Enables agents to dynamically collect information from users during workflow execution.

Integration with langcrew

HITL integrates seamlessly with all langcrew components:

• Agents: Add approval workflows to agent tools
• Tasks: Tasks inherit HITL settings from their assigned agents
• Crews: Apply unified HITL policies across teams

# HITL is configured at the Agent level
agent = Agent(
    role="Data Analyst",
    tools=[web_search, file_write],
    hitl=HITLConfig(interrupt_before_tools=["file_write"])
)

# Tasks automatically inherit HITL settings from their agent
task = Task(
    agent=agent,
    description="Analyze data and save report"
)

# Crew can also apply HITL policies to all agents
crew = Crew(
    agents=[agent],
    tasks=[task],
    hitl=HITLConfig(interrupt_before_tools=["web_search"])
)

Interrupt Types

Before Interrupt

# User approves/modifies parameters before execution
hitl_config = HITLConfig(
    interrupt_before_tools=["web_search", "file_write"]
)

After Interrupt

# User reviews/edits results after execution
hitl_config = HITLConfig(
    interrupt_after_tools=["data_analysis", "report_generator"]
)

When to Use HITL

• Production environments requiring human oversight
• Sensitive operations like file modifications or API calls
• Quality assurance workflows needing human validation
• Compliance scenarios requiring audit trails

Multi-language Support

HITL provides built-in multi-language interface support:

# Automatic language detection
# Currently supported languages:
# English: "approve", "deny", "yes", "no"
# Chinese: "批准", "拒绝", "同意", "不同意"
# More languages can be added in the future