Skip to content

rotorstar/hitl-protocol

BranchesTags

Repository files navigation

HITL Protocol Logo

HITL Protocol

The Open Standard for Human Decisions in Agent Workflows

License: Apache 2.0 Version: 0.8 Open Issues PRs Welcome

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 (HTTP semantics), RFC 3339 (timestamps), RFC 6750 (auth), RFC 2119 (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 in 4 frameworks (Express, Hono, Next.js, FastAPI), HTML templates for all review types, an OpenAPI spec, and compliance 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.

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

The Solution

HITL Protocol v0.8 — Interactive Flow
▶ Try the Interactive Flow 

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 ✓"
Loading

For simple decisions (confirm/cancel, approve/reject), agents can render native messaging buttons directly in the chat — no browser switch needed:

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 ✓"
Loading

Quick Start

For Service Implementors

Return HTTP 202 with a hitl object when human input is needed:

{
  "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:

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 in 4 frameworks (Express 5, Hono, Next.js, FastAPI), HTML review templates for all 5 types, an OpenAPI 3.1 spec, JSON Schemas for validation, and compliance test suites 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 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).

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 and Example 13.

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 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 (agent.json) Agent-to-agent communication HITL complements A2A's input-required
MCP Agent tool/resource access HITL handles complex UI that MCP Elicitation can't
AG-UI (CopilotKit) Agent ↔ embedded frontend HITL serves agents with no frontend (CLI, Telegram)
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.

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
│   └── 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
│   ├── 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

HITL Protocol Interactive Playground

Try the Interactive Playground →

Versioning

The specification follows Semantic Versioning. 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 HTTP semantics (202 Accepted, 304 Not Modified, ETag, If-None-Match, Retry-After) Spec v0.8, OpenAPI, reference implementations
RFC 2119 + RFC 8174 Normative requirement language (MUST, SHOULD, MAY) Spec terminology conventions
RFC 3339 Timestamp formats (created_at, expires_at, status timestamps) JSON Schemas, OpenAPI
RFC 6750 Bearer token usage and security boundaries for API auth and inline submit auth Spec security sections, OpenAPI security schemes

Contributing

We welcome contributions from anyone building autonomous agent systems. See CONTRIBUTING.md for guidelines.

Ways to contribute:

  • Propose spec changes via issues
  • Submit implementations
  • Improve examples and documentation
  • Build reference implementations in new languages
  • Report ambiguities or edge cases

Adopters

Building with HITL Protocol? Open an issue to be listed here.

Implementation Language Transport Status
— — — Be the first to add your implementation!

License

Apache License 2.0 — see LICENSE for details.

Links

HITL Protocol is an open standard. Contributions, feedback, and implementations are welcome.

Copyright 2026 Torsten Heissler. Licensed under Apache License 2.0.

About

Human-in-the-Loop Protocol for Autonomous Agent Services — Open Standard (v0.8)

Topics

protocol auth agents human-in-the-loop ai-agents hitl proof-of-human openclaw openclaw-skills

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

0.7.2 Latest
Mar 2, 2026

Packages

 
 
 

Contributors

Languages