Home › Claude › Agent › Human in the Loop

🧑‍⚖️ Human in the Loop: people stay in charge

Agents are fast, but they can misunderstand, and some actions can't be undone. Human-in-the-loop design adds checkpoints where a person reviews what the agent proposes and decides whether it goes ahead.

• Beginner
• ⏱ 25 min
• General workflow pattern

What is it?

Human in the loop means the agent's workflow includes deliberate pauses where a person must approve, reject, correct or stop what the agent wants to do before it happens.

Proposal

What the agent wants to do, shown to a person before it is done (for example a draft email).

Approval checkpoint

A point in the workflow that cannot be passed without a human decision.

Irreversible action

Something that can't be undone: sending, paying, publishing, deleting.

Audit log

A permanent record of who decided what, and when.

Reviewer

The person authorised to make the decision.

Why is human oversight important?

• AI makes mistakes: it can misread a request, use the wrong recipient or state a wrong figure with confidence.
• Some actions are permanent: you can't un-send an email or un-pay an invoice.
• Manipulation: text the agent reads, such as an email or web page, may try to trick it (prompt injection). A human checkpoint stops a tricked agent from causing damage.
• Accountability: organisations, and sometimes laws, require a named person to approve certain decisions.
• Trust: people are more willing to use agents when they know nothing important happens without their OK.

Examples that need a human

Real-world analogy

How does it work?

1. The agent works until it reaches an action that needs approval.
2. It pauses and saves where it is, presenting a clear proposal: what it will do, to whom, and why.
3. The reviewer is notified and looks at the proposal.
4. The reviewer decides: Approve, Reject or Request changes (with feedback).
5. The decision is recorded in the audit log.
6. The workflow resumes: approve → the action happens; changes → the agent revises and asks again; reject → it stops safely.

Workflow diagram

Try it: approve the agent's email

In the loop, on the loop, or fully automated?

Many systems mix all three: automate the safe parts, monitor the medium-risk parts and require approval for the risky parts.

Practical example: draft an email, wait for approval

1. The agent drafts the client email with Claude.
2. The workflow pauses and shows the draft to the account manager.
3. The manager clicks Request changes: "Mention we'll add a free extra review session."
4. The agent writes version 2 with the feedback included and pauses again.
5. The manager clicks Approve, and only then is the email sent. Every step is in the audit log.

Code example

Runnable Python. Claude writes the drafts, and you approve in the terminal. Sending is simulated (it just prints). It needs pip install anthropic and the ANTHROPIC_API_KEY environment variable on your computer or server.

# hitl_email.py: the agent drafts, a human decides, and only then is the email "sent".
import datetime
import hashlib
import json
import anthropic

client = anthropic.Anthropic()
AUDIT_LOG = "audit_log.jsonl"
APPROVED = set()  # fingerprints of the exact drafts a human approved

def audit(event: str, **details):
    """Add one line per event (who, what, when). Old lines are never edited."""
    entry = {"time": datetime.datetime.now(datetime.timezone.utc).isoformat(), "event": event, **details}
    with open(AUDIT_LOG, "a", encoding="utf-8") as f:
        f.write(json.dumps(entry) + "\n")

def fingerprint(text: str) -> str:
    return hashlib.sha256(text.encode()).hexdigest()[:12]  # short unique ID for this exact text

def draft_email(request: str, feedback: list) -> str:
    prompt = f"Write a short, polite email for this request:\n{request}"
    if feedback:
        prompt += "\n\nRevise it using this reviewer feedback:\n- " + "\n- ".join(feedback)
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=16000,
        messages=[{"role": "user", "content": prompt}],
    )
    return "".join(b.text for b in response.content if b.type == "text")

def send_email(to: str, body: str):
    # The approval check lives INSIDE the risky action, so no code path can skip it.
    if fingerprint(body) not in APPROVED:
        raise PermissionError("Blocked: this exact email has not been approved by a human.")
    print(f"\n[email] (Simulated) email sent to {to}.")  # swap in your real email service here
    audit("email_sent", to=to, draft=fingerprint(body))

