Human-in-the-Loop (HITL)

HITL lets you pause the pipeline at key phase boundaries, review what the agents are about to do, and approve, reject, or redirect before they continue.

Enabling HITL

Set hitl_enabled: true in your pipeline request and specify which phases to pause at:

{
  "prompt": "...",
  "goal": "production",
  "hitl_enabled": true,
  "hitl_phases": ["planning", "design", "release"]
}

When to use HITL

• planning — review the architecture before any code is written (highest value)
• design — review the database schema and API contracts
• release — review the full output before deployment config is generated

The checkpoint event

When the pipeline reaches a HITL phase it emits a checkpoint event on the SSE stream and pauses:

event: checkpoint
data: {
  "checkpoint_id": "chk_a1b2c3",
  "phase": "planning",
  "type": "hitl",
  "summary": "IdeationAgent and ArchitectureAgent have completed. Review before implementation.",
  "outputs": {
    "IdeationAgent": "...",
    "ArchitectureAgent": "..."
  }
}

The build stays paused until you resolve the checkpoint. There is no timeout — take as long as you need.

Resolving a checkpoint

POST /pipeline/v2/checkpoint/{checkpoint_id}/resolve

Approve

{ "action": "approve" }

Pipeline continues from where it paused.

Approve with feedback

{
  "action": "approve",
  "feedback": "Use Redis for session storage instead of database sessions"
}

The feedback is injected into the context of the next agent before it runs.

Reject and redirect

{
  "action": "reject",
  "feedback": "Use Django instead of FastAPI, and MySQL instead of PostgreSQL"
}

The relevant agents re-run with the new direction.

Modify

{
  "action": "modify",
  "feedback": "Add a rate limiting middleware and a background job queue"
}

modify is like approve with feedback — it continues but injects the change as a new requirement.

Managing checkpoints

# List all pending checkpoints
GET /api/checkpoints?status=pending

# Get all sessions paused and waiting for input
GET /api/checkpoints/resumable-tasks

# Get a specific checkpoint with its stored outputs
GET /api/checkpoints/{checkpoint_id}

Best practice

For Production goal builds, enable HITL on planning at minimum. Reviewing the architecture before 15+ agents generate thousands of lines of code is the single highest-leverage intervention point.

For Prototype builds, skip HITL entirely — speed is the priority.