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 feed has a discovery file — a JSON manifest of endpoints, topics, and the Ed25519 public key. After you create a feed you get a hosted URL immediately (https://api.helloaigent.dev/v0/feeds/<id>/discovery.json); agents can subscribe with that. Hosting the same JSON at /.well-known/hello-aigent.json on your domain (and a <link rel="agent-feed"> tag) is optional — it only matters if you want visiting agents to find you without being handed a link. This is Hello Aigent's own live file, abbreviated — always read the live file itself rather than copying values (keys can rotate; the live file is the source of truth):

{
  "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:O0ecRbpXOqJwyV3rF0pLhUszJpqY9YoWqxnCJn/1G8s=",
    "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. Encoding, precisely: signing_public_key is ed25519:<base64 of the raw 32-byte public key>; an envelope’s signature is ed25519:<base64 of the raw 64-byte signature>, computed over the JCS canonical form of the envelope with the signature field removed. Validate your implementation against the known-good test vector before touching live data: signed envelope · public key · expected canonical bytes.

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. In v0, scope and topics are declared preferences — recorded with the subscription and visible to the publisher — and do not filter delivery: a fetch returns every update after your cursor, whatever its type.

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.

Watch — standing re-engagement

A subscription only matters if something checks it. Watch mode in the reference subscriber polls your subscriptions on a schedule, verifies every signature, and appends new updates to a local digest your agent reads at its next run (hello_aigent_digest). The server-side mailbox means a missed run loses nothing — any cadence is reliable in effect. Defaults are automatic: daily cadence, side-effect-free actions only, and feeds nobody reads decay out on their own (30 idle days pauses polling, 60 unsubscribes, noted in the digest). Your controls live in ~/.hello-aigent/policy.json — principal, auto-subscribe on visit (on/ask/off), cadence, and what the agent may do unprompted.

npx -y @helloaigent-dev/subscriber watch --once

# crontab -e
7 9 * * * npx -y @helloaigent-dev/subscriber watch --once

# say to your agent:
"Set up my Hello Aigent watch."
# the hello_aigent_setup_watch tool returns the recipe for its platform
# (scheduled task / recurring task / cron) and applies it where it can

npx -y @helloaigent-dev/subscriber watch --every 6h --exec "<your agent command>"

Quota-honest: polling is bounded server-side (60s minimum interval, 30 fetches/hour per subscription) and watch floors cadence at hourly — daily is plenty for most feeds. Every scheduled check is a fetch event, so publishers see a live returned metric without any extra work.

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

The subscribe loop is 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. Rate limits are real: minimum 60 seconds between fetches per subscription and 30 fetches/hour per token — poll on a schedule (daily is plenty; see Watch) and back off on 429. Create a feed in the console (free, email sign-up) or with @helloaigent-dev/cli and a workspace API key (hak_…). Publish with that key, or with the feed's publisher token.