Humans in the loop (HITL) gates are checkpoints in a Modulo pipeline where execution pauses for a person to review agent output. They put a decision point in front of high-stakes steps: merging a pull request, shipping a config change, or sending a customer-facing message. The reviewer inspects the artifact and its context, then approves or rejects.

In short

A HITL checkpoint pauses the run and sends a review request to a person; the pipeline continues only after approval.
Use it on high-stakes write steps - merging code, shipping config, changing billing - where a mistake is expensive.
Skip it on read-only steps, or high-volume work where deterministic gates already catch the failure modes.
Rejections create a FeedbackRecord and can trigger a correction run.

The problem it solves

Say an agent drafts and merges pull requests, opening a PR with a working diff, passing tests, and landing the change while you are in another meeting - until one day it merges a PR with a hardcoded API key or a billing change nobody intended to ship. The merge is done and the secret is in the repo. Automated gates (regex, schema, or function checks) catch patterns and structure - a regex can flag a key in a diff - but they cannot judge whether a change should ship. That judgment needs a person, after the work is produced and before the irreversible step.

How it works

A HITL gate is a checkpoint node in a pipeline.

The run pauses and creates a review request

Place a checkpoint node wherever a mistake would be expensive. When the run reaches it, execution stops and the system creates a review request, holding the work until someone sees it.

A reviewer claims the request

Each request carries a claim_token that expires after 15 minutes. A reviewer claims it, the team sees it as taken, and the window auto-expires so no one holds a request forever.

The review shows the artifact and its context

The review screen shows the artifact - a diff, text, JSON, or file - alongside the prompt that generated it, the run context, previous review history, and a per-pipeline approval checklist. The reviewer decides with the same information the agent had.

Approve or reject

Approving continues the run from the checkpoint; rejecting stops it. A rejection creates a structured FeedbackRecord that can trigger a correction run, with the reviewer's objections as input to the new attempt.

The pipeline notifies your team

When a run reaches a checkpoint, Modulo sends a webhook to the URLs you configure. The event is hitl.awaiting_review, with the pipeline, run, and agent that raised it:

{
  "event": "hitl.awaiting_review",
  "pipeline_id": "...",
  "run_id": "...",
  "agent_name": "draft-email",
  "url": "https://<your-modulo-host>/runs/..."
}

Set the governance tier

Checkpoints appear by tier: Full autonomy proceeds without review, Guarded requires review on writes, and Gated requires review on every action. A pipeline can start strict and loosen as evidence builds - review every action, then only writes, then run without review once the gates rarely fire. This treats autonomy as earned rather than default; see the principles.

Journey example: before and after

Before

A support team run by Marta uses an agent to draft customer replies and sends them automatically. One week a dismissive draft reaches an angry customer, who cancels. Repairing that means apologizing to someone who already decided, walking the mistake back in public, writing a correction, and explaining it to the account team - at far more cost than the automation saved.

After

Marta adds a HITL checkpoint before every send. Each draft pauses, the review screen shows the reply with the full customer thread as context, and she or a teammate approves it. A few minutes of review turns a bad draft into a rejection click, not a lost customer, and the rejection's FeedbackRecord feeds the next draft.

When to use it vs. when not to

Use HITL gates where a mistake is expensive or hard to undo: merging code, changing billing or permissions, moving money, sending customer-facing messages, or any write to production data. Use them for a new agent until its record is long enough to judge; a gate on every step turns the team into a click-through queue where reviews stop being careful. When an automated gate already covers a failure mode - a regex catching secrets or a schema check catching shape - keep the checkpoint for judgment calls.

Where it fits in a pipeline

HITL gates sit between deterministic gates and the audit trail: automated gates catch patterns, checkpoints catch judgment calls, and the audit trail records both, letting a pipeline earn the right to run with less oversight. For the gate types that run before a person looks, see Every gate type in Modulo and when to use each.

Go deeper

Read the HITL docs for the checkpoint flow, or the related docs on pipelines, feedback, and agents. Take the product tour to see HITL gates in action, or use the contact page to talk about adding a HITL gate to your pipeline.