Back to series
· 14 min read

Human-in-the-loop: Human-Machine Collaboration Mechanism


1. What Is Human-in-the-loop

Human-in-the-loop, abbreviated HITL, is a design pattern that integrates human judgment into the execution process of automated systems.

Traditional automation systems usually execute tasks according to predefined rules, with humans mainly responsible for starting tasks, reviewing results, and handling exceptions.

Agents, by contrast, possess autonomous reasoning, tool-calling, and dynamic decision-making capabilities. They can not only understand user intent, but may also call external APIs, modify business data, send messages, execute code, and even trigger real business operations.

This raises an important question:

Should an Agent have fully autonomous execution authority?

The answer is usually no.

Models may misread intent, reason incorrectly, pass wrong tool parameters, and misjudge results. For high-risk operations, relying solely on the model's own judgment is not reliable.

The core idea of HITL is: let the Agent handle automated execution, and let humans provide judgment, authorization, correction, and oversight at the necessary points.

1.1 Basic Components of HITL

A typical human-machine collaboration system contains the following roles:

Component Responsibility
Human Provides judgment, approval, feedback, and correction
Agent Understands the task, reasons and decides, calls tools
Tool Performs the concrete operation
Control Layer Determines whether human involvement is needed
State Manager Stores task and human-interaction state
Checkpointer Saves checkpoints, enabling pause and resume
Approval Service Manages approval requests and approval results

Among these, the Control Layer is a critical control point.

It is responsible for determining whether the current operation requires human participation, rather than sending every operation to humans for approval.

1.2 Basic Flow of Human-Machine Collaboration

