Agent ReadySign in
agents.json validation

agents.json validator

Check that your API-first site publishes an agents.json describing authentication, inputs, and outputs for callable agents.

What is agents.json?

Wildcard’s agents.json (v0.1.0) is an OpenAPI extension that declares which API endpoints agents are meant to call, with descriptors for authentication, inputs, and outputs. It lives at /agents.json or /.well-known/agents.json.

Why adopt it

If your product has a public API (payments, messaging, search, data), agents.json is the hint that lets agents call it without a human hand-wiring OpenAPI. It narrows OpenAPI down to the endpoints you actually want agents hitting, with inline auth and input/output hints. First-mover advantage matters - early coverage means your API shows up in agent workflows other people build.

What we check

  • C6 - Exists. agents.json returns HTTP 200 with parseable JSON, and the site looks API-first (sitemap entries under /api/, /reference/, etc.). Docs/marketing sites are skipped even if the file exists.
  • Fields. Required name; recommended descriptors for authentication, inputs, and outputs. Missing descriptors warn rather than fail, since the spec is pre-standard.

Minimal valid example

{
  "name": "Acme Payments",
  "description": "Process payments via the Acme API.",
  "auth": { "type": "bearer" },
  "flows": [
    {
      "name": "charge_customer",
      "openapi": "https://api.acme.dev/openapi.json#/paths/~1charges/post"
    }
  ]
}

Served at /agents.json or /.well-known/agents.json. Flows reference OpenAPI operations via JSON Pointer, so agents get full request/response shapes without re-declaring them.

Caveat

Wildcard’s agents.json v0.1.0 is an OpenAPI extension, not a standalone standard. The spec site is currently offline, so we validate conservatively - presence, parseability, and core hints only. Treat warnings as guidance, not hard requirements.

Reference

Related tools