HITL Protocol
rotorstar/hitl-protocol
Open HTTP protocol for human decisions in agent workflows, with review URLs and messenger buttons
HITL Protocol is an open specification that lets a website or API ask a human to decide before an AI agent proceeds. The service returns HTTP 202 with a review URL, the agent forwards it to the user, and polls for the structured result.
What HITL Protocol does
HITL Protocol, short for Human in the Loop, standardizes the handoff of a decision between a service, an agent and a human. When a service needs human input, it returns HTTP 202 with a review URL. The agent passes that URL to the user through a channel such as the CLI, Telegram, Slack or WhatsApp, then polls for the result. The human opens a web page with cards, forms and buttons, or taps a native button in a messenger for simple choices. No SDK is required.
The repository contains the v0.9 specification, schemas and an OpenAPI file, HTML templates, compliance tests, and local reference demonstrations in Express, Hono, Next.js and FastAPI. An optional Agent Access profile covers verified initiators, bounded delegation, owner review and explicit execution, with a persistent reference service using OAuth and DPoP. The README names OpenClaw, Claude Code, Codex and Goose as agents that can handle the hitl response, and the repository is tagged hermes and hermes-agent.
Key features
- HTTP 202 plus review URL flow with polling for the structured result
- Review pages with cards, forms and buttons instead of a wall of chat text
- Optional native messenger buttons for Telegram, Slack, Discord, WhatsApp and Teams
- Reference demos in Express, Hono, Next.js and FastAPI
- JSON schemas, OpenAPI file and compliance tests
- Optional Agent Access profile with OAuth and DPoP enrollment
When to use it
- Making an agent ask a person before cancelling a policy or paying
- Adding an approval page to a booking or application API
- Sending a decision request to a user's Telegram chat and reading back the answer
Who it is for: Service owners who want agents to hand off critical decisions to a human, and agent developers who handle those handoffs.
How it fits with Hermes Agent
An agent-agnostic protocol. The repository is tagged hermes and hermes-agent, but the README names OpenClaw, Claude Code, Codex and Goose when describing agents that handle the response.
Note: The README says HITL v0.9 and the Agent Access profile are drafts and that broad provider acceptance is not implied.
FAQ
What is HITL Protocol?
HITL Protocol is an open HTTP standard for human decisions in AI agent workflows. A service returns a review URL when human input is needed, and the agent forwards it and polls for the answer.
Does HITL Protocol work with Hermes Agent?
It is agent-agnostic, so any agent that can follow an HTTP 202 response and poll a URL can use it. The repository is tagged hermes-agent, but the README does not give Hermes-specific steps.
Is HITL Protocol free and open source?
Yes. The repository is released under the Apache-2.0 license.
Similar dev tools for Hermes Agent
All dev toolsSwift package that embeds Hermes Agent, CPython and an iSH shell inside an iOS app
lodado Playwright Spec for AI AgentCLI that has an AI agent judge a live staging page against your existing Playwright specs
barkley-assistant CaduceusRust daemon and Hermes plugin that reviews pull requests and turns labeled issues into PRs
aRYmK13 Hermes Session ExporterExport Hermes Agent sessions to Markdown, HTML or normalized JSON, with a TUI browser and web panel
prevu-cloud PrevuOpen-source CLI and agent skills for giving coding agents preview and staging environments
a5c-ai agent-muxTypeScript SDK and amux CLI for driving many coding agents, Hermes included, through one contract
Related guides: How to install Hermes Agent · Run multiple Hermes agents with profiles