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.

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.