Human-in-the-Loop (HITL)
Your agent does the prep work, but it may not send the email or issue the refund until you say yes. Human-in-the-loop is the pause before the risky tool runs.
Why Does This Exist?
Give a support agent send_email and issue_refund and you have given it the power to embarrass you in public and move money. It drafts beautifully. It will also misread a sarcastic ticket one day and fire off the wrong reply to the wrong customer. That send can't be unsent.
Human-in-the-loop is the pause you put between deciding and doing. The agent still does the grunt work. It reads the thread, pulls the order, drafts the reply, fills in the refund amount. But the risky call doesn't run until you say yes. You keep the speed for everything reversible and keep a hand on the lever for everything else.
This page covers that pause: the gate, the saved state, the approve or deny round trip. It doesn't cover which tools the agent should have at all. That is tool permissions. It doesn't cover automatic input and output filters. Those are guardrails.
The one idea you need first: an agent runs a loop. It thinks, proposes one tool call, runs it, reads the result, and thinks again. That loop plus its step cap, timeouts, and error handling is the agent harness. Human-in-the-loop cuts into that loop at exactly one place: after the proposal, before the run. If you haven't seen the loop, read the harness page first. Everything here assumes you know what a proposed call looks like.
Think of It Like This
A woodshop apprentice and a locked tablesaw
You hire an apprentice who measures fast and never gets tired. All day they can sand, measure, and write up cut lists on their own. Those are the safe tools. The tablesaw stays locked. When a board needs cutting, the apprentice brings you the board with the cut line marked, you unlock the saw, watch the cut, and lock it again. If the line is wrong you mark a fresh line, say why, and send them back to remeasure.
The mapping is direct. The apprentice is the agent. Sanding and measuring are read-only calls. The tablesaw is send_email or issue_refund. The lock is the gate. You are the reviewer. Unlocking is approve. Marking a fresh line with a reason is deny with a note.
Where it stops: wood never talks back. Your agent does. A denial becomes new text the agent must replan from, which an apprentice would never need. And unlike a shop, the paused run has to be written down somewhere to survive the wait. Leave for lunch and the saw is still locked. An agent left in memory is gone.
How It Actually Works
Every pause follows the same five steps: propose, sort, save, decide, resume. The vocabulary below keeps them straight.
Let be the proposed tool call, meaning its name plus its arguments, such as send_email with a to address and a body. Let be the gating rule, meaning the function that maps each to either auto or review. Let be the saved agent state at the pause, meaning the message history plus the pending . Let be the human decision, meaning either approve or deny with a short note. Let be the observation returned to the agent on resume, meaning the text the loop reads next.
The gate decides auto or review
runs before anything executes. The usual inputs are a denylist of tool names, a risk tier per tool, and a threshold such as a refund amount. search_db and draft_reply map to auto. send_email and issue_refund map to review. You want strict enough that no irreversible call slips past, and narrow enough that routine reads never queue. That is the whole trade-off: each extra tool you mark review buys safety and spends reviewer minutes plus agent waiting time.
Do not use this gate for low-stakes reversible reads. If the call changes nothing outside the run, let it run. Do not use it where a human cannot answer in time, such as live control or high-frequency triage. There the queue itself becomes the failure, so you need tighter permissions or automatic checks instead.
Pause, decide, resume
When is review, the harness does not call the tool. It writes to durable storage, attaches an idempotency key to so a retry cannot double-send, and pings the reviewer with the full context: the arguments, the diff, the ticket, and why flagged it. The run then sleeps.
You read that card and return . On approve, the harness runs , builds from the tool result, and resumes the loop from . On deny with a note, it skips the tool, builds from your note, for example "too blunt, restate the fee before asking for confirmation", and resumes so the agent can try a fresh . The assumption holding all of this up is that you actually read the card with enough context to judge it. A tired reviewer clicking approve on everything carries the same risk as no gate at all, only slower.
Worked example: 20 calls, 14 auto, 6 wait
Take one support shift. The agent proposes 20 tool calls.
14 are safe: 8 search_db lookups and 6 draft_reply drafts. maps all 14 to auto, so they run at once with no wait. That is , so 70 percent of the work stays autonomous.
6 are risky: 4 send_email sends and 2 issue_refund refunds. maps all 6 to review. The harness saves each , queues 6 cards, and waits. That is , so a 30 percent review rate.
You approve 4 and deny 2 with rewrite notes. The 4 approvals run and their results return as . The 2 denials return your notes as and the agent redrafts. Approval share is , about 67 percent. Denial share is , about 33 percent.
Notice what you bought. You read 6 cards instead of 20, and the 2 risky sends that would have gone out never ran. What you paid is wait time on those 6 plus the discipline to keep durable so a late click still resumes the right run.
Code
The point of this snippet is the sort plus the count. It runs the same the prose describes over a six-call fixture and tallies what would have paused, so you can check the review load before you ship the policy.
from typing import Literal
DANGEROUS: set[str] = {"send_email", "issue_refund"}
def gate(tool: str) -> Literal["auto", "review"]: """Return review for risky tools, auto for the rest.""" return "review" if tool in DANGEROUS else "auto"
def run(tool: str) -> str: """Stand-in for the real tool implementation.""" return f"ran {tool}"
calls: list[str] = [ "search_db", "draft_reply", "send_email", "issue_refund", "search_db", "send_email",]
auto: int = sum(1 for c in calls if gate(c) == "auto")paused: int = len(calls) - autoprint(auto, paused) # -> 3 3
decisions: dict[str, str] = {"send_email": "approve", "issue_refund": "deny: rewrite needed"}blocked: int = sum(1 for c in calls if gate(c) == "review" and decisions[c] != "approve")print(blocked) # -> 1Three calls run at once, three pause, and one of the paused calls stays blocked. That matches the gate above: the two send_email entries approve and would call run, while the issue_refund entry returns its denial note as the next observation instead.
Watch Out For
Rubber-stamp approvals that keep the risk and add delay
The symptom is a dashboard with a 100 percent approval rate and median review times under ten seconds. Nothing is truly reviewed, yet every risky call now waits in a queue. One bad send still slips through, and you paid latency for no safety.
Fix it by making approval take real evidence. Show the exact arguments and diff, not just the tool name. Show why flagged the call. Require a short reason on high-stakes approvals, sample past approvals for audit, and rotate reviewers before fatigue sets in. If approvals stay instant and total, your tiers are too wide or your cards hide the detail that matters.
A pause that loses its place and sends twice
The symptom is ugly: you click approve an hour later and the run crashes, resumes the wrong ticket, or sends the same email twice. The cause is a pause kept only in memory. The request ended, the process restarted, and went with it.
Fix it by treating every pause as a database row. Persist with the pending , resume by id, and key the tool call so a retried approve cannot execute twice. Give each pending card a time to live whose expiry defaults to deny, never to silent auto-approve. Test the late click and the double click before you trust the happy path.
The Quick Version
- Human-in-the-loop means the agent proposes each tool call but a risky one never runs until you approve it.
- A gating rule sorts every call into auto or review before anything executes, so reads stay fast and sends wait.
- A paused run must be saved to storage with a retry-safe key, or a late click resumes the wrong work or sends twice.
- Denials return as text the agent must replan from, which makes the quality of your note decide how fast it recovers.
- Skip this pattern for reversible reads and for decisions a human cannot reach in time, and watch for reviewers who approve everything without reading.