Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/agents-json

    agents.json at /.well-known/agents.json

    What it checks

    Whether anything is published at /.well-known/agents.json, and if so whether what is published there is a real agents.json document.

    The check never asks a site to publish the file. A site that serves nothing at that path is reported as not applicable: the convention has no documented consumer, so its absence is not a finding and is excluded from scoring entirely. When a document is published, the check validates the shape the agents.json v0.1.0 specification actually defines — an info object alongside a sources array (each entry pointing at an OpenAPI document) or a flows array — and reports a warning, at weight 0, when what is served is something else:

    • an HTTP 200 carrying the site’s HTML shell (a soft 404 at a well-known path);
    • a body that does not parse as JSON;
    • JSON that is not an agents.json document, including [] and {};
    • a valid document served with a text/html content type, which a client dispatching on media type will not read as a document.

    The check never returns a failure. Its evidence grade is C, so it carries weight 0 and cannot move a score in any direction.

    Why it matters

    agents-json — Publishing an agents.json file (the Wildcard AI OpenAPI-derived contract describing flows, links and actions) lets AI agents discover and reliably invoke a site’s API workflows.

    agent-surface-soft-404-validation — A well-known or conventional agent-discovery path that returns HTTP 200 with an HTML body is worse than a 404 — that body is an SPA catch-all rather than a real document. A conforming client follows the standard, fails to parse, and has no recourse. Any audit must therefore validate content-type and parseability, not status code.

    Evidence

    agents-json

    agents.json was a genuine 2025 proposal: an open spec layered on OpenAPI, adding flows (chains of calls), links between actions, and agent-facing metadata. It accumulated 1,314 stars and 66 forks. It was not fringe at its peak.

    agent-surface-soft-404-validation

    This is a meta-signal about how the other audits must be implemented, and it is the best-evidenced claim in the whole domain. The May 2026 API Evangelist study covered 74 providers. Of the roughly 72 that served no valid catalog, only two returned a clean 404; sixty-eight returned HTTP 200 with an HTML body. The study concluded: ‘an agent following the standard would get a 200, try to parse a LinkSet out of the body, fail, and have no useful recourse — an HTML 200 at a well-known path lies, which is worse than a 404.’ A probe on 2026-08-20 reproduced that result across a different path set. linear.app returned 200 text/html for /openapi.json; github.com, linear.app, vercel.com and zapier.com returned 200 text/html for /mcp; zapier.com returned 200 text/html for /.well-known/ai-plugin.json.

    A status-code-only scanner would have reported all of these as adoption. The correct rule is to require a JSON, YAML or linkset content-type, and to require the body to parse. Where a spec names a media type, prefer it: application/ai-catalog+json for AI catalogs, application/linkset+json with the RFC 9727 profile for api-catalog, and application/mcp-server-card+json for card entries. Vercel demonstrates that all of this is achievable in production.

    Limits

    agents-json — The project is dead by every measurable signal, checked 2026-08-20. The repository wild-card-ai/agents-json has not been pushed since 2025-08-21 — twelve months stale — and its description field is now empty. Its declared homepage agents-json.com fails to resolve entirely (curl exit code 6 / HTTP 000). The documentation host docs.wild-card.ai serves an EXPIRED TLS certificate (valid 2026-01-09 to 2026-04-09, i.e. expired four months ago) so the spec itself is unreachable over HTTPS without an error. The spec version never advanced past 0.1.0. No agent vendor has ever documented consuming it, and there is no IANA registration. Auditing for agents.json would tell site owners to implement a specification whose own documentation site has been broken since April.

    agent-surface-soft-404-validation — None found — this is a validation-correctness requirement, not a contested adoption claim. The only nuance is that content negotiation is legitimate. RFC 9727 permits additional formats beyond the mandatory Linkset, so an audit should send an explicit Accept header before concluding a publisher is non-conformant. It should also not penalise a clean 404, which is honest, the way it penalises an HTML 200, which is a lie.

    Sources