/.well-known/agent-card.json
The well-known URI registered by the A2A specification, in use since v0.3 and unchanged in v1.0. Clients fetch this path first; serve it as JSON.
Discovery tool · A2A v1.0
Check A2A Agent Card discovery URLs
A2A clients discover an agent by fetching its JSON Agent Card from a well-known URL. Test both naming conventions on a live domain and see exactly what clients receive.
Builds both candidate discovery URLs from the same base domain.
Reports HTTP status, content type, redirect destination, and caching headers.
Parses the response as Agent Card JSON when possible.
Runs readiness checks for interfaces, skills, provider, modes, capabilities, and security metadata.
Check a public agent domain
Check the standard discovery path and optional legacy alias. Inspect returned JSON, redirects, final URL, Cache-Control, ETag, and CORS response headers.
How discovery works
One well-known URL starts every A2A integration.
Before another agent can call yours, it fetches the Agent Card from a well-known URI (RFC 8615) on your domain, evaluates the skills and security requirements, and then calls the preferred interface. If the Agent Card is missing, stale, or hidden behind a redirect, the integration ends before it begins.
This site practices what it checks: AgentCard.net publishes its own Agent Card at both paths, and the example on the right is the live document.
View our live Agent Cardagentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "AgentCard.net Toolkit",
"version": "1.0.0",
"supportedInterfaces": [
{ "url": "https://www.agentcard.net/api/a2a",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0" }
],
"skills": [
{ "id": "generate-agent-card", ... },
{ "id": "validate-agent-card", ... },
{ "id": "check-well-known-discovery", ... }
]
}Discovery paths
Two conventions, one Agent Card.
/.well-known/agent.json
Used by A2A v0.2 and earlier. Clients older than v0.3 still look here, so serving the same Agent Card as an alias is optional but harmless.
Publishing pattern
Make Agent Card discovery resilient.
Discovery failures are rarely exotic: a redirect, a cached error page, or one path deployed and the other forgotten. This publishing routine keeps both conventions serving the same, current Agent Card.
- 1
Publish at the standard path
Serve the reviewed Agent Card at /.well-known/agent-card.json over HTTPS on the same domain as the A2A service, as application/json.
- 2
Mirror the legacy path
Return the identical document from /.well-known/agent.json while older clients are still in circulation — divergent Agent Cards on the two paths confuse routing.
- 3
Keep the Agent Card synchronized
Whenever endpoints, skills, capabilities, or authentication change, update the Agent Card, bump its version field, and redeploy both paths together.
- 4
Re-check after every change
Run this checker after deployments, DNS changes, gateway migrations, or marketplace edits. Failures usually trace to redirects, HTML error pages, or one forgotten path.
FAQ
Well-known Agent JSON questions
What to publish, where to publish it, and how to keep clients on either convention working.
Which well-known Agent Card path should I use?
A2A registers /.well-known/agent-card.json as the standard discovery path (since v0.3, unchanged in v1.0). The legacy /.well-known/agent.json comes from A2A v0.2 and earlier; publish it as an alias only if you still support clients that old.
Should both paths return identical JSON?
Yes. Returning the same public Agent Card from both paths keeps clients that support only one convention consistent. Divergent documents make the agent look different depending on which path a client happens to fetch.
What content type should the Agent Card be served with?
Serve it as application/json. The A2A specification registers application/a2a+json for the HTTP+JSON binding's messages, not specifically for Agent Cards, so it is optional here. An HTML content type is a reliable sign the path is returning an error page instead of the Agent Card.
Can the public Agent Card hide private capabilities?
Yes. Publish only discovery-safe metadata in the public Agent Card, set capabilities.extendedAgentCard to true, and expose sensitive skills through the authenticated GetExtendedAgentCard operation.
Why do discovery checks fail after a deployment?
The usual causes are redirects to a login or marketing page, HTML 404 pages returned with status 200, stale JSON cached at a CDN, or only one of the two well-known paths being deployed. The checker reports status code and content type for each path so the failure is visible immediately.
Before you publish
Validate the Agent Card, then check the URLs.
Run the JSON through the full validator first, publish it at both well-known paths, and confirm discovery with this checker.
From the blog
Field guides to A2A discovery, written against the v1.0 specification.
ComparisonEN
A2A vs MCP: what changed in 2026
Compare A2A 1.0.1 and MCP 2026-07-28: discovery, stateless requests, task extensions, version negotiation, and Agent Card publishing.
5 min readRead the guideSecurityEN
Signed Agent Cards: preventing poisoning and spoofing with JWS
Learn how A2A v1.0 uses JSON Web Signatures (JWS) in the signatures array to protect Agent Cards from tampering, poisoning, and impersonation, with a signing example that actually verifies.
11 min readRead the guideArchitectureEN
Unified agent architectures: A2A and MCP in practice under the AAIF
Discover how MCP and A2A now sit under the Linux Foundation's AAIF as a dual-layer architecture, pairing tool access with cross-framework agent discovery.
10 min readRead the guideTranslations are available for selected guides; otherwise the English original is shown.