The agent record

One document per agent, served at /api/v1/agents/{id} and /agents/{handle}/record.json. It is the same object the website renders.

Identity

id is opaque and permanent (ag_…). handle is the URL name and stable once assigned; renames keep the old handle as an alias. Neither encodes a model, provider, framework or endpoint, so a record survives all of them changing. Two sources describing the same repository or the same endpoint attach to one record; they never create two.

Shape

{
  "$schema": "https://wellknown.network/schemas/agent-record-v1.json",
  "id": "ag_v3bzkm6gafcr", "handle": "mcp-postgres-server", "kind": "mcp_server",
  "declared": {              // what sources said, attributed per field
    "name", "summary", "description", "publisher", "homepage", "repository",
    "version", "license", "protocols", "tags", "pricing",
    "endpoints": [{ "url", "type", "auth", "probeable" }],
    "skills", "tools", "extra",
    "attribution": { "summary": "npm", "repository": "npm", … }
  },
  "derived": {               // Wellknown's mapping, with confidence
    "capabilities": [{ "slug": "data.database", "confidence": 1, "provenance": "declared" }],
    "categories": ["data"]
  },
  "observed": {              // what Wellknown measured
    "status": "live" | "recently_observed" | "unavailable" | "unknown",
    "statusReason", "lastOkAt", "lastProbedAt", "statusComputedAt",
    "reliability30d": { "probes", "successRate", "p50Ms" } | null,
    "latestObservations": [{ "at", "kind", "ok", "httpStatus", "latencyMs", "error", "detail" }],
    "tools": [{ "name", "description" }] | null,   // from an MCP tools/list handshake
    "package": { "registry", "name", "latestVersion", "publishedAt", "weeklyDownloads", "observedAt" } | null
  },
  "verification": { "claimed": false, "claimedAt": null, "proofs": [] },
  "provenance": { "sources": [{ "source", "key", "url", "firstSeenAt", "fetchedAt" }] },
  "firstSeenAt", "updatedAt"
}

Provenance rules

• Every source row keeps the raw upstream payload and its fetch time. Nothing is edited in place.
• Fields are merged from sources in priority order: verified owner > A2A card from the agent's own origin > official MCP registry > npm > PyPI > GitHub lists > self-submission. Lower-priority sources only fill gaps.
• Each merged field records which source supplied it (declared.attribution), and every change appends a provenance event (declared, observed, derived or claimed).
• Capabilities carry their own provenance and, when derived, the confidence of the match.
• A verified owner can remove a self-submission from their own record. Its key, its link and the values only it supplied leave the record, the same submission sent again is not added back, the history notes the removal without saying what it was, and addresses and their checks stay. Listings from registries and package indexes cannot be removed this way.

What is never in a record

Star ratings, popularity scores presented as quality, or any state we did not observe. Registry download counts appear as what they are: a registry-observed adoption figure.