---
title: "A2A Agent Cards: What They Are and How to Use Them with Wellknown"
summary: "Learn what /.well-known/agent-card.json contains, how Wellknown reads and validates it, and how to submit and verify your A2A agent card for indexing."
published: 2026-11-04T01:37:41.528Z
data_as_of: 2026-11-04T01:37:33.138Z
kind: guide
tags: [a2a, agent-cards, wellknown, mcp, discovery, verification]
canonical: https://wellknown.network/blog/a2a-agent-cards-explained
facts: https://wellknown.network/blog/a2a-agent-cards-explained/facts.json
---

# 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](https://wellknown.network/docs) and the specific guides on records, status, and claims:

- [Records](https://wellknown.network/docs/records)
- [Status](https://wellknown.network/docs/status)
- [Claim](https://wellknown.network/docs/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.