Human-in-the-Loop

HITL checkpoints give you control over where and when agents act without human oversight. You decide the balance between autonomy and governance.

How it works

1. A pipeline reaches a human-in-the-loop (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 FeedbackRecords 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 auto-expires if the reviewer doesn’t act.

// Claim a HITL request
POST /api/v1/hitl/requests/{id}/claim

// Approve
POST /api/v1/hitl/requests/{id}/approve

// Reject
POST /api/v1/hitl/requests/{id}/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

When a pipeline reaches a HITL checkpoint, Modulo sends a webhook to configured URLs:

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

Governance tiers