{
  "schemaVersion": "1.0",
  "item": {
    "slug": "hitl-protocol",
    "name": "HITL Protocol — Workflows and Human Decisions for Autonomous Agents",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/rotorstar/hitl-protocol",
    "canonicalUrl": "https://clawhub.ai/rotorstar/hitl-protocol",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/hitl-protocol",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=hitl-protocol",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "references/agent-integration.md",
      "references/service-integration.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/hitl-protocol"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/hitl-protocol",
    "agentPageUrl": "https://openagent3.xyz/skills/hitl-protocol/agent",
    "manifestUrl": "https://openagent3.xyz/skills/hitl-protocol/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/hitl-protocol/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "HITL Protocol",
        "body": "AI agents increasingly visit websites and services on behalf of their users: searching, booking, applying, purchasing. But some decisions are too important to leave 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 ensures humans stay in control of these moments. The user stays in their favorite messenger — Telegram, WhatsApp, Slack — and either taps a decision button right there or follows a link to a web page with a comfortable UI: cards, forms, buttons. No wall of text. No blind agent decisions. When you encounter a HITL response, tell your user that a decision is needed that should not be made by an agent alone — forward the prompt and make it easy to act: show the review link or render action buttons.\n\nHITL Protocol is to human decisions what OAuth is to authentication — an open standard connecting Services, Agents, and Humans. When a service needs human input, it returns HTTP 202 with a review URL. The agent forwards the URL to the human. The human opens it in a browser, gets a rich UI, and makes an informed decision. The agent polls for the structured result and continues.\n\nFor simple decisions (confirm/cancel, approve/reject), agents can render native messaging buttons directly in Telegram, Slack, Discord, WhatsApp, or Teams — no browser needed. The service opts in via submit_url.\n\nNo SDK required. No UI framework mandated. Just HTTP + URL + polling.\n\nInteractive Playground — try all review types, transports, and inline actions live in your browser."
      },
      {
        "title": "Who Are You?",
        "body": "Your roleYou want to...ReadService/website builderAdd HITL endpoints to your API so agents can request human inputService Integration GuideAgent developerHandle HTTP 202 + HITL responses from servicesAgent Integration GuideBoth / LearningUnderstand the full protocolContinue reading below"
      },
      {
        "title": "The Flow",
        "body": "Standard flow (all review types):\n1. Human → Agent:    \"Find me jobs in Berlin\"\n2. Agent → Service:  POST /api/search {query: \"Senior Dev Berlin\"}\n3. Service → Agent:  HTTP 202 + hitl object (review_url, poll_url, type, prompt)\n4. Agent → Human:    \"Found 5 jobs. Review here: {review_url}\"\n5. Human → Browser:  Opens review_url → rich UI (cards, forms, buttons)\n6. Human → Service:  Makes selection, clicks Submit\n7. Agent → Service:  GET {poll_url} → {status: \"completed\", result: {action, data}}\n8. Agent → Human:    \"Applied to 2 selected jobs.\"\n\nInline flow (v0.7 — simple decisions only, when submit_url present):\n1. Human → Agent:    \"Send my application emails\"\n2. Agent → Service:  POST /api/send {emails: [...]}\n3. Service → Agent:  HTTP 202 + hitl object (incl. submit_url, submit_token, inline_actions)\n4. Agent → Human:    Native buttons in chat: [Confirm] [Cancel] [Details →]\n5. Human → Agent:    Taps [Confirm] in chat\n6. Agent → Service:  POST {submit_url} {action: \"confirm\", submitted_via: \"telegram\"}\n7. Service → Agent:  200 OK {status: \"completed\"}\n8. Agent → Human:    Updates message: \"Confirmed — 3 emails sent.\"\n\nThe agent never renders UI. The service hosts the review page. Sensitive data stays in the browser — never passes through the agent. The inline flow is an optional shortcut for simple decisions."
      },
      {
        "title": "Feature Matrix",
        "body": "FeatureDetailsReview typesapproval, selection, input, confirmation, escalationForm field typestext, textarea, number, date, email, url, boolean, select, multiselect, range, custom x-*TransportPolling (required), SSE (optional), Callback/Webhook (optional)Inline submitsubmit_url + native messaging buttons (Telegram, Slack, Discord, WhatsApp, Teams) — service opt-inStatespending → opened → in_progress → completed / expired / cancelledSecurityOpaque tokens (43 chars, base64url, 256-bit entropy), SHA-256 hash storage, timing-safe comparison, HTTPS onlyMulti-roundprevious_case_id / next_case_id for iterative edit cycles (Approval type)FormsSingle-step fields, multi-step wizard, conditional visibility, validation rules, progress trackingTimeoutsISO 8601 duration, default_action: skip / approve / reject / abortDiscovery.well-known/hitl.json, SKILL.md metadata.hitl extensionRemindersreminder_at timestamps, review.reminder SSE eventRate limiting60 requests/min per case on poll endpoint, Retry-After header"
      },
      {
        "title": "Five Review Types",
        "body": "TypeActionsMulti-roundForm fieldsUse caseApprovalapprove, edit, rejectYesNoArtifact review (CV, email, deployment plan)SelectionselectNoNoChoose from options (job listings, targets)InputsubmitNoYesStructured data entry (salary, dates, preferences)Confirmationconfirm, cancelNoNoIrreversible action gate (send emails, deploy)Escalationretry, skip, abortNoNoError recovery (deployment failed, API error)"
      },
      {
        "title": "HITL Object (HTTP 202 Response Body)",
        "body": "When a service needs human input, it returns HTTP 202 with this structure:\n\n{\n  \"status\": \"human_input_required\",\n  \"message\": \"5 matching jobs found. Please select which ones to apply for.\",\n  \"hitl\": {\n    \"spec_version\": \"0.7\",\n    \"case_id\": \"review_abc123\",\n    \"review_url\": \"https://service.example.com/review/abc123?token=K7xR2mN4pQ...\",\n    \"poll_url\": \"https://api.service.example.com/v1/reviews/abc123/status\",\n    \"type\": \"selection\",\n    \"prompt\": \"Select which jobs to apply for\",\n    \"timeout\": \"24h\",\n    \"default_action\": \"skip\",\n    \"created_at\": \"2026-02-22T10:00:00Z\",\n    \"expires_at\": \"2026-02-23T10:00:00Z\",\n    \"context\": {\n      \"total_options\": 5,\n      \"query\": \"Senior Dev Berlin\"\n    }\n  }\n}"
      },
      {
        "title": "Required Fields",
        "body": "FieldTypeDescriptionspec_version\"0.7\"Protocol versioncase_idstringUnique, URL-safe identifier (pattern: review_{random})review_urlURLHTTPS URL to review page with opaque bearer tokenpoll_urlURLStatus polling endpointtypeenumapproval / selection / input / confirmation / escalation / x-*promptstringWhat the human needs to decide (max 500 chars)created_atdatetimeISO 8601 creation timestampexpires_atdatetimeISO 8601 expiration timestamp"
      },
      {
        "title": "Optional Fields",
        "body": "FieldTypeDescriptiontimeoutdurationHow long the review stays open (24h, PT24H, P7D)default_actionenumskip / approve / reject / abort — action on expirycallback_urlURL / nullEchoed callback URL if agent provided oneevents_urlURLSSE endpoint for real-time status eventscontextobjectArbitrary data for the review page (not processed by agent)reminder_atdatetime / datetime[]When to re-send the review URLprevious_case_idstringLinks to prior case in multi-round chainsurfaceobjectUI format declaration (format, version)submit_urlURLAgent-submit endpoint for channel-native inline buttons (v0.7)submit_tokenstringBearer token for submit_url authentication (required if submit_url set)inline_actionsstring[]Actions permitted via submit_url (e.g. [\"confirm\", \"cancel\"]). If absent, all actions for the type are allowed."
      },
      {
        "title": "Poll Response (Completed)",
        "body": "{\n  \"status\": \"completed\",\n  \"case_id\": \"review_abc123\",\n  \"completed_at\": \"2026-02-22T10:15:00Z\",\n  \"result\": {\n    \"action\": \"select\",\n    \"data\": {\n      \"selected_jobs\": [\"job-123\", \"job-456\"],\n      \"note\": \"Only remote positions\"\n    }\n  }\n}\n\nThe result object is present only when status is \"completed\". It always contains action (string) and data (object with type-dependent content)."
      },
      {
        "title": "Poll Response Statuses",
        "body": "StatusTerminalDescriptionKey fieldspendingNoCase created, human hasn't opened URLexpires_atopenedNoHuman opened the review URLopened_atin_progressNoHuman is interacting with the formprogress (optional)completedYesHuman submitted responseresult, completed_at, responded_byexpiredYesTimeout reachedexpired_at, default_actioncancelledYesHuman clicked cancelcancelled_at, reason"
      },
      {
        "title": "State Machine",
        "body": "+---------------------------------------------+\n            |                                             v\n[created] -> pending -> opened -> in_progress -> completed [terminal]\n               |         |          |\n               |         |          +---------> cancelled  [terminal]\n               |         |\n               |         +--> completed     [terminal]\n               |         +--> expired       [terminal]\n               |         +--> cancelled     [terminal]\n               |\n               +----------> expired          [terminal]\n               +----------> cancelled        [terminal]\n\nTerminal states (completed, expired, cancelled) are immutable — no further transitions."
      },
      {
        "title": "For Services: Quick Start",
        "body": "Return HTTP 202 when human input is needed:\n\n// Express / Hono / any HTTP framework\napp.post('/api/search', async (req, res) => {\n  const results = await searchJobs(req.body.query);\n\n  // Create review case with opaque token\n  const caseId = `review_${crypto.randomBytes(16).toString('hex')}`;\n  const token = crypto.randomBytes(32).toString('base64url'); // 43 chars\n  const tokenHash = crypto.createHash('sha256').update(token).digest('hex');\n\n  store.set(caseId, {\n    status: 'pending',\n    tokenHash,\n    results,\n    created_at: new Date().toISOString(),\n    expires_at: new Date(Date.now() + 86400000).toISOString(),\n  });\n\n  res.status(202).json({\n    status: 'human_input_required',\n    message: `${results.length} jobs found. Please select which ones to apply for.`,\n    hitl: {\n      spec_version: '0.6',\n      case_id: caseId,\n      review_url: `https://yourservice.com/review/${caseId}?token=${token}`,\n      poll_url: `https://api.yourservice.com/v1/reviews/${caseId}/status`,\n      type: 'selection',\n      prompt: 'Select which jobs to apply for',\n      timeout: '24h',\n      default_action: 'skip',\n      created_at: store.get(caseId).created_at,\n      expires_at: store.get(caseId).expires_at,\n    },\n  });\n});\n\nYou also need: a review page (any web framework), a poll endpoint (GET /reviews/:caseId/status), and a response endpoint (POST /reviews/:caseId/respond). See Service Integration Guide for full details."
      },
      {
        "title": "For Agents: Quick Start",
        "body": "Handle HTTP 202 responses — ~15 lines:\n\nimport time, httpx\n\nresponse = httpx.post(\"https://api.jobboard.com/search\", json=query)\n\nif response.status_code == 202:\n    hitl = response.json()[\"hitl\"]\n\n    # v0.7: Check for inline submit support\n    if \"submit_url\" in hitl and \"submit_token\" in hitl:\n        # Render native buttons in messaging platform (e.g. Telegram, Slack)\n        send_inline_buttons(hitl[\"prompt\"], hitl[\"inline_actions\"], hitl[\"review_url\"])\n        # When human taps button → POST to submit_url (see Agent Integration Guide)\n    else:\n        # Standard flow: forward URL to human\n        send_to_user(f\"{hitl['prompt']}\\n{hitl['review_url']}\")\n\n    # Poll for result (standard flow or fallback)\n    while True:\n        time.sleep(30)\n        poll = httpx.get(hitl[\"poll_url\"], headers=auth).json()\n\n        if poll[\"status\"] == \"completed\":\n            result = poll[\"result\"]  # {action: \"select\", data: {...}}\n            break\n        if poll[\"status\"] in (\"expired\", \"cancelled\"):\n            break\n\nNo SDK. No UI rendering. Just HTTP + URL forwarding + polling. See Agent Integration Guide for inline submit, SSE, callbacks, multi-round, and edge cases."
      },
      {
        "title": "Three Transport Modes",
        "body": "TransportAgent needs public endpoint?Real-time?ComplexityPolling (default)NoNoMinimalSSE (optional)NoYesLowCallback (optional)YesYesMedium\n\nPolling is the baseline — every HITL-compliant service MUST support it. SSE and callbacks are optional enhancements."
      },
      {
        "title": "Channel-Native Inline Actions (v0.7)",
        "body": "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.\n\nHow it works: The service includes submit_url + submit_token in the HITL object. The agent detects these fields and renders platform-native buttons. When the human taps a button, the agent POSTs the action to submit_url. The messaging platform is passive — it renders whatever the agent sends. No messenger auto-detects HITL support.\n\nWhen to use inline buttons:\n\nReview typeInline possible?ReasonConfirmationYes2 buttons: Confirm / CancelEscalationYes3 buttons: Retry / Skip / AbortApproval (simple)Yes2 buttons: Approve / Reject (without edit)Approval (with edit)URL onlyEdit requires rich UISelectionURL onlyNeeds list/cards UIInputURL onlyNeeds form fields\n\nAlways include a URL fallback button (e.g. \"Details →\") linking to review_url — the human can always switch to the full review page.\n\nPlatform requirements: The agent must be a platform bot (Telegram Bot via BotFather, Slack App, Discord Bot, WhatsApp Business API, Teams Bot) to send native buttons. See Agent Integration Guide for platform-specific rendering patterns."
      },
      {
        "title": "Non-Goals",
        "body": "Does NOT render review UI — the service hosts and renders the review page. The agent is a messenger.\nDoes NOT define the review page framework — any web technology works (React, plain HTML, etc.).\nDoes NOT replace OAuth — HITL is for decisions, not authentication.\nDoes NOT submit on behalf of the human — unless the human explicitly triggers an inline action button in a messaging platform (v0.7 submit_url)."
      },
      {
        "title": "SKILL.md Extension for Services",
        "body": "Services that use HITL can declare support in their own SKILL.md frontmatter:\n\nmetadata:\n  hitl:\n    supported: true\n    types: [selection, confirmation]\n    supports_inline_submit: true\n    review_base_url: \"https://yourservice.com/review\"\n    timeout_default: \"24h\"\n    info: \"May ask user to select preferred jobs or confirm applications.\"\n\nSee spec Section 12 for the full field reference."
      },
      {
        "title": "Best Practice: Enforce HITL Choice",
        "body": "Problem: Agents tend to take the efficient path and silently skip HITL — defaulting to no human review. Even though the protocol says agents MUST NOT ignore HTTP 202, nothing prevents an agent from never sending requests that trigger HITL in the first place.\n\nSolution: Force agents to make an explicit choice per request. Add prefer_hitl and skip_hitl flags to your API and reject requests that provide neither.\n\nDeclare this in your SKILL.md:\n\nmetadata:\n  hitl:\n    supported: true\n    hitl_required: true\n    types: [selection, confirmation]\n    info: \"HITL is required. You MUST send prefer_hitl: true or skip_hitl: true.\"\n\nAdd an Agent Guidelines section to your SKILL.md body:\n\n## Agent Guidelines\n\nHITL is required for this service. Every request MUST include exactly one of:\n\n| Parameter | Type | Effect |\n|-----------|------|--------|\n| `prefer_hitl` | boolean | `true` → human reviews via HITL (HTTP 202) |\n| `skip_hitl` | boolean | `true` → direct execution, no human review (HTTP 201) |\n\nYou MUST choose one. Omitting both returns 400 `HITL_CHOICE_REQUIRED`.\nSending both returns 400 validation error.\n\n### Example: With HITL\n\nPOST /api/search\n{\"query\": \"Senior Dev Berlin\", \"prefer_hitl\": true}\n\n→ 202 + hitl object (human reviews results)\n\n### Example: Without HITL\n\nPOST /api/search\n{\"query\": \"Senior Dev Berlin\", \"skip_hitl\": true}\n\n→ 201 {\"results\": [...], \"hitl_skipped\": true}\n\n### Example: Missing choice\n\nPOST /api/search\n{\"query\": \"Senior Dev Berlin\"}\n\n→ 400 {\"error\": \"HITL_CHOICE_REQUIRED\", \"message\": \"You must send prefer_hitl or skip_hitl.\"}\n\nSee Service Integration Guide — Enforcing HITL Choice for validation gate implementation."
      },
      {
        "title": "Optional: Quality Improvement Signal",
        "body": "Services can include improvement_suggestions in successful (non-202) responses to give agents structured feedback they can act on — without requiring a new HITL flow.\n\nDeclare support in your SKILL.md:\n\nmetadata:\n  hitl:\n    supported: true\n    supports_improvement_suggestions: true\n    info: \"Returns improvement_suggestions in 201 responses. Agents may offer up to 2 improvement cycles.\"\n\nSuggestion object schema:\n\nFieldTypeDescriptionfieldstringWhich data field can be improvedissuestringWhat is missing or suboptimalagent_actionstringExact question/action for the agent to takeimpactstringHuman-readable benefit (e.g. \"+25 quality points\")priority\"high\" / \"medium\" / \"low\"Order of importance\n\nAgent behavior:\n\nAlways share the primary result first\nOffer up to 2 improvement cycles — one question per suggestion, re-submit with enriched data\nStop when improvement_suggestions is empty or maxAttempts reached\nNever loop indefinitely\n\nSee Agent Checklist — Quality Improvement Loop and Example 13."
      },
      {
        "title": "RFC Alignment",
        "body": "This protocol and skill documentation are aligned with these core RFCs:\n\nRFC 9110 — HTTP semantics (202 Accepted, conditional requests, retry behavior)\nRFC 2119 + RFC 8174 — normative terms (MUST, SHOULD, MAY)\nRFC 3339 — timestamp formats used by HITL case lifecycle fields\nRFC 6750 — bearer token usage for review and inline submit authorization\n\nFor the complete implementation matrix, see README RFC Alignment."
      },
      {
        "title": "Resources",
        "body": "Full Specification (v0.7)\nOpenAPI 3.1 Spec — all endpoints documented\nJSON Schemas — HITL object, poll response, form field, submit request definitions\nReference Implementations — Express 5, Hono, Next.js, FastAPI\nReview Page Templates — HTML templates for all 5 review types\nExamples — 12 end-to-end flows (incl. inline confirmation, escalation, hybrid approval)\nAgent Implementation Checklist — detailed agent guide with pseudocode\nInteractive Playground\nSDK Design Guide — build a community SDK"
      }
    ],
    "body": "HITL Protocol\n\nAI agents increasingly visit websites and services on behalf of their users: searching, booking, applying, purchasing. But some decisions are too important to leave 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 ensures humans stay in control of these moments. The user stays in their favorite messenger — Telegram, WhatsApp, Slack — and either taps a decision button right there or follows a link to a web page with a comfortable UI: cards, forms, buttons. No wall of text. No blind agent decisions. When you encounter a HITL response, tell your user that a decision is needed that should not be made by an agent alone — forward the prompt and make it easy to act: show the review link or render action buttons.\n\nHITL Protocol is to human decisions what OAuth is to authentication — an open standard connecting Services, Agents, and Humans. When a service needs human input, it returns HTTP 202 with a review URL. The agent forwards the URL to the human. The human opens it in a browser, gets a rich UI, and makes an informed decision. The agent polls for the structured result and continues.\n\nFor simple decisions (confirm/cancel, approve/reject), agents can render native messaging buttons directly in Telegram, Slack, Discord, WhatsApp, or Teams — no browser needed. The service opts in via submit_url.\n\nNo SDK required. No UI framework mandated. Just HTTP + URL + polling.\n\nInteractive Playground — try all review types, transports, and inline actions live in your browser.\n\nWho Are You?\nYour role\tYou want to...\tRead\nService/website builder\tAdd HITL endpoints to your API so agents can request human input\tService Integration Guide\nAgent developer\tHandle HTTP 202 + HITL responses from services\tAgent Integration Guide\nBoth / Learning\tUnderstand the full protocol\tContinue reading below\nThe Flow\nStandard flow (all review types):\n1. Human → Agent:    \"Find me jobs in Berlin\"\n2. Agent → Service:  POST /api/search {query: \"Senior Dev Berlin\"}\n3. Service → Agent:  HTTP 202 + hitl object (review_url, poll_url, type, prompt)\n4. Agent → Human:    \"Found 5 jobs. Review here: {review_url}\"\n5. Human → Browser:  Opens review_url → rich UI (cards, forms, buttons)\n6. Human → Service:  Makes selection, clicks Submit\n7. Agent → Service:  GET {poll_url} → {status: \"completed\", result: {action, data}}\n8. Agent → Human:    \"Applied to 2 selected jobs.\"\n\nInline flow (v0.7 — simple decisions only, when submit_url present):\n1. Human → Agent:    \"Send my application emails\"\n2. Agent → Service:  POST /api/send {emails: [...]}\n3. Service → Agent:  HTTP 202 + hitl object (incl. submit_url, submit_token, inline_actions)\n4. Agent → Human:    Native buttons in chat: [Confirm] [Cancel] [Details →]\n5. Human → Agent:    Taps [Confirm] in chat\n6. Agent → Service:  POST {submit_url} {action: \"confirm\", submitted_via: \"telegram\"}\n7. Service → Agent:  200 OK {status: \"completed\"}\n8. Agent → Human:    Updates message: \"Confirmed — 3 emails sent.\"\n\n\nThe agent never renders UI. The service hosts the review page. Sensitive data stays in the browser — never passes through the agent. The inline flow is an optional shortcut for simple decisions.\n\nFeature Matrix\nFeature\tDetails\nReview types\tapproval, selection, input, confirmation, escalation\nForm field types\ttext, textarea, number, date, email, url, boolean, select, multiselect, range, custom x-*\nTransport\tPolling (required), SSE (optional), Callback/Webhook (optional)\nInline submit\tsubmit_url + native messaging buttons (Telegram, Slack, Discord, WhatsApp, Teams) — service opt-in\nStates\tpending → opened → in_progress → completed / expired / cancelled\nSecurity\tOpaque tokens (43 chars, base64url, 256-bit entropy), SHA-256 hash storage, timing-safe comparison, HTTPS only\nMulti-round\tprevious_case_id / next_case_id for iterative edit cycles (Approval type)\nForms\tSingle-step fields, multi-step wizard, conditional visibility, validation rules, progress tracking\nTimeouts\tISO 8601 duration, default_action: skip / approve / reject / abort\nDiscovery\t.well-known/hitl.json, SKILL.md metadata.hitl extension\nReminders\treminder_at timestamps, review.reminder SSE event\nRate limiting\t60 requests/min per case on poll endpoint, Retry-After header\nFive Review Types\nType\tActions\tMulti-round\tForm fields\tUse case\nApproval\tapprove, edit, reject\tYes\tNo\tArtifact review (CV, email, deployment plan)\nSelection\tselect\tNo\tNo\tChoose from options (job listings, targets)\nInput\tsubmit\tNo\tYes\tStructured data entry (salary, dates, preferences)\nConfirmation\tconfirm, cancel\tNo\tNo\tIrreversible action gate (send emails, deploy)\nEscalation\tretry, skip, abort\tNo\tNo\tError recovery (deployment failed, API error)\nHITL Object (HTTP 202 Response Body)\n\nWhen a service needs human input, it returns HTTP 202 with this structure:\n\n{\n  \"status\": \"human_input_required\",\n  \"message\": \"5 matching jobs found. Please select which ones to apply for.\",\n  \"hitl\": {\n    \"spec_version\": \"0.7\",\n    \"case_id\": \"review_abc123\",\n    \"review_url\": \"https://service.example.com/review/abc123?token=K7xR2mN4pQ...\",\n    \"poll_url\": \"https://api.service.example.com/v1/reviews/abc123/status\",\n    \"type\": \"selection\",\n    \"prompt\": \"Select which jobs to apply for\",\n    \"timeout\": \"24h\",\n    \"default_action\": \"skip\",\n    \"created_at\": \"2026-02-22T10:00:00Z\",\n    \"expires_at\": \"2026-02-23T10:00:00Z\",\n    \"context\": {\n      \"total_options\": 5,\n      \"query\": \"Senior Dev Berlin\"\n    }\n  }\n}\n\nRequired Fields\nField\tType\tDescription\nspec_version\t\"0.7\"\tProtocol version\ncase_id\tstring\tUnique, URL-safe identifier (pattern: review_{random})\nreview_url\tURL\tHTTPS URL to review page with opaque bearer token\npoll_url\tURL\tStatus polling endpoint\ntype\tenum\tapproval / selection / input / confirmation / escalation / x-*\nprompt\tstring\tWhat the human needs to decide (max 500 chars)\ncreated_at\tdatetime\tISO 8601 creation timestamp\nexpires_at\tdatetime\tISO 8601 expiration timestamp\nOptional Fields\nField\tType\tDescription\ntimeout\tduration\tHow long the review stays open (24h, PT24H, P7D)\ndefault_action\tenum\tskip / approve / reject / abort — action on expiry\ncallback_url\tURL / null\tEchoed callback URL if agent provided one\nevents_url\tURL\tSSE endpoint for real-time status events\ncontext\tobject\tArbitrary data for the review page (not processed by agent)\nreminder_at\tdatetime / datetime[]\tWhen to re-send the review URL\nprevious_case_id\tstring\tLinks to prior case in multi-round chain\nsurface\tobject\tUI format declaration (format, version)\nsubmit_url\tURL\tAgent-submit endpoint for channel-native inline buttons (v0.7)\nsubmit_token\tstring\tBearer token for submit_url authentication (required if submit_url set)\ninline_actions\tstring[]\tActions permitted via submit_url (e.g. [\"confirm\", \"cancel\"]). If absent, all actions for the type are allowed.\nPoll Response (Completed)\n{\n  \"status\": \"completed\",\n  \"case_id\": \"review_abc123\",\n  \"completed_at\": \"2026-02-22T10:15:00Z\",\n  \"result\": {\n    \"action\": \"select\",\n    \"data\": {\n      \"selected_jobs\": [\"job-123\", \"job-456\"],\n      \"note\": \"Only remote positions\"\n    }\n  }\n}\n\n\nThe result object is present only when status is \"completed\". It always contains action (string) and data (object with type-dependent content).\n\nPoll Response Statuses\nStatus\tTerminal\tDescription\tKey fields\npending\tNo\tCase created, human hasn't opened URL\texpires_at\nopened\tNo\tHuman opened the review URL\topened_at\nin_progress\tNo\tHuman is interacting with the form\tprogress (optional)\ncompleted\tYes\tHuman submitted response\tresult, completed_at, responded_by\nexpired\tYes\tTimeout reached\texpired_at, default_action\ncancelled\tYes\tHuman clicked cancel\tcancelled_at, reason\nState Machine\n            +---------------------------------------------+\n            |                                             v\n[created] -> pending -> opened -> in_progress -> completed [terminal]\n               |         |          |\n               |         |          +---------> cancelled  [terminal]\n               |         |\n               |         +--> completed     [terminal]\n               |         +--> expired       [terminal]\n               |         +--> cancelled     [terminal]\n               |\n               +----------> expired          [terminal]\n               +----------> cancelled        [terminal]\n\n\nTerminal states (completed, expired, cancelled) are immutable — no further transitions.\n\nFor Services: Quick Start\n\nReturn HTTP 202 when human input is needed:\n\n// Express / Hono / any HTTP framework\napp.post('/api/search', async (req, res) => {\n  const results = await searchJobs(req.body.query);\n\n  // Create review case with opaque token\n  const caseId = `review_${crypto.randomBytes(16).toString('hex')}`;\n  const token = crypto.randomBytes(32).toString('base64url'); // 43 chars\n  const tokenHash = crypto.createHash('sha256').update(token).digest('hex');\n\n  store.set(caseId, {\n    status: 'pending',\n    tokenHash,\n    results,\n    created_at: new Date().toISOString(),\n    expires_at: new Date(Date.now() + 86400000).toISOString(),\n  });\n\n  res.status(202).json({\n    status: 'human_input_required',\n    message: `${results.length} jobs found. Please select which ones to apply for.`,\n    hitl: {\n      spec_version: '0.6',\n      case_id: caseId,\n      review_url: `https://yourservice.com/review/${caseId}?token=${token}`,\n      poll_url: `https://api.yourservice.com/v1/reviews/${caseId}/status`,\n      type: 'selection',\n      prompt: 'Select which jobs to apply for',\n      timeout: '24h',\n      default_action: 'skip',\n      created_at: store.get(caseId).created_at,\n      expires_at: store.get(caseId).expires_at,\n    },\n  });\n});\n\n\nYou also need: a review page (any web framework), a poll endpoint (GET /reviews/:caseId/status), and a response endpoint (POST /reviews/:caseId/respond). See Service Integration Guide for full details.\n\nFor Agents: Quick Start\n\nHandle HTTP 202 responses — ~15 lines:\n\nimport time, httpx\n\nresponse = httpx.post(\"https://api.jobboard.com/search\", json=query)\n\nif response.status_code == 202:\n    hitl = response.json()[\"hitl\"]\n\n    # v0.7: Check for inline submit support\n    if \"submit_url\" in hitl and \"submit_token\" in hitl:\n        # Render native buttons in messaging platform (e.g. Telegram, Slack)\n        send_inline_buttons(hitl[\"prompt\"], hitl[\"inline_actions\"], hitl[\"review_url\"])\n        # When human taps button → POST to submit_url (see Agent Integration Guide)\n    else:\n        # Standard flow: forward URL to human\n        send_to_user(f\"{hitl['prompt']}\\n{hitl['review_url']}\")\n\n    # Poll for result (standard flow or fallback)\n    while True:\n        time.sleep(30)\n        poll = httpx.get(hitl[\"poll_url\"], headers=auth).json()\n\n        if poll[\"status\"] == \"completed\":\n            result = poll[\"result\"]  # {action: \"select\", data: {...}}\n            break\n        if poll[\"status\"] in (\"expired\", \"cancelled\"):\n            break\n\n\nNo SDK. No UI rendering. Just HTTP + URL forwarding + polling. See Agent Integration Guide for inline submit, SSE, callbacks, multi-round, and edge cases.\n\nThree Transport Modes\nTransport\tAgent needs public endpoint?\tReal-time?\tComplexity\nPolling (default)\tNo\tNo\tMinimal\nSSE (optional)\tNo\tYes\tLow\nCallback (optional)\tYes\tYes\tMedium\n\nPolling is the baseline — every HITL-compliant service MUST support it. SSE and callbacks are optional enhancements.\n\nChannel-Native Inline Actions (v0.7)\n\nFor 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.\n\nHow it works: The service includes submit_url + submit_token in the HITL object. The agent detects these fields and renders platform-native buttons. When the human taps a button, the agent POSTs the action to submit_url. The messaging platform is passive — it renders whatever the agent sends. No messenger auto-detects HITL support.\n\nWhen to use inline buttons:\n\nReview type\tInline possible?\tReason\nConfirmation\tYes\t2 buttons: Confirm / Cancel\nEscalation\tYes\t3 buttons: Retry / Skip / Abort\nApproval (simple)\tYes\t2 buttons: Approve / Reject (without edit)\nApproval (with edit)\tURL only\tEdit requires rich UI\nSelection\tURL only\tNeeds list/cards UI\nInput\tURL only\tNeeds form fields\n\nAlways include a URL fallback button (e.g. \"Details →\") linking to review_url — the human can always switch to the full review page.\n\nPlatform requirements: The agent must be a platform bot (Telegram Bot via BotFather, Slack App, Discord Bot, WhatsApp Business API, Teams Bot) to send native buttons. See Agent Integration Guide for platform-specific rendering patterns.\n\nNon-Goals\nDoes NOT render review UI — the service hosts and renders the review page. The agent is a messenger.\nDoes NOT define the review page framework — any web technology works (React, plain HTML, etc.).\nDoes NOT replace OAuth — HITL is for decisions, not authentication.\nDoes NOT submit on behalf of the human — unless the human explicitly triggers an inline action button in a messaging platform (v0.7 submit_url).\nSKILL.md Extension for Services\n\nServices that use HITL can declare support in their own SKILL.md frontmatter:\n\nmetadata:\n  hitl:\n    supported: true\n    types: [selection, confirmation]\n    supports_inline_submit: true\n    review_base_url: \"https://yourservice.com/review\"\n    timeout_default: \"24h\"\n    info: \"May ask user to select preferred jobs or confirm applications.\"\n\n\nSee spec Section 12 for the full field reference.\n\nBest Practice: Enforce HITL Choice\n\nProblem: Agents tend to take the efficient path and silently skip HITL — defaulting to no human review. Even though the protocol says agents MUST NOT ignore HTTP 202, nothing prevents an agent from never sending requests that trigger HITL in the first place.\n\nSolution: Force agents to make an explicit choice per request. Add prefer_hitl and skip_hitl flags to your API and reject requests that provide neither.\n\nDeclare this in your SKILL.md:\n\nmetadata:\n  hitl:\n    supported: true\n    hitl_required: true\n    types: [selection, confirmation]\n    info: \"HITL is required. You MUST send prefer_hitl: true or skip_hitl: true.\"\n\n\nAdd an Agent Guidelines section to your SKILL.md body:\n\n## Agent Guidelines\n\nHITL is required for this service. Every request MUST include exactly one of:\n\n| Parameter | Type | Effect |\n|-----------|------|--------|\n| `prefer_hitl` | boolean | `true` → human reviews via HITL (HTTP 202) |\n| `skip_hitl` | boolean | `true` → direct execution, no human review (HTTP 201) |\n\nYou MUST choose one. Omitting both returns 400 `HITL_CHOICE_REQUIRED`.\nSending both returns 400 validation error.\n\n### Example: With HITL\n\nPOST /api/search\n{\"query\": \"Senior Dev Berlin\", \"prefer_hitl\": true}\n\n→ 202 + hitl object (human reviews results)\n\n### Example: Without HITL\n\nPOST /api/search\n{\"query\": \"Senior Dev Berlin\", \"skip_hitl\": true}\n\n→ 201 {\"results\": [...], \"hitl_skipped\": true}\n\n### Example: Missing choice\n\nPOST /api/search\n{\"query\": \"Senior Dev Berlin\"}\n\n→ 400 {\"error\": \"HITL_CHOICE_REQUIRED\", \"message\": \"You must send prefer_hitl or skip_hitl.\"}\n\n\nSee Service Integration Guide — Enforcing HITL Choice for validation gate implementation.\n\nOptional: Quality Improvement Signal\n\nServices can include improvement_suggestions in successful (non-202) responses to give agents structured feedback they can act on — without requiring a new HITL flow.\n\nDeclare support in your SKILL.md:\n\nmetadata:\n  hitl:\n    supported: true\n    supports_improvement_suggestions: true\n    info: \"Returns improvement_suggestions in 201 responses. Agents may offer up to 2 improvement cycles.\"\n\n\nSuggestion object schema:\n\nField\tType\tDescription\nfield\tstring\tWhich data field can be improved\nissue\tstring\tWhat is missing or suboptimal\nagent_action\tstring\tExact question/action for the agent to take\nimpact\tstring\tHuman-readable benefit (e.g. \"+25 quality points\")\npriority\t\"high\" / \"medium\" / \"low\"\tOrder of importance\n\nAgent behavior:\n\nAlways share the primary result first\nOffer up to 2 improvement cycles — one question per suggestion, re-submit with enriched data\nStop when improvement_suggestions is empty or maxAttempts reached\nNever loop indefinitely\n\nSee Agent Checklist — Quality Improvement Loop and Example 13.\n\nRFC Alignment\n\nThis protocol and skill documentation are aligned with these core RFCs:\n\nRFC 9110 — HTTP semantics (202 Accepted, conditional requests, retry behavior)\nRFC 2119 + RFC 8174 — normative terms (MUST, SHOULD, MAY)\nRFC 3339 — timestamp formats used by HITL case lifecycle fields\nRFC 6750 — bearer token usage for review and inline submit authorization\n\nFor the complete implementation matrix, see README RFC Alignment.\n\nResources\nFull Specification (v0.7)\nOpenAPI 3.1 Spec — all endpoints documented\nJSON Schemas — HITL object, poll response, form field, submit request definitions\nReference Implementations — Express 5, Hono, Next.js, FastAPI\nReview Page Templates — HTML templates for all 5 review types\nExamples — 12 end-to-end flows (incl. inline confirmation, escalation, hybrid approval)\nAgent Implementation Checklist — detailed agent guide with pseudocode\nInteractive Playground\nSDK Design Guide — build a community SDK"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/rotorstar/hitl-protocol",
    "publisherUrl": "https://clawhub.ai/rotorstar/hitl-protocol",
    "owner": "rotorstar",
    "version": "0.7.2",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/hitl-protocol",
    "downloadUrl": "https://openagent3.xyz/downloads/hitl-protocol",
    "agentUrl": "https://openagent3.xyz/skills/hitl-protocol/agent",
    "manifestUrl": "https://openagent3.xyz/skills/hitl-protocol/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/hitl-protocol/agent.md"
  }
}