def run(request: str, to: str, reviewer: str):
    feedback = []
    for round_no in range(1, 4):  # at most 3 drafts
        draft = draft_email(request, feedback)
        audit("draft_created", round=round_no, draft=fingerprint(draft))
        print(f"\n--- Draft {round_no} ---\n{draft}\n")

        choice = input("Approve (a), request changes (c) or reject (r)? ").strip().lower()  # ⏸ pauses here
        if choice == "a":
            APPROVED.add(fingerprint(draft))
            audit("approved", reviewer=reviewer, draft=fingerprint(draft))
            send_email(to, draft)
            return
        if choice == "c":
            note = input("What should change? ")
            feedback.append(note)
            audit("changes_requested", reviewer=reviewer, feedback=note)
            continue  # loop back: the agent revises
        # Anything else counts as a rejection, which is the safe default.
        audit("rejected", reviewer=reviewer, draft=fingerprint(draft))
        print("Stopped. Nothing was sent.")
        return
    audit("stopped", reason="too many revisions")
    print("Too many revisions. Stopping. Nothing was sent.")

if __name__ == "__main__":
    run("Tell the client the delivery moves from 3 Nov to 10 Nov because of extra testing.",
        to="client@example.com", reviewer="maria")

Example session:

--- Draft 1 ---
Dear client, we need to move the delivery date from 3 November to 10 November ...

Approve (a), request changes (c) or reject (r)? c
What should change? Offer a free extra review session.

--- Draft 2 ---
Dear client, ... To make up for the delay, we'd like to offer a free extra review session ...

Approve (a), request changes (c) or reject (r)? a

[email] (Simulated) email sent to client@example.com.

Pausing for hours or days. In a real app, the reviewer isn't sitting at a terminal. Instead of input(), you save the agent's state and resume when the decision arrives. Here is the idea as a sketch:

# Save state, notify, stop. Resume later when a person decides.
task = save_task(status="waiting_for_approval", draft=draft, messages=messages, to=to)
notify_reviewer(task.id)                 # e.g. a chat message with Approve / Reject buttons

def on_decision(task_id, decision, reviewer, feedback=""):
    task = load_task(task_id)
    if task.status != "waiting_for_approval":
        return                           # already handled: ignore double-clicks
    if not reviewer_may_approve(reviewer, task):
        raise PermissionError("This person is not allowed to approve this task")
    audit(decision, reviewer=reviewer, task=task_id, feedback=feedback)
    if decision == "approve":
        send_email(task.to, task.draft)
    elif decision == "changes":
        resume_agent(task.messages, feedback)   # agent revises and asks again
    else:
        mark_stopped(task)

Step-by-step explanation

1. audit() appends one JSON line per event to audit_log.jsonl, so there is a permanent record of who did what and when.
2. fingerprint() makes a short ID from the exact text of a draft. If even one character changes, the ID changes.
3. draft_email() asks Claude for a draft and includes any reviewer feedback so far. This is how feedback is recorded and used when the workflow resumes.
4. send_email() refuses to send any text whose fingerprint wasn't approved. The check is inside the risky action, so even buggy code elsewhere can't skip it.
5. input(...) is the pause: the program waits for a human decision.
6. "a" records the approval and sends. "c" records the feedback and loops back. Anything else is treated as a rejection, because when unsure, do nothing.
7. range(1, 4) limits the number of revisions so a disagreement can't loop forever.
8. The pause-and-resume sketch shows how real apps wait for a long time. It also checks that the reviewer is allowed to approve and ignores duplicate clicks.

Checkpoints, audit logs, permissions and error recovery

Use cases

• Customer emails, social posts and press releases
• Refunds, payments, purchase orders and price changes
• Deleting or overwriting data, and changing permissions
• Code changes deployed to production
• Medical, legal or HR decisions, where AI should assist rather than decide

Advantages and limitations

Best practices

• Make proposals easy to judge: show exactly what will happen, to whom, and why.
• Ask for approval only where it matters, so reviewers stay attentive.
• Enforce approval inside the action's code, and approve the exact content.
• Treat silence, errors and timeouts as "no".
• Log every decision, and review the logs regularly.
• Never accept "approval" that appears inside content the agent read. Only your approval system counts.

Knowledge check

Mini project

Key takeaways

• HITL adds checkpoints where a person approves, rejects or corrects the agent.
• Use it for anything costly, public or irreversible, and enforce it in code.
• Pause by saving state, resume by feeding the decision and feedback back in.
• Log every decision. Silence and errors mean "no".
• Choose in-the-loop, on-the-loop or automated based on risk.

Further learning

• Building effective agents, on when agents should pause for human feedback (Anthropic engineering blog)
• Claude Agent SDK overview, including permission controls for tool use (official docs)
• Claude Code security, on how Claude Code asks for permission (official docs)
• Tool use overview (official docs)