hitl-protocol

---

You run a website or service, and you know that AI agents will increasingly visit it on behalf of their users: searching, booking, applying, purchasing. But some decisions should not be left to an agent alone. An agent can hallucinate, misinterpret, or make the wrong call at a critical moment — cancel the wrong insurance policy, book a non-refundable trip to the wrong city, wire money to the wrong account. HITL Protocol ("Human in the Loop") is an open standard that puts you in control of these moments. Your users stay in their favorite messenger — Telegram, WhatsApp, Slack. They either tap a decision button right there or follow a link to a web page with a comfortable UI: cards, forms, buttons. No wall of text. No blind agent decisions. Honest, transparent communication in everyone's interest.

HITL Protocol is to human decisions what OAuth is to delegated access — an open standard connecting Services, Agents, and Humans.

Any website or API integrates HITL to become agent-ready: when human input is needed, return HTTP 202 with a review URL. Any autonomous agent (OpenClaw, Claude Code, Codex, Goose) handles the hitl response — forward the URL, poll for the result. The human opens the URL, gets a rich browser UI (not a chat wall of text), and makes an informed decision.

No SDK required. No UI framework mandated. Just HTTP + URL + polling.

Current contract: HITL v0.9. Default schema-package imports select v0.9; explicit /v0.8 imports preserve historical consumers. Existing HTTP/MCP demos, templates and end-to-end example JSON remain explicitly v0.8 demonstrations.

The optional Agent Access profile connects verified initiator, bounded delegation, immutable business operation, owner review and explicit execution. Its persistent reference service implements public signed catalogue reads, real OAuth/DPoP enrollment, browser review, PostgreSQL transactions and local bookings. Public identity, user authorization and human decision remain separate. Both v0.9 and the profile are drafts; broad provider acceptance is not implied.

HITL is deliberately not a frontend framework or embedded UI protocol. It standardizes the decision handoff between service, agent, and human. Optional declarative surface interoperability lives in separate profiles above the core, and review_url remains the required fallback.

Built on established Internet standards: RFC 9110 (HTTP semantics), RFC 3339 (timestamps), RFC 6750 (auth), RFC 2119 (normative language).

Who Is This For?

For Services & Websites — Add HITL endpoints to request human input from an agent. You host the review page and control which fields appear in agent-visible results. Sensitive input requires an explicit data-disclosure policy: structured review results can contain human-entered data. This repository includes local reference demonstrations in 4 frameworks (Express, Hono, Next.js, FastAPI), HTML templates, OpenAPI, and compliance tests.

For Agent Developers — Handle HTTP 202 responses. Forward the review URL to your user via any channel (CLI, Telegram, Slack, WhatsApp) — or render native messaging buttons for simple decisions (Telegram, Slack, Discord, WhatsApp, Teams). Poll for the structured result. No SDK, no UI rendering, no framework dependency. ~15 lines of code.

For Humans — Instead of typing "option 2" in a chat, you get a real web page: cards to browse, forms to fill, buttons to click, artifacts to review. Your decision is structured, validated, and auditable.

The Gap

For agents: Text channels are terrible for complex decisions. Walls of text, freeform parsing, no structured input.

For services: There's no standard way to request human input from an agent. Every agent framework has its own mechanism — or none at all. Your service either builds custom integrations or stays invisible to AI agents.

For humans: You're either excluded from agent workflows entirely, or squeezed through text-only channels.

For regulated workflows: The EU AI Act includes human-oversight requirements for high-risk systems (Article 14). Under the updated application timeline, the relevant high-risk rules apply from 2 December 2027 for Annex III systems and 2 August 2028 for Annex I product systems. A service-owned HITL case can record the structured decision and its timestamp; identifying the reviewer requires the service's authentication and authorization policy.

HITL Protocol closes this gap with one standardized flow that works across all services, all agents, and all messaging channels.

"Don't agents already have approvals?"

Yes — for their own actions. OpenClaw asks before running a dangerous command. Hermes Agent has /approve and /deny. LangGraph has interrupt(). OpenAI's Agents SDK can pause a tool call. All of these gate what the agent itself is about to do, inside that one framework.

HITL Protocol answers a different question: how does a service the agent calls request a structured decision from the human? A job board that found 5 matches. A bank that needs explicit confirmation. A deployment service that wants a plan reviewed. None of the framework-internal mechanisms reach that far — and none of them are portable across agents.

That last row matters more than it looks. Prompt-based instructions can be compacted, drowned out, or forgotten. A HITL case stores the review decision on the service side, independently of the agent's context window. The service must still enforce its separate business authorization and execution boundary; completed records a decision, not an executed action.

The same applies to MCP's newer plumbing: URL-mode elicitation and the 2026-07-28 Tasks extension (input_required + polling) standardize how an MCP server hands a pending decision to its client — inside one MCP session. HITL standardizes that moment at the open HTTP layer, for any agent with or without MCP, and defines the typed decision behind the URL.

Use both: let yo