Human-in-the-Loop

AI is powerful, but it's not perfect. For sensitive actions—like charging a card, dropping a production database, or sending an email to a VIP—you need a Human-in-the-Loop (HITL).

Cencori Workflows makes this trivial with the .waitFor() primitive.

The Concept

A Workflow can Pause its execution and hibernate. It consumes no compute resources while waiting. It creates a Pending Action that can be resolved via the API or Dashboard.

Implementation

1. The waitFor Step

In your workflow code, simply yield a wait step.

// Inside your workflow
const plan = await agent.createPlan();
 
// PAUSE HERE
const approval = await cencori.workflows.waitFor('human_approval', {
  timeout: '24h',
  metadata: {
    plan_summary: plan.summary,
    risk_score: plan.risk
  }
});
 
if (approval.status === 'rejected') {
  await agent.reply("Plan rejected by human. Stopping.");
  return;
}
 
// RESUME HERE
await agent.executePlan(plan);

2. Building the UI

You can build a simple UI in your admin dashboard to fetch and resolve pending tasks.

Fetch Pending Tasks:

// GET /api/cencori/workflows/pending
const pendingTasks = await cencori.client.workflows.listPending();

Resolve a Task:

// POST /api/cencori/workflows/{id}/resume
await cencori.client.workflows.resume(taskId, {
  status: 'approved',
  feedback: "Looks good, proceed!"
});

3. Interactive Notifications

A common pattern is to send a notification to Slack/Discord with "Approve" and "Reject" buttons.

1. Workflow: Sends Slack message with buttons.
2. Workflow: Calls waitFor('slack_interaction').
3. Slack: User clicks "Approve".
4. Webhook: Slack hits your webhook -> calls cencori.resume().
5. Workflow: Wakes up and continues.

Timeout Handling

What if the human never approves? You should always set a timeout.

try {
  await cencori.workflows.waitFor('approval', { timeout: '1h' });
} catch (error) {
  if (error.code === 'TIMEOUT') {
    // Auto-reject or escalate
    await tools.email.send("Manager", "Approval timed out!");
  }
}

Security

HITL is a security feature. It ensures that the AI cannot execute high-risk tools (like stripe.charge or aws.deleteInstance) without explicit authorization token generated by the resume call.