HITL Protocol — Interactive Playground

The Core Idea

"HITL Protocol is to human decisions what OAuth is to authentication"

Agent

Service

Human

Service returns HTTP 202 → Agent forwards URL → Human decides in browser → Agent polls result

Aligned references: RFC 9110 (HTTP), RFC 3339 (timestamps), RFC 6750 (bearer auth), RFC 2119/8174 (normative terms).

Case Lifecycle

pending

→

opened

→

in_progress

→

completed

Also: pending/opened → expired

Also: any non-terminal → cancelled

opened and in_progress are optional intermediate states. Terminal states have glow borders.

HITL Object Anatomy

Transport Options

Polling

Default

Agent calls GET poll_url every 30s-5min. Stateless. No server needed on agent side. Works everywhere.

SSE

Real-time

Agent opens persistent connection to events_url. Server pushes status updates instantly. No public endpoint needed.

Callback

Webhook

Service POSTs result to callback_url. Requires agent to expose a public endpoint. Signed via X-HITL-Signature: sha256=<hmac> header.

5 Review Types

Approval

Go/no-go on an artifact. CV draft, deployment plan, email.

approve ✓ edit ↩ reject ✗

edit creates new round (previous_case_id chain)

Selection

Choose one or more from options. Job listings, configs, templates.

select

Returns selected option IDs. Often followed by confirmation.

Input

Structured data entry via context.form. Supports multi-step wizards.

submit

10 field types, validation, conditional fields, sensitive data

Confirmation

Irreversible action check. Send emails, deploy, delete data.

confirm ✓ cancel ✗

One-shot. No edit loop. Irreversible action gate.

Escalation

Something failed. Retry, skip, abort, or provide new params.

retry skip abort ✗ edit ↩

Error recovery. Human provides fix strategy.

Use Case 1: Job Search Selection + Confirmation

OpenClaw agent finds jobs for a user. Two HITL rounds: select jobs, then confirm applications.

Use Case 2: Deployment Approval Approval

Claude Code (CLI agent) builds v2.1.0. CI/CD service needs human sign-off before production deploy.

Reviewer Decision

Approve Reject Request Changes

Options

Signed response Timeout scenario Audit trail

Use Case 3: Content Review Multi-Round Edit Cycle

CMS agent drafts a blog post. Editor reviews, requests changes, agent revises. Chain of linked review cases.

Review Rounds

1 (approve) 2 (edit + approve) 3 (edit + edit + approve)

Channel

Slack Email WhatsApp

Options

Show SSE events Show reminders

Use Case 4: Agent Deal ADL + HITL

DevOps agent negotiates infrastructure budget via ADL. Platform policy triggers human approval via HITL bridge.

Use Case 5: Input Form Structured Input

Service needs structured data from the human — form fields, validation, conditional visibility, and optional multi-step wizard flows.

Use Case 7: Inline Confirmation v0.7 Inline Submit

Email service needs confirmation before sending. Agent renders native messaging buttons — human confirms with one tap, no browser needed.

Platform

Telegram Slack Discord

Human Action

Confirm (inline) Cancel (inline) View Details (URL)

Comparison Matrix

How HITL Protocol compares to existing standards for human interaction in agent workflows.

Feature	HITL	AG-UI	A2UI	Adaptive Cards	MCP Elicit	Slack Blocks
URL-based delivery	Yes	No	No	Partial	No	No
Async (hours/days)	Yes	No	No	No	No	No
Rich forms	Yes	Yes	Yes	Partial	No	Partial
No platform lock-in	Yes	No	Yes	Yes	Partial	No
Open standard	Yes	Yes	Yes	Yes	Yes	No
CLI agent support	Yes	No	No	Partial	Yes	No
Mobile support	Yes	Partial	Partial	Yes	Partial	Yes
Crypto signing	Partial	No	No	No	No	No
Real-time updates	Yes	Yes	Yes	No	No	Yes
Multi-round chains	Yes	No	No	No	No	No
Delegation + audit	Yes	No	No	No	No	No

What HITL Borrows

json-render

Recommended UI

39 shadcn components, catalog-constrained (no XSS), state binding + actions, AI-generatable JSON specs. The default review surface format.

AG-UI (CopilotKit)

SSE Streaming

Server-Sent Events as transport option. Real-time status updates without requiring a public agent endpoint. Adapted from AG-UI's event architecture.

CHEQ (IETF)

Response Signing

Cryptographic proof that the human actually made the decision. RS256 signed responses for high-stakes financial/legal/compliance workflows.

Adaptive Cards

Input Patterns

6 years of proven input type semantics (text, number, date, toggle, choice). Mature patterns for structured data entry in agent workflows.

Key Distinction

AG-UI

Agent embedded in YOUR app (React/Angular). Real-time streaming within a frontend you control.

MCP Elicitation

Simple prompts inline in AI client. Text, number, boolean. Synchronous, blocks the tool.

HITL Protocol

Agent has NO app. Runs in terminal/Telegram. Gets human decisions from EXTERNAL services via URL.

HITL Protocol Interactive Playground