HITL Protocol
The Open Standard for Human Decisions in Agent Workflows
-orange.svg)
---
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 authentication — 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.**
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](https://www.rfc-editor.org/rfc/rfc9110) (HTTP semantics), [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) (timestamps), [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) (auth), [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) (normative language).
## Who Is This For?
**For Services & Websites** — Add HITL endpoints to make your service accessible to any autonomous agent. You host the review page, you control the UI, you own the data. Sensitive information stays in the browser — never passes through the agent. This repository includes [reference implementations](implementations/reference-service/) in 4 frameworks (Express, Hono, Next.js, FastAPI), [HTML templates](templates/) for all review types, an [OpenAPI spec](schemas/openapi.yaml), and [compliance tests](tests/) — everything needed to integrate.
**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's human-oversight requirements for high-risk systems ([Article 14](https://artificialintelligenceact.eu/article/14/)) apply from August 2026 — oversight has to be demonstrable, not promised. A HITL case is auditable protocol state: who decided what, when, with a structured, validated result.
**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.
| | Framework approvals (OpenClaw, Hermes, LangGraph, …) | HITL Protocol |
|---|---|---|
| **Who asks?** | The agent, about its own tool call | The service, about its own domain decision |
| **Decision shape** | Approve / deny | 5 typed review flows with structured, validated results |
| **UI** | Chat prompt | Service-hosted review page + native buttons |
| **Portability** | Locked to one framework | Any agent, plain HTTP |
| **Where the state lives** | Agent context / prompt | Service-side protocol state |
That last row matters more than it looks. In February 2026, a Meta director watched an agent delete 200+ emails after her *"don't action until I tell you"* instruction was silently lost to context compaction. Prompt-based approvals can be compacted, drowned out, or forgotten. A HITL case is protocol state on the service side — the action does not happen until a structured decision arrives, no matter what the agent's context window does.
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 your agent runtime gate its own dangerous actions, and let services request human decisions via HITL. See the [approval-mechanism landscape](docs/feature-matrix.md#approval-mechanism-landscape) for the full comparison.
## The Solution
▶ Try the Interactive Flow
```mermaid
sequenceDiagram
actor H as Human
participant A as Agent
participant S as Service
participant P as Review Page
H->>A: "Find me jobs in Berlin"
A->>S: POST /api/search
S-->>A: HTTP 202 + hitl object
A->>H: "Found 5 jobs. Review here: [URL]"
H->>P: Opens URL in browser
P-->>H: Rich UI (cards, forms, buttons)
H->>P: Makes selection, submits
loop Agent polls
A->>S: GET {poll_url}
S-->>A: {status: "completed", result: {...}}
end
A->>H: "Applied to 2 selected jobs ✓"
```
For simple decisions (confirm/cancel, approve/reject), agents can render **native messaging buttons** directly in the chat — no browser switch needed:
```mermaid
sequenceDiagram
actor H as Human
participant A as Agent (Telegram Bot)
participant S as Service
H->>A: "Send my application emails"
A->>S: POST /api/send
S-->>A: HTTP 202 + hitl (incl. submit_url)
A->>H: Native buttons: [Confirm] [Cancel] [Details →]
H->>A: Taps [Confirm]
A->>S: POST {submit_url} {action: "confirm"}
S-->>A: 200 OK {status: "completed"}
A->>H: "Confirmed — 3 emails sent ✓"
```
## Quick Start
### For Service Implementors
Return HTTP 202 with a `hitl` object when human input is needed:
```json
{
"status": "human_input_required",
"message": "5 matching jobs found. Please select which ones to apply for.",
"hitl": {
"spec_version": "0.8",
"case_id": "review_abc123",
"review_url": "https://yourservice.com/review/abc123?token=K7xR2mN4pQ8sT1vW3xY5zA9bC...",
"poll_url": "https://api.yourservice.com/v1/reviews/abc123/status",
"type": "selection",
"prompt": "Select which jobs to apply for",
"timeout": "24h",
"default_action": "skip",
"created_at": "2026-02-22T10:00:00Z",
"expires_at": "2026-02-23T10:00:00Z"
}
}
```
### For Agent Implementors
Handle HTTP 202 responses — that's it:
```python
response = httpx.post("https://api.jobboard.com/search", json=query)
if response.status_code == 202:
hitl = response.json()["hitl"]
# v0.8: Check for inline submit support and optional proof preflight
if "submit_url" in hitl and "submit_token" in hitl:
if (
"verification_policy" in hitl
and "inline_submit" in hitl["verification_policy"]["required_for"]
and not agent_can_satisfy_proof(hitl["verification_policy"])
):
send_to_user(f"{hitl['prompt']}\n{hitl['review_url']}")
else:
# Render native buttons in messaging platform (Telegram, Slack, Discord)
send_inline_buttons(hitl["prompt"], hitl["inline_actions"], hitl["review_url"])
# When human taps button → POST to submit_url (see Agent Integration Guide)
else:
# Standard flow: forward URL to human
send_to_user(f"{hitl['prompt']}\n{hitl['review_url']}")
# Poll for result (standard flow or fallback)
while True:
poll = httpx.get(hitl["poll_url"], headers=auth).json()
if poll["status"] == "completed":
result = poll["result"] # structured data
break
if poll["status"] in ("expired", "cancelled"):
break
time.sleep(30)
```
No SDK. No library. No UI rendering. Just HTTP + URL forwarding + polling.
**Ready to integrate?** This repository provides everything you need: [reference implementations](implementations/reference-service/) in 4 frameworks (Express 5, Hono, Next.js, FastAPI), [HTML review templates](templates/) for all 5 types, an [OpenAPI 3.1 spec](schemas/openapi.yaml), [JSON Schemas](schemas/) for validation, and [compliance test suites](tests/) in Node.js and Python.
## Five Review Types
| Type | Actions | Multi-round | Form Fields | Use Case |
|------|---------|:-----------:|:-----------:|----------|
| **Approval** | approve, edit, reject | Yes | No | Artifact review (CV, deployment plan) |
| **Selection** | select | No | No | Choose from options (job listings) |
| **Input** | submit | No | Yes | Structured data entry (salary, dates) |
| **Confirmation** | confirm, cancel | No | No | Irreversible action gate (send emails) |
| **Escalation** | retry, skip, abort | No | No | Error recovery (deployment failed) |
**Input forms** support structured field definitions via `context.form` — including typed fields (text, number, date, select, range, ...), validation rules, conditional visibility, and multi-step wizard flows. See [Spec Section 10.3](spec/v0.8/hitl-protocol.md#103-input) for details.
**Multi-round workflows:** Approval reviews support iterative cycles — submit, request edits, resubmit, approve. Agents can chain multiple HITL interactions for complex multi-step processes (see `previous_case_id` / `next_case_id` in the [spec](spec/v0.8/hitl-protocol.md)).
**Quality improvement signals:** Services can include `improvement_suggestions` in successful responses — structured hints agents act on by asking the human targeted questions and re-submitting enriched data. The agent always shares the primary result first, then optionally offers up to 2 improvement cycles. See [Agent Checklist — Quality Improvement Loop](agents/checklist.md#enhanced-quality-improvement-loop) and [Example 13](examples/13-quality-improvement-loop.json).
## Three Transport Modes
| Transport | Agent needs public endpoint? | Real-time? | Complexity |
|-----------|:---:|:---:|:---:|
| **Polling** (default) | No | No | Minimal |
| **SSE** (optional) | No | Yes | Low |
| **Callback** (optional) | Yes | Yes | Medium |
Polling is the baseline. Every HITL-compliant service MUST support it. SSE and callbacks are optional enhancements.
## Channel-Native Inline Actions (v0.8)
For simple decisions, agents can render **native messaging buttons** instead of sending a URL. The human taps a button directly in the chat — no browser switch needed.
**How it works:** The service includes `submit_url` + `submit_token` in the HITL object. The agent detects these fields, preflights any `verification_policy` declared for `inline_submit`, and renders platform-native buttons only if the inline path is both UI-compatible and policy-satisfiable. When the human taps a button, the agent POSTs the action to `submit_url`.
| Review type | Inline possible? | Reason |
|-------------|:----------------:|--------|
| **Confirmation** | Yes | 2 buttons: Confirm / Cancel |
| **Escalation** | Yes | 3 buttons: Retry / Skip / Abort |
| **Approval** (simple) | Yes | 2 buttons: Approve / Reject |
| **Selection** | URL only | Needs list/cards UI |
| **Input** | URL only | Needs form fields |
Always include a URL fallback button (e.g. "Details →") linking to `review_url` — the human can always switch to the full review page. See [Agent Integration Guide](skills/references/agent-integration.md) for platform-specific rendering patterns (Telegram, Slack, Discord, WhatsApp, Teams).
## Verification Evidence (v0.8)
v0.8 adds an optional verification layer for Proof of Human flows:
- `verification_policy` lets the service declare when proof is optional, required, or step-up-only.
- `verification_evidence` can be relayed only on agent-authenticated `submit_url` requests.
- `submission_context.verification_result` returns only normalized, provider-agnostic results to the polling agent.
- Browser review remains the preferred step-up path for high-stakes actions, and browser-path verification is always service-hosted.
The normative v0.8 core standardizes only `proof_of_human`. Identity, authorization, and agent binding remain separate concerns.
## Agent Auth Composition
HITL transport auth and external agent-auth systems solve different problems:
- HITL covers `review_url`, `poll_url`, optional `submit_url`, and the human decision transport itself.
- External agent-auth/control-plane systems cover per-agent identity, capability grants, escalation, and revocation.
The current OpenAPI auth model is sufficient for HITL transport boundaries. If a service also binds cases to an agent principal or host, it should advertise that through discovery metadata such as `supports_agent_binding` and external auth/profile documentation.
## Protocol Standards Landscape
HITL Protocol fills a gap no existing standard addresses:
| Standard | What it solves | HITL Protocol's role |
|----------|---------------|---------------------|
| **SKILL.md** | How agents discover skills | HITL extends SKILL.md metadata |
| **A2A** (v1.0, Linux Foundation) | Agent-to-agent communication | HITL complements A2A's `input-required` — A2A signals *that* input is needed, HITL defines the review page and typed result |
| **MCP** | Agent tool/resource access | URL-mode elicitation delivers a HITL `review_url`; the 2026-07-28 revision adds async human-approval plumbing *inside* MCP (MRTR, Tasks `input_required`) — HITL standardizes the same handoff on the open HTTP layer, for any agent, and defines the typed decision at the URL ([binding](docs/mcp-elicitation-binding.md)) |
| **AG-UI** (CopilotKit) | Agent ↔ embedded frontend | HITL serves agents with no frontend (CLI, Telegram) |
| **AP2 / ACP / x402** | Payment authorization & agentic checkout | Domain-locked to commerce; HITL covers the same "human authorizes the critical action" moment for **any** domain, with the service hosting the review UI |
| **CHEQ** (IETF drafts, expired) | Human confirmation of agent decisions | Closest prior art: `draft-rosenberg-cheq-00` (07/2025) used 202 + URI package + polling; its successor pivoted to signed objects carried over MCP/A2A and both drafts expired without WG adoption — HITL is the active standard for this pattern at the HTTP layer ([details](docs/feature-matrix.md#adjacent-standards-landscape-july-2026)) |
| **OAuth 2.0** | User authentication | HITL follows the same three-party pattern |
## Optional Surface Interop Profiles
The HITL core stays intentionally small: service-hosted review page, signed URL, polling, optional inline submit. If a client also wants to render declarative UI inline, use an optional profile rather than extending the core `hitl` object with renderer-specific payloads.
- [Surface Interop Profile v0.1](profiles/surface-interop/v0.1/README.md) defines a portable wrapper for declarative surfaces
- [Feature Matrix](docs/feature-matrix.md) compares HITL core, `json-render`, and A2UI with evidence
- [Flow Verification](docs/flow-verification.md) checks Mermaid flows against real HITL semantics and fallback rules
## Repository Structure
```
hitl-protocol/
├── README.md ← You are here
├── SKILL.md ← Agent skill (protocol knowledge)
├── LICENSE ← Apache 2.0
├── CONTRIBUTING.md ← How to contribute
├── CHANGELOG.md ← Version history
├── SECURITY.md ← Security reporting
│
├── spec/v0.8/
│ └── hitl-protocol.md ← Full specification (normative)
│
├── schemas/
│ ├── hitl-object.schema.json ← JSON Schema: HITL object
│ ├── poll-response.schema.json ← JSON Schema: Poll response
│ ├── form-field.schema.json ← JSON Schema: Form field definitions
│ ├── discovery-response.schema.json ← JSON Schema: discovery response
│ └── openapi.yaml ← OpenAPI 3.1 spec (all endpoints)
│
├── examples/ ← 16 end-to-end example flows
│
├── profiles/
│ ├── README.md ← Optional interoperability profiles
│ └── surface-interop/
│ └── v0.1/
│ ├── README.md ← Surface interop profile spec
│ └── surface-interop-profile.schema.json
│
├── templates/ ← Review page HTML templates
│ ├── approval.html ← Approval review page
│ ├── selection.html ← Selection review page
│ ├── input.html ← Input form (multi-step wizard)
│ ├── confirmation.html ← Confirmation review page
│ └── escalation.html ← Escalation review page
│
├── implementations/
│ ├── README.md ← Known implementations
│ ├── mcp-server/ ← MCP URL mode elicitation demo
│ └── reference-service/ ← Reference implementations
│ ├── express/ ← Express 5 (Node.js)
│ ├── hono/ ← Hono (Edge/Deno/Bun)
│ ├── nextjs/ ← Next.js App Router (TypeScript)
│ └── python/ ← FastAPI (Python)
│
├── docs/
│ ├── quick-start.md ← Quick Start Guide (5 frameworks)
│ ├── sdk-guide.md ← SDK Design Guide
│ ├── mcp-elicitation-binding.md ← HITL via MCP URL mode elicitation
│ ├── feature-matrix.md ← Evidence-backed comparison matrix
│ └── flow-verification.md ← Mermaid flow verification
│
├── tests/ ← Compliance test suites
│ ├── node/ ← Vitest (schema + state machine)
│ └── python/ ← pytest (schema + state machine)
│
├── agents/
│ └── checklist.md ← Agent implementation checklist
│
├── skills/
│ ├── README.md ← Skill publishing guide
│ └── references/ ← Detailed integration guides
│ ├── service-integration.md ← For service builders
│ └── agent-integration.md ← For agent developers
│
├── playground/
│ └── index.html ← Interactive playground
│
└── .github/ ← Issue + PR templates
```
## Interactive Playground
Try the Interactive Playground →
## Versioning
The specification follows [Semantic Versioning](https://semver.org/). Breaking changes increment the major version. The `spec_version` field in all HITL objects enables forward compatibility.
| Version | Status | Date |
|---------|--------|------|
| 0.8 | Draft | 2026-03-26 |
| 0.7 | Draft | 2026-02-23 |
| 0.6 | Draft | 2026-02-23 |
| 0.5 | Draft | 2026-02-22 |
## RFC Alignment
HITL Protocol aligns with established Internet standards where applicable:
| RFC | Scope in HITL Protocol | Where Implemented |
|-----|------------------------|-------------------|
| **[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110)** | HTTP semantics (`202 Accepted`, `304 Not Modified`, `ETag`, `If-None-Match`, `Retry-After`) | [Spec v0.8](spec/v0.8/hitl-protocol.md), [OpenAPI](schemas/openapi.yaml), reference implementations |
| **[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)** + **[RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)** | Normative requirement language (`MUST`, `SHOULD`, `MAY`) | [Spec terminology conventions](spec/v0.8/hitl-protocol.md#4-terminology) |
| **[RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)** | Timestamp formats (`created_at`, `expires_at`, status timestamps) | [JSON Schemas](schemas/), [OpenAPI](schemas/openapi.yaml) |
| **[RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)** | Bearer token usage and security boundaries for API auth and inline submit auth | [Spec security sections](spec/v0.8/hitl-protocol.md), [OpenAPI security schemes](schemas/openapi.yaml) |
## Contributing
We welcome contributions from anyone building autonomous agent systems. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
**Ways to contribute:**
- Propose spec changes via [issues](https://github.com/rotorstar/hitl-protocol/issues)
- Submit implementations
- Improve examples and documentation
- Build reference implementations in new languages
- Report ambiguities or edge cases
## Adopters & Ecosystem
The [HITL Protocol skill on ClawHub](https://clawhub.ai/skills/hitl-protocol) (`openclaw skills install hitl-protocol`) teaches OpenClaw agents the protocol — **850+ installs and counting**.
Building with HITL Protocol? [Open an issue](https://github.com/rotorstar/hitl-protocol/issues/new?template=implementation-report.md) to be listed here.
| Implementation | Role | Spec | Review Types | Transport |
|----------------|------|:----:|--------------|-----------|
| [Etienne](https://github.com/bullorosso/etienne) — agent harness integration layer (Claude Agent SDK, OpenCode, Codex) | Agent harness | 0.8 | Approval, Selection, Input, Confirmation | Polling |
| *Your implementation here* | | | | |
## License
Apache License 2.0 — see [LICENSE](LICENSE) for details.
## Links
- [Full Specification (v0.8)](spec/v0.8/hitl-protocol.md)
- [Quick Start Guide](docs/quick-start.md) — Get started in 5 minutes
- [OpenAPI Spec](schemas/openapi.yaml) — All endpoints documented
- [JSON Schemas](schemas/) — HITL object, poll response, form field, discovery response
- [Review Page Templates](templates/) — HTML templates for all 5 review types
- [Reference Implementations](implementations/reference-service/) — Express, Hono, Next.js, FastAPI
- [MCP Server Demo](implementations/mcp-server/) — HITL via MCP URL mode elicitation (works in Claude Code)
- [MCP Elicitation Binding](docs/mcp-elicitation-binding.md) — Informative binding for MCP delivery
- [Examples](examples/) — 16 end-to-end flows (including proof-of-human inline submit, step-up fallback, and browser-verified approval)
- [Compliance Tests](tests/) — Schema + state machine tests (Node.js + Python)
- [Interactive Playground](playground/)
- [Agent Implementation Checklist](agents/checklist.md)
- [Agent Skill (SKILL.md)](SKILL.md) — Teach agents the HITL Protocol
- [SDK Design Guide](docs/sdk-guide.md) — Build a community SDK
- [Surface Interop Profile](profiles/surface-interop/v0.1/README.md) — Optional declarative surface profile
- [Feature Matrix](docs/feature-matrix.md) — Evidence-backed comparison
- [Flow Verification](docs/flow-verification.md) — Mermaid flows checked against HITL semantics
---
*HITL Protocol is an open standard. Contributions, feedback, and implementations are welcome.*
*Copyright 2026 Torsten Heissler. Licensed under Apache License 2.0.*