flowchart TD
    A["User submits task"] --> B["Agent understands task"]
    B --> C["Model reasoning and decision-making"]
    C --> D{"Is human intervention needed?"}
    D -->|"No"| E["Execute operation automatically"]
    D -->|"Yes"| F["Create human approval request"]
    F --> G["Pause Agent execution"]
    G --> H["Human review"]
    H --> I{"Approval result"}
    I -->|"Approved"| J["Resume Agent execution"]
    I -->|"Rejected"| K["Terminate or adjust task"]
    I -->|"Modified"| L["Receive human feedback"]
    L --> M["Update Agent state"]
    M --> J
    E --> N["Verify execution result"]
    J --> N
    N --> O["Task complete"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style E fill:#EAF3EC,stroke:#83A995,color:#315D49
    style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style G fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#EAF3EC,stroke:#83A995,color:#315D49
    style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style L fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style M fill:#EAF3EC,stroke:#83A995,color:#315D49
    style N fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style O fill:#E5F0E9,stroke:#83A995,color:#315D49

This flow illustrates the basic HITL pattern:

  • Ordinary operations are completed automatically by the Agent.
  • High-risk operations go to human approval.
  • The task is paused during human approval.
  • Human feedback is written into the state.
  • Execution resumes after approval.
  • The final result still needs to be verified.

2. Why Agents Need Human-Machine Collaboration

The stronger an Agent's autonomous capabilities, the more clearly its behavioral boundaries must be defined.

In real business settings, models cannot guarantee that every reasoning step is correct, nor do they inherently understand all of an enterprise's permission rules and business constraints.

HITL mainly addresses the following problems.

2.1 Reduce the Risk of Model Decisions

Large models may produce the following problems:

  • Misunderstanding user intent.
  • Generating incorrect tool parameters.
  • Making excessive inferences from incomplete information.
  • Ignoring business constraints.
  • Choosing an inappropriate tool.
  • Incorrectly judging that a task has been completed.

For example, a user asks the Agent to clean up temporary files on a server.

If the Agent mistakes business files for temporary files, important data may be lost.

By having a human confirm critical deletion operations, the risk of erroneous actions can be reduced.

2.2 Controlling high-risk tool calls

Not all tool calls carry the same risk.

For example:

Tool operation Reference risk level Is human approval recommended?
Query public web pages Low Usually not required
Query internal data Medium Depends on data sensitivity
Generate analysis reports Low Usually not required
Modify ordinary business records Medium Depends on business rules
Delete important data High Approval recommended
Initiate payments High Approval recommended
Publish public content High Depends on the scope of impact
Modify system permissions High Approval recommended

Risk levels are only a reference; the final decision should be made jointly based on business rules, user permissions, and the scope of impact of the operation.

2.3 Supplementing business information the model cannot grasp

Some decisions require real-time business context, and that information may not exist in the model's context.

For example:

  • Whether the current customer is a key customer.
  • Whether a certain contract has already been confirmed offline.
  • Whether the current operation complies with departmental approval policies.
  • Whether a certain business matter involves a special exception.
  • Whether a certain user holds final authorization.

Humans can supply this information, which the model cannot reliably obtain.

2.4 Improving result quality

HITL is not only about preventing errors; it can also proactively improve the quality of the Agent's output.

For example, in a content generation task:

  1. The Agent generates a first draft of the article.
  2. A human checks the facts and the wording.
  3. The human points out the parts that need revision.
  4. The Agent regenerates based on the feedback.
  5. The human confirms the final version.

Human feedback can become input for the Agent's next round of execution.

2.5 Meeting compliance and audit requirements

In scenarios such as finance, healthcare, government affairs, and enterprise management, certain operations must be confirmed by personnel with the corresponding authority.

For example:

  • Fund transfers.
  • Approval of important contracts.
  • Export of sensitive data.
  • Permission changes.
  • Major business decisions.

HITL can retain the approver, approval time, approval comments, and execution records, providing a basis for subsequent audits.


III. Three collaboration modes of Human-in-the-loop

Depending on when humans participate and what their responsibilities are, HITL can be divided into three common modes.

3.1 Human-in-the-loop: human participation during execution

In this mode, the Agent actively pauses during task execution and waits for human feedback or approval.

For example:

  • The Agent waits for human confirmation after generating an email.
  • The Agent waits for authorization before preparing to execute a payment.
  • The Agent requests supplementary information from the user when it finds the task information insufficient.
  • The Agent waits for human revision suggestions after generating a plan.

Typical characteristics:

  • Humans participate in the execution process.
  • Human feedback can influence subsequent decisions.
  • The Agent can continue running after the feedback.

3.2 Human-on-the-loop: human supervision of the execution process

Human-on-the-loop emphasizes that humans do not need to participate in every decision, but instead continuously supervise the Agent's operation process.

The Agent can autonomously execute most tasks, while humans view the status through a monitoring interface and intervene when anomalies or risks are detected.

For example:

  • Humans monitor the execution status of multiple Agents.
  • The system automatically handles ordinary tickets.
  • Complex tickets automatically enter the human queue.
  • Humans can pause or terminate tasks at any time.

This mode is suitable for large-scale automation systems.

3.3 Human-out-of-the-loop: humans do not participate in daily execution

Human-out-of-the-loop means humans do not directly participate in the specific execution process, and the system runs autonomously according to authorized policies.

For example:

  • Automatically classifying emails.
  • Automatically organizing documents.
  • Automatically generating internal summaries.
  • Automatically performing low-risk data processing.

This mode does not mean the system requires no human management at all.

Humans are still responsible for:

  • Setting execution boundaries.
  • Configuring permissions.
  • Formulating risk rules.
  • Monitoring system quality.
  • Handling exceptional events.

3.4 Comparison of the three modes

Dimension Human-in-the-loop Human-on-the-loop Human-out-of-the-loop
Timing of human involvement During execution Supervision during execution Outside routine execution
Frequency of human intervention Relatively high Medium-low Relatively low
Agent autonomy level Medium Relatively high High
Primary objective Approval and correction Supervision and intervention Automated execution
Applicable scenarios High-risk operations Multi-task operations Low-risk repetitive tasks

Actual systems usually do not choose one of the three; they switch dynamically based on task risk.


IV. Trigger Mechanisms for Human Intervention

HITL systems need to solve a core problem:

When should humans participate?

If every step requires human confirmation, the Agent loses its automation value.

If no human confirmation is required at all, uncontrollable risks may arise.

Therefore, clear trigger mechanisms for human intervention need to be established.

4.1 Triggering based on risk level

Whether approval is required can be determined based on the risk level of tool operations.

Risk level Example Handling strategy
Low Query public information Automatic execution
Medium Modify ordinary business data Rule validation or sample review
High Delete data, publish content Human approval
Critical Payments, permission changes Mandatory authorization and multiple checks

Risk assessment can consider:

  • Whether the operation is reversible.
  • Whether funds are involved.
  • Whether sensitive data is involved.
  • Number of affected users.
  • Scope of operation permissions.
  • Potential losses.
  • Whether legal and compliance requirements exist.

4.2 Triggering based on confidence

When the model is not sufficiently certain about task understanding or result judgment, it can request human participation.

For example:

def should_request_human(confidence):
    if confidence < 0.60:
        return True

    return False

But note:

Model self-reported confidence may not be calibrated and cannot be used alone as a basis for safety decisions.

A more reliable approach is to combine:

  • Model structured evaluation results.
  • Rule validation results.
  • Data integrity.
  • Tool execution feedback.
  • Task risk level.
  • Historical error rate.

For high-risk operations such as payments, deletions, and permission changes, even if model confidence is high, mandatory approval rules should not be bypassed.

4.3 Triggering based on task complexity

Some tasks are inherently highly complex.

For example:

  • Formulate complex business plans.
  • Generate legal-related documents.
  • Modify large codebases.
  • Analyze multiple conflicting data sources.
  • Handle ambiguous user requests.

The system can set human review checkpoints based on task type and execution status.

4.4 Triggering based on anomalies

During Agent operation, the following may be encountered:

  • Continuous multiple tool call failures.
  • The same error repeating.
  • Conflicting results from multiple data sources.
  • Execution costs exceeding expectations.
  • No progress for a long time.
  • The model cannot determine the next action.

These situations can trigger human intervention.

4.5 Human intervention decision process

flowchart TD
    A["Agent prepares to execute operation"] --> B["Collect operation context"]
    B --> C["Calculate operation risk"]
    C --> D["Check business rules"]
    D --> E["Evaluate data integrity and anomalies"]
    E --> F{"Are auto-execution conditions met?"}
    F -->|"Yes"| G["Auto-execute"]
    F -->|"No"| H["Determine human intervention type"]
    H --> I{"Intervention method"}
    I -->|"Approval"| J["Create approval request"]
    I -->|"Supplement information"| K["Request information from user"]
    I -->|"Exception handling"| L["Enter manual processing queue"]
    I -->|"Force prohibit"| M["Reject execution"]
    J --> N["Wait for human response"]
    K --> N
    L --> N
    N --> O{"Human processing result"}
    O -->|"Allow"| P["Update task status"]
    O -->|"Reject"| M
    P --> Q["Continue Agent execution"]
    G --> R["Record execution result"]
    Q --> R

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style F fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style G fill:#E5F0E9,stroke:#83A995,color:#315D49
    style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style M fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style N fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style O fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style P fill:#EAF3EC,stroke:#83A995,color:#315D49
    style Q fill:#E5F0E9,stroke:#83A995,color:#315D49
    style R fill:#DCEFE5,stroke:#4F8B70,color:#24563F

V. Designing the Manual Approval Mechanism

Manual approval is the most common implementation of HITL.

Before executing an operation, the Agent submits the operation content, the reason for execution, and risk information to the approval system, then waits for an authorized person to make a decision.

5.1 Data Structure of an Approval Request

A complete approval request usually needs to include:

Field Description
approval_id Approval request ID
task_id Owning task
tool_call_id Corresponding tool call
requester Request initiator
approver Designated approver or approval role
action Operation pending approval
arguments Operation arguments
risk_level Risk level
reason Reason for the operation submitted by the Agent
status Approval status
created_at Creation time
expires_at Approval expiration time

Example:

{
  "approval_id": "approval_1001",
  "task_id": "task_1001",
  "tool_call_id": "call_003",
  "action": "delete_file",
  "arguments": {
    "file_path": "/data/archive/old_report.csv"
  },
  "risk_level": "high",
  "reason": "该文件被判断为过期临时文件",
  "status": "pending",
  "created_at": "2026-11-20T10:00:00Z",
  "expires_at": "2026-11-20T11:00:00Z"
}

Note: The reason provided by the Agent is supplementary approval information and should not be treated as proven fact. The approval interface should display real file information, scope of impact, and verifiable data as much as possible.

5.2 Approval State Machine

An approval cannot have only two states: approved and rejected.

In real business scenarios, approval withdrawal, timeout, resubmission, and permission exceptions also need to be considered.

Status Meaning
Pending Waiting for approval
Approved Approved
Rejected Rejected
Expired Expired
Cancelled Cancelled
Revision Required Requires revision and resubmission

Approval state transitions should be strictly controlled.

For example, an expired approval cannot directly become Approved, and a rejected approval should not be resubmitted for execution.

5.3 Approval Process

flowchart TD
    A["Agent creates approval request"] --> B["Save approval record"]
    B --> C["Notify approver"]
    C --> D["Approver views operation details"]
    D --> E{"Approval decision"}
    E -->|"Approve"| F["Verify approval permission"]
    E -->|"Reject"| G["Record rejection reason"]
    E -->|"Request revision"| H["Return revision comments"]
    E -->|"Timeout"| I["Mark approval as expired"]
    F --> J{"Are permissions and status valid?"}
    J -->|"Valid"| K["Mark as Approved"]
    J -->|"Invalid"| L["Reject approval operation"]
    K --> M["Allow corresponding operation to be executed"]
    G --> N["Notify Agent"]
    H --> O["Update operation parameters"]
    O --> P["Initiate approval again"]
    I --> N
    L --> N

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style G fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style K fill:#E5F0E9,stroke:#83A995,color:#315D49
    style L fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style N fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style O fill:#EAF3EC,stroke:#83A995,color:#315D49
    style P fill:#E0F0FE,stroke:#93BCE8,color:#1E4976

5.4 Approval Does Not Equal Permanent Authorization

This is a very important security principle.

Suppose the Agent submits an approval request to delete a file, and the approver agrees to delete file A.

This does not mean the Agent can subsequently:

  • Delete file B.
  • Delete the entire directory.
  • Modify the deletion parameters.
  • Use the same approval result to perform other operations.
  • Continue execution after the approval expires.

Approval must be bound to an explicit scope of operations.

It is recommended to bind at least:

  • Task ID.
  • Tool call ID.
  • Tool name.
  • Normalized operation parameters.
  • Parameter digest or hash.
  • Approval validity period.
  • Approver identity.
  • Authorization scope.

If the operation parameters change after approval, re-approval should be required.


6. Human Feedback and Agent Self-Correction

HITL does not only let humans decide whether execution can proceed; it can also let humans participate in the Agent's reasoning and result correction.

Human feedback can be divided into several types.

6.1 Supplementary Information

When the user's request is not sufficiently clear, the Agent can ask the user for additional information.

For example:

User:

Help me analyze recent sales performance.

The Agent may need to know more about:

  • Which time range should be analyzed?
  • Which products should be focused on?
  • Is a regional comparison needed?
  • Are charts needed?

After the user provides additional information, the Agent adds the new information to the current task state and then continues execution.

6.2 Correcting Parameters

Suppose the Agent is about to query:

{
  "start_date": "2026-10-01",
  "end_date": "2026-10-31",
  "region": "all"
}

A human finds that only East China should be analyzed, so it is changed to:

{
  "start_date": "2026-10-01",
  "end_date": "2026-10-31",
  "region": "east"
}

The Agent should use the modified parameters as the new execution input, instead of continuing to use the original parameters.

6.3 Modifying Generated Results

For example, the Agent generates a business analysis report, and a human proposes:

  • Remove unverified conclusions.
  • Add data sources.
  • Adjust the chart presentation.
  • Focus on changes in profit margin.
  • Add explanations for anomalous data.

The Agent regenerates the content based on the feedback.

6.4 Correcting Decision Direction

Sometimes the Agent's reasoning direction itself is biased.

For example:

The Agent believes that the sales decline is due to prices being too high.

A human adds the following information:

This month's main problem is insufficient inventory, not price.

The Agent should update the current task context and re-analyze inventory, order, and sales data, rather than merely revising one sentence in the report.

6.5 Closed Loop of Human Feedback

flowchart TD
    A["Agent generates initial decision"] --> B["Show decision and rationale"]
    B --> C["Human review"]
    C --> D{"Feedback type"}
    D -->|"Additional information"| E["Supplement task context"]
    D -->|"Modify parameters"| F["Correct execution parameters"]
    D -->|"Modify result"| G["Adjust generated content"]
    D -->|"Correct direction"| H["Adjust task goal or strategy"]
    E --> I["Update Agent State"]
    F --> I
    G --> I
    H --> I
    I --> J["Agent re-reasons"]
    J --> K["Generate new decision"]
    K --> L{"Meets requirements?"}
    L -->|"No"| B
    L -->|"Yes"| M["Continue task execution"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style E fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style G fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style I fill:#EAF3EC,stroke:#83A995,color:#315D49
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style M fill:#E5F0E9,stroke:#83A995,color:#315D49

Human feedback should be explicitly recorded, including the feedback provider, feedback time, feedback content, and the corresponding task version.

If the feedback will change an important business decision, the original decision and the revised decision should also be retained for traceability.


7. HITL and Agent State Persistence

Human-agent collaboration is usually not a one-off, real-time interaction.

An approver may respond only after a few minutes, or may not process it until several hours or even days later.

Therefore, the Agent must be able to release execution resources while waiting for human feedback and resume the original task after receiving a response.

This requires combining State, Checkpoint, and persistence mechanisms.

7.1 Why Persistence Is Needed

Suppose the Agent is executing a procurement task:

  1. Query supplier quotes.
  2. Compare supplier qualifications.
  3. Generate a procurement recommendation.
  4. Submit the procurement request for approval.
  5. Wait for administrator confirmation.

If the Agent keeps occupying a Worker while waiting for approval, it wastes execution resources.

If the process is shut down and the state has not been saved, the original task cannot be resumed afterward.

Therefore, a reasonable design is to:

  • Save the current Agent State.
  • Save the current checkpoint.
  • Create a separate approval record.
  • Set the task status to Waiting.
  • Release the current Worker.
  • Wait for an approval event.
  • Reschedule the task after approval is complete.
  • Resume execution from the checkpoint.

7.2 HITL State Design

from typing import TypedDict, Literal, Any

class ApprovalInfo(TypedDict):
    approval_id: str
    status: Literal[
        "pending",
        "approved",
        "rejected",
        "expired",
        "cancelled"
    ]
    approver_id: str | None
    comment: str | None

class AgentState(TypedDict):
    task_id: str
    goal: str
    messages: list[Any]

    status: Literal[
        "running",
        "waiting",
        "completed",
        "failed",
        "cancelled"
    ]

    current_step: str
    iteration: int

    pending_action: dict[str, Any] | None
    approval: ApprovalInfo | None

    checkpoint_id: str | None

Here, pending_action is used to store the content of the operation awaiting approval.

approval is used to record the approval status.

checkpoint_id is used to associate the current task with its corresponding persisted checkpoint.

7.3 Human-in-the-Loop Waiting State Machine

State Meaning Main Action
Running The Agent is executing Normal operation
Approval Pending Waiting for approval Pause and save state
Approved Approval granted Allow execution to continue
Rejected Approval rejected Terminate or adjust the task
Waiting Input Waiting for user input Save context
Resuming Resuming Load checkpoint
Completed Task completed Save final result

7.4 Pause and Resume Flow

flowchart TD
    A["Agent Executes Task"] --> B["Identify Need for Human Intervention"]
    B --> C["Generate Operation Pending Approval"]
    C --> D["Save Agent State"]
    D --> E["Create Checkpoint"]
    E --> F["Create Approval Record"]
    F --> G["Set Task Status to Waiting"]
    G --> H["Release Worker"]
    H --> I["Wait for Approval Event"]
    I --> J["Receive Approval Result"]
    J --> K["Verify Approver Permissions"]
    K --> L{"Approval Result"}
    L -->|"Approved"| M["Update Approval Status"]
    L -->|"Rejected"| N["Update Rejection Status"]
    M --> O["Create Resume Task"]
    O --> P["Load Checkpoint"]
    P --> Q["Validate Pending Operation"]
    Q --> R["Continue Agent Loop"]
    N --> S["Terminate or Adjust Task"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#EAF3EC,stroke:#83A995,color:#315D49
    style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style M fill:#E5F0E9,stroke:#83A995,color:#315D49
    style N fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style O fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style P fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style Q fill:#EAF3EC,stroke:#83A995,color:#315D49
    style R fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style S fill:#F7EAE7,stroke:#C98D7C,color:#754438

7.5 Consistency Between Approval and Execution

Here is a very easily overlooked issue:

After approval, the Agent may fail to receive the resume event due to network issues or a process crash.

If the system relies only on a single message notification, a task may wait forever.

A more reliable approach is:

  • Persist approval records.
  • Update approval results transactionally.
  • Write approval-completed events to a reliable message queue, or use a transactional Outbox.
  • Have a background scheduler scan for tasks awaiting resumption.
  • Make resume operations idempotent.
  • Allow only one valid Worker to take over a given task.

In addition, after approval, the Agent must not directly trust the action parameters in the historical state.

Before execution, the parameters, permissions, and approval validity period still need to be revalidated to ensure that the operation actually executed is consistent with the approved content.


8. Implementing Human-in-the-loop with LangGraph

LangGraph provides mechanisms suitable for building HITL workflows, the most important of which are:

  • interrupt(): Pause the current execution and wait for external input.
  • Command(resume=...): Provide resume data to a paused flow.
  • Checkpointer: Save graph execution state.
  • thread_id: Associate checkpoints for the same execution thread.

Combined, these mechanisms can implement Agent pause, human approval, and execution resumption.

8.1 Define Agent State

from typing import TypedDict, Literal, Any

class AgentState(TypedDict):
    task: str
    action: dict[str, Any]

    status: Literal[
        "running",
        "waiting",
        "approved",
        "rejected",
        "completed"
    ]

    approval_result: dict[str, Any] | None
    result: str

8.2 Define Nodes Requiring Human Approval

from langgraph.types import interrupt

def approval_node(state: AgentState):
    action = state["action"]

    decision = interrupt({
        "type": "approval",
        "task": state["task"],
        "action": action,
        "message": "是否允许执行该操作?"
    })

    return {
        "approval_result": decision,
        "status": (
            "approved"
            if decision.get("approved")
            else "rejected"
        )
    }

interrupt() pauses the current graph execution and treats the data passed to it as a pending human-in-the-loop interaction message.

The caller can retrieve the content of the approval request from it and pass it to a frontend approval interface or a business approval service.

Note: a node containing interrupt() may be re-executed from the beginning of the node when it resumes. Therefore, code placed before interrupt() should avoid causing non-repeatable external side effects.