Research guide · agent discovery · 13 September 2026
agents.json is not one universal agent-discovery standard.
A new generation of agent-readable web projects is converging on the same attractive filename: /.well-known/agents.json. The problem is that the documents are not interchangeable. Web2Agent, Wildcard's agents.json specification and the A2A Registry's custom multi-agent manifest use the name for different contracts, while current official A2A discovery uses /.well-known/agent-card.json.
Sources and project status checked 13 September 2026.
1 filename
Several incompatible schemas now compete for agents.json
agent-card.json
Current official A2A well-known discovery path
OpenAPI flows
Wildcard uses agents.json to describe executable API workflows
Website actions
W2A uses agents.json as a website capability declaration
Why this matters
A path collision can look like successful discovery and still route an agent incorrectly
Discovery code often starts with a predictable URL. That is useful only when the format behind the URL is also predictable. If a client fetches /.well-known/agents.json and assumes one schema without checking, it can misread fields, invent an endpoint, drop authentication requirements or reject a perfectly valid document written for another project.
The collision is especially easy to miss because all of the projects are trying to solve a legitimate version of the same problem: make a website or service easier for software agents to understand. Their unit of description is different. W2A describes website capabilities, Wildcard adds LLM-oriented workflows on top of OpenAPI, and A2A describes an actual remote agent through an Agent Card.
Treat the filename as discovery metadata, not proof of protocol identity. A robust client verifies the document shape and declared specification before it turns any field into an executable action.
Format map
Four similarly named surfaces, four different contracts
| Surface | Typical path | What it describes | Status / boundary |
|---|---|---|---|
| Official A2A Agent Card | /.well-known/agent-card.json | One A2A agent identity, interfaces, skills, capabilities and authentication requirements | A2A Protocol Working Group standard |
| Web2Agent (W2A) | /.well-known/agents.json | Website-level capabilities, actions, inputs/outputs and policies for agents | Community protocol; distinct schema and tooling |
| Wildcard agents.json | /agents.json or /.well-known/agents.json | OpenAPI-backed flows that help an agent execute multi-step API operations | Wildcard open specification; current repository describes v0.1.0 |
| A2A Registry custom agents.json | /.well-known/agents.json | An array-like multi-agent manifest for domains hosting several agents | Registry-specific extension, not the official single-agent A2A discovery document |
W2A
Web2Agent is a community attempt to make websites declare actions directly
The Web2Agent Protocol site describes W2A as an open protocol in which a website publishes /.well-known/agents.json. Its example document includes site metadata plus capabilities with an intent, HTTP action, input, output and authentication mode. The project also publishes Python, JavaScript and MCP tooling.
That is useful implementation evidence, but it is not the same thing as being the official A2A discovery format. W2A's own compatibility claims should therefore be read as a project claim about interoperability, not as permission to replace a standards-conformant A2A Agent Card with a W2A document.
Wildcard
Wildcard's agents.json is an OpenAPI workflow layer, not a website-capability clone
Wildcard's public repository describes agents.json as an open specification built on OpenAPI. Its core abstraction is a set of structured contracts or flows that refer back to API operations so an LLM can execute a sequence of calls more reliably. The repository describes the current specification as version 0.1.0 and proposes /.well-known/agents.json as a discovery location.
A W2A parser and a Wildcard parser therefore cannot safely share the assumption that “agents.json means this schema.” The same applies to the A2A Registry's separate custom multi-agent manifest, which uses the same well-known path for a list of agent records.
Builder test
Before you execute anything from agents.json, prove which contract you fetched
Path
The URL is only a hint. The same agents.json path is reused by incompatible formats.
Top-level shape
Inspect the actual keys or array structure before selecting a parser.
Spec + version
Record which project and version the publisher claims, not just the filename.
Execution target
Separate website actions, OpenAPI workflows and an A2A agent endpoint; they are different contracts.
Authentication
Use the linked protocol or OpenAPI security model. Never infer credentials from an ambiguous manifest.
Fallback
If the schema is unknown, fail closed or fall back to another declared discovery surface instead of guessing.
Safe publishing pattern
Publish explicit surfaces instead of pretending one filename has universal semantics
- 1. Keep official protocol surfaces canonical. If you implement A2A, publish the current Agent Card at
/.well-known/agent-card.json. - 2. Name the extra contract. If you also publish W2A or Wildcard agents.json, document the project and schema version on a human-readable discovery page and in machine metadata where the format allows it.
- 3. Do not alias incompatible JSON. One URL cannot safely return different schemas depending on which client you hope is calling.
- 4. Keep OpenAPI authoritative for HTTP details. Do not duplicate security, parameter or response truth inconsistently across discovery manifests.
- 5. Test with real consumers. Validate each public file using the parser or client that is supposed to consume it, then monitor failures without manufacturing agent traffic.
Sources checked
- Web2Agent Protocol — W2A overview, example
agents.json, SDK/tooling claims. - Wildcard agents-json — OpenAPI-based specification, schema model and proposed discovery path.
- A2A Protocol specification — current
agent-card.jsonwell-known registration and Agent Card semantics. - A2A Registry agents.json spec — registry-specific multi-agent manifest using
/.well-known/agents.json.
Continue