A2A Agent Cards: What They Are and How to Use Them with Wellknown

Why A2A Agent Cards Matter

A2A Agent Cards are JSON documents published at the path /.well-known/agent-card.json on a domain. They describe an agent’s name, skills, endpoint URL, and security schemes. This standardized format enables AI agents and applications to discover each other and exchange tasks using the Agent2Agent protocol (A2A). By publishing an Agent Card, developers make their agents visible and interoperable in the AI ecosystem.

How Wellknown Sees Your Agent Card

Wellknown indexes A2A Agent Cards by fetching the JSON document from the declared domain’s /.well-known/agent-card.json path. It distinguishes between declared metadata (what the publisher states) and observed status (what Wellknown measures by checking the endpoint). The observed status can be:

• live: latest check succeeded within 24 hours
• recently observed: a success within 7 days but stale or failing
• unavailable: two or more consecutive failures and no success in 7 days
• unknown: nothing to check or never checked

This status helps developers understand the current availability and reliability of their agent’s endpoint.

Step-by-Step: Publishing and Submitting Your Agent Card

1. Create your Agent Card as a JSON document describing your agent’s name, skills, endpoint URL, and security schemes.
2. Host it at /.well-known/agent-card.json on your domain so it is publicly accessible.
3. Prove ownership of your domain by one of the following claim proofs:
   • Add a DNS TXT record at _wellknown.YOUR-DOMAIN
   • Host a file at https://YOUR-DOMAIN/.well-known/wellknown-verify.txt
   • Add a .wellknown-verify file at your repository root
4. Submit your agent card to Wellknown by calling the HTTP POST endpoint https://wellknown.network/api/v1/submit with your agent card data.
5. Check your agent’s status using https://wellknown.network/api/v1/agents/{id}/status where {id} is your agent’s identifier.

Wellknown enforces rate limits of 30 anonymous submissions per minute and 120 keyed submissions per minute, with a maximum of 5 anonymous submissions per hour. Claim tokens remain valid for 7 days.

What Changes Once Your Agent Card Is Indexed

Once submitted and verified, your agent card becomes part of Wellknown’s live index, which currently contains 82,776 records with 25,937 live endpoints. Your agent will be discoverable through the search API at https://wellknown.network/api/v1/search and accessible via the resolve and get endpoints:

• https://wellknown.network/api/v1/resolve to resolve agent identifiers
• https://wellknown.network/api/v1/agents/{id} to retrieve agent metadata

Your agent’s availability and reliability will be monitored continuously, and its status updated accordingly. This visibility helps other developers and AI agents find and interact with your agent reliably.

Common Mistakes to Avoid

• Incorrect hosting path: The Agent Card must be exactly at /.well-known/agent-card.json. Hosting it elsewhere will prevent Wellknown from discovering it.
• Missing claim proofs: Without proving domain ownership via DNS TXT, verification file, or repository file, your submission cannot be verified.
• Ignoring rate limits: Exceeding anonymous or keyed submission limits can cause rejections or delays.
• Not checking status: Failing to monitor your agent’s status endpoint may leave you unaware of outages or failures.
• Assuming unknown means failure: The status “unknown” means no check has run or nothing to check, not that your agent is broken.

Additional Resources

For more details, consult Wellknown’s documentation at https://wellknown.network/docs and the specific guides on records, status, and claims:

• Records
• Status
• Claim

These resources provide comprehensive guidance on publishing, verifying, and maintaining your agent card.

This guide reflects data and procedures as of 2026-11-04T01:37:33.138Z.