Hitl Protocol

HITL Protocol

The Open Standard for Human Decisions in Agent Workflows

---

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](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.

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.

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

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:

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:

{
  "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](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 (agent.json) | Agent-to-agent communication | HITL complements A2A's input-required | | MCP | Agent tool/resource access | Form-mode elicitation covers primitive input; URL-mode elicitation can deliver a HITL review_url — HITL defines what happens at that URL ([binding](docs/mcp-elicitation-binding.md)) | | 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.

• [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
│   ├─

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rotorstar](https://github.com/rotorstar)
- **Source:** [rotorstar/hitl-protocol](https://github.com/rotorstar/hitl-protocol)
- **License:** Apache-2.0
- **Homepage:** https://rotorstar.github.io/hitl-protocol/playground/index.html

Install and usage instructions live in the source repository linked above.