HITL Architecture

Human-in-the-Loop — Escalation Infrastructure for Autonomous Agents

This document describes the architecture powering the Human-in-the-Loop (HITL) system — webhook-based approval workflows delivered via Telegram, designed for autonomous agent systems that need human oversight at critical decision points.

System Overview

The HITL system operates as a lightweight middleware layer between autonomous agents and human reviewers. When an agent encounters a decision that exceeds its confidence threshold or requires external authorisation, it sends an escalation request via webhook. The system routes this request to the appropriate human reviewer through Telegram, captures the response, and returns it to the calling agent.

Architecture Diagram

Key Components

1. Webhook Receiver

Accepts POST requests from autonomous agents containing escalation payloads. Each request includes: agent ID, confidence score, context data, proposed action, and required reviewer role. Requests are validated against a schema and queued for processing.

2. Routing Engine

Determines which human reviewer should handle each escalation based on:

• Role-based routing — escalations go to the appropriate team member (e.g., compliance, operations, technical)
• Round-robin load balancing — distributes reviews evenly across available reviewers in a role
• Escalation policies — configurable timeout and fallback rules if no reviewer responds

3. Telegram Integration

Delivers escalation notifications to human reviewers via a dedicated Telegram bot. The bot presents structured approval cards with action buttons (Approve / Reject / Request Info). Reviewers can respond inline without leaving Telegram.

4. Audit Log

All escalations, decisions, and metadata are recorded in PostgreSQL for compliance, debugging, and performance analysis. Each record includes timestamps, reviewer identity, decision rationale, and response latency.

Configuration

The HITL system is configured via environment variables or a hitl.json configuration file:

{
  "telegram_token": "your_bot_token",
  "reviewers": {
    "operations": ["@user1", "@user2"],
    "compliance": ["@user3"]
  },
  "timeout_seconds": 300,
  "fallback_action": "reject",
  "pg_connection": "postgresql://..."
}

Deployment

The HITL middleware can be deployed as a standalone Node.js service or as a serverless function on Vercel. The Telegram bot component runs as a persistent process with webhook polling.

For more details, visit the main HITL product page.