Introduction

Hello Aigent is the subscription layer for the agentic web. Publishers expose a feed of signed updates; agents subscribe with a principal and a consent scope, and fetch updates over time — turning one-off visits into an audience a publisher owns.

Everything is API-first and self-describing — an agent needs zero prior knowledge beyond the discovery file. This page covers the core concepts; the Quickstart gets you running in three calls.

The discovery file

Every publisher hosts a single JSON file at /.well-known/hello-aigent.json. It's how agents find a feed — with or without a human clicking the mark. Point a <link rel="agent-feed"> at it for autodiscovery. This is Hello Aigent's own live file, abbreviated:

{
  "hello_aigent_version": "0.1",
  "publisher": { "name": "Hello Aigent", "site": "https://helloaigent.dev" },
  "feeds": [{
    "id":    "hello-aigent-product",
    "title": "Hello Aigent product updates",
    "topics": ["product-updates", "agent-offers"],
    "signing_public_key": "ed25519:c7WgLxBY…ivWQ=",
    "endpoints": {
      "subscribe":   "https://api.helloaigent.dev/v0/subscribe",
      "fetch":       "https://api.helloaigent.dev/v0/fetch",
      "unsubscribe": "https://api.helloaigent.dev/v0/unsubscribe"
    },
    "subscribe_schema_url":
      "https://helloaigent.dev/schemas/subscribe-request.schema.json",
    "update_schema_version": "0.1"
  }]
}

The envelope

Each update is an envelope with four parts, ordered so an agent can triage cheaply and only read deeper when it needs to.

Signing & verification

Every update is signed with the feed's Ed25519 key over its RFC 8785 (JCS) canonical form. Agents verify against the signing_public_key in the discovery file before acting — this is the trust beat of the loop. The reference subscriber does this for you and strips actions from anything that fails.

Consent scopes

A subscription declares what the agent consented to receive, on behalf of its principal. Scope is a first-class, visible attribute — never hidden metadata. Unsubscribe is one idempotent call.

Callable actions

Updates can attach typed actions — a name, an endpoint, and an input_schema — so an agent executes intent directly instead of interpreting a link. Actions are called on the publisher's endpoints and attributed to the calling principal. The live demo feed exposes one: claim_offer.

The mark

<a href="/.well-known/hello-aigent.json" rel="agent-feed"
   aria-label="Subscribe with your agent">
  <svg width="24" height="24" viewBox="0 0 120 120" aria-hidden="true">
    <rect x="2" y="2" width="116" height="116" rx="27" fill="#E0531C"/>
    <path d="M16 43V77 M16 60H48 M48 30V90" stroke="#fff" stroke-width="9" fill="none"/>
    <path d="M60 30 L100 60 L60 90 M77.6 43.2V76.8" stroke="rgba(10,10,10,.35)" stroke-width="9" fill="none"/>
  </svg>
  <span>Agent subscribe</span>
</a>

<link rel="agent-feed"
      type="application/hello-aigent+json"
      href="/.well-known/hello-aigent.json"
      title="Hello Aigent — agent feed">

Part 3 is the discovery file itself — the mark, the <link>, and the file must all resolve to the same feed. Minimum size 16px; keep clearspace ≥ the H height; add aria-label whenever the icon appears without a label.

API reference

Six endpoints, all under https://api.helloaigent.dev/v0 — each advertises its input schema, so agents need zero prior knowledge. Full contract in the OpenAPI spec and JSON Schemas.