Specification

HAP v1.0

Human-readable specification for the Human Agent Protocol.

Status Draft
Version 1.0
Publisher Deslop Foundation
License MIT

1. Overview

A HAP file is a JSON document published at /.well-known/hap.json on any domain. It declares an expert's identity, their structured positions, and the agent endpoint that can answer queries on their behalf.

The goal is simple: let any AI agent discover and query any human expert, with structured access controls and verifiable identity.

2. File location

The canonical location is https://<domain>/.well-known/hap.json. Agents should look here first. Alternative locations may be specified via a Link header or HTML <link> element with rel="hap".

3. Top-level fields

Field Type Required Description
hap string Yes Protocol version. Currently "1.0".
expert object Yes Identity and domain of the expert.
agent object Yes Agent endpoint configuration.
positions array No Structured positions the expert holds.
assets array No Gated materials (frameworks, data, whitepapers).

4. Expert object

Field Type Required Description
name string Yes Display name of the expert.
domain string Yes Primary domain of expertise.
thesis string Yes Core insight or contrarian take (1-2 sentences).
credentials array No Professional credentials and affiliations.

5. Agent object

Field Type Required Description
protocol string Yes Protocol identifier, e.g. "hap/1.0".
endpoint string Yes URL of the queryable agent endpoint.
capabilities array Yes List of supported operations: query, deep_dive, subscribe.
auth object No Authentication requirements for gated access.

6. Access tiers

HAP defines two access tiers:

  • public — Queryable by any agent without authentication. Drives discovery.
  • agent_gated — Requires the requesting agent to identify itself and its human operator. Identity is the price — not money.

7. Capabilities

  • query — Ask questions and receive structured answers from the expert's positions.
  • deep_dive — Request extended analysis on a specific position or topic.
  • subscribe — Register for updates when the expert publishes new positions.

8. Implementation notes

Agents discovering a hap.json should cache the file for no longer than the Cache-Control header specifies (default: 1 hour). Agents should include a User-Agent header identifying themselves and their human operator when querying endpoints.

View on GitHub → Validate your hap.json