Human-in-the-Loop

Human-in-the-loop (HITL) checkpoints give you control over where and when agents require human oversight before acting. You decide the balance between autonomy and governance.

How it works

1. A pipeline reaches a HITL checkpoint node
2. Execution pauses and the system creates a review request
3. A reviewer claims the request (15-minute time-to-live exclusive claim window)
4. The reviewer inspects the artifact and context
5. The reviewer approves (pipeline continues) or rejects (pipeline stops). Rejections create structured Feedback Records that can trigger AI-powered correction runs.

Claim workflow

Each HITL request has a claim_token with a 15-minute time-to-live (TTL). Once claimed, other reviewers see it as claimed and cannot take it. The claim expires automatically if the reviewer does not act within the window.

POST /api/v1/runs/{run_id}/hitl/{review_id}/claim    # Claim a HITL gate
POST /api/v1/runs/{run_id}/hitl/{review_id}/approve  # Approve
POST /api/v1/runs/{run_id}/hitl/{review_id}/reject   # Reject

Review UI

The review interface shows:

• The artifact produced by the agent (diff, text, JSON, file)
• The prompt that generated it
• The full run context and upstream agent outputs
• Previous review history for this pipeline
• An approval checklist (configurable per pipeline)

Notification webhooks

Modulo sends a webhook to each configured endpoint when a HITL event fires:

The payload carries the run and gate identity, for example:

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

The url is your instance’s public URL (MODULO_PUBLIC_URL) with the run’s detail path appended.

Run-level events share the same channel: run_failed, run_stalled, budget_exceeded, and circuit_breaker_tripped. Failed deliveries retry with a backoff.

Rejection handling

When a reviewer rejects an artifact, the rejection is recorded as a structured Feedback Record. The pipeline’s feedback handler determines the next step: manual review, automatic AI correction, or AI correction with human review. See Feedback System for the full routing strategy.

Who can decide a human-only gate

A gate can be marked human-only where oversight must come from a person rather than an automated step. Deciding one from Model Context Protocol (MCP) requires a credential linked to a human account: a consent-derived OAuth token issued to a member of your organization. An MCP API key, including a per-user key, and any service-account credential are refused.

A human-linked token is meant for a local client you are driving yourself, on your own machine. Do not put one into a cloud agent, a pipeline, or a shared continuous integration (CI) job, because a decision made that way is still recorded as yours. Use an organization or machine credential for anything that runs unattended. Those credentials cannot decide a human-only gate, by design.

Approving a human-only gate with your own token is you approving it. The audit record attributes the decision to the human whose token it was, not to the agent and not to Modulo.

This tells you whose account a decision belongs to. It does not prove the person was present when the decision was made, because a token can be copied. Treat it as that person’s stated authority, not as evidence they were at the keyboard. Manually delivering a gate’s output remains browser-only.

Governance tiers

Related

• Pipelines: the directed-graph execution model
• Feedback System: rejection routing and correction runs
• Agents: the atomic units that make up a pipeline
• Evals: automated quality checks that run before HITL gates
• MCP: claiming and deciding gates from an MCP client