---
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 cards for indexing."
published: 2026-11-14T00:36:36.180Z
data_as_of: 2026-11-14T00:36:26.508Z
kind: guide
tags: [a2a, agent-cards, wellknown, mcp, api, discovery]
canonical: https://wellknown.network/blog/a2a-agent-cards-explained-2
facts: https://wellknown.network/blog/a2a-agent-cards-explained-2/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 AI agent’s name, skills, endpoint URL, and security schemes. This standardized format enables agents to discover each other and exchange tasks over JSON-RPC using the Agent2Agent protocol (A2A). For developers shipping agents, publishing an Agent Card is essential to make your agent discoverable and interoperable in the AI ecosystem.

## How Wellknown Sees Your Agent Card
Wellknown indexes AI agents by fetching their Agent Cards from the `/.well-known/agent-card.json` path on their domains. 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

Wellknown’s index currently contains 92,257 records, with 30,059 live. This separation helps you understand how your agent card performs in the index and whether it is reliably reachable.

## Step-by-Step: Publishing and Verifying Your Agent Card
1. **Create your Agent Card JSON** at the path `/.well-known/agent-card.json` on your domain. Include your agent’s name, skills, endpoint URL, and security schemes exactly as your agent supports.

2. **Submit your agent card to Wellknown** using the HTTP API endpoint `https://wellknown.network/api/v1/submit`. This submission lets Wellknown know about your agent and triggers indexing.

3. **Claim ownership of your record** to verify control. You can prove ownership by adding one of the following claim proofs:
   - A DNS TXT record at `_wellknown.YOUR-DOMAIN`
   - A file at `https://YOUR-DOMAIN/.well-known/wellknown-verify.txt`
   - A `.wellknown-verify` file at your repository root

   Claim tokens are valid for 7 days.

4. **Check your agent’s status** via `https://wellknown.network/api/v1/agents/{id}/status` to see if it is live or recently observed.

5. **Use MCP tools** if you interact programmatically with Wellknown’s MCP server at `https://wellknown.network/mcp`. Tools like `search_agents`, `resolve_agent`, and `check_status` help you query and monitor agents.

## What Changes Once Your Agent Card Is Indexed
Once indexed and verified, your agent appears in Wellknown’s live index, making it discoverable by developers and AI applications. Your agent’s metadata is available through API endpoints such as `https://wellknown.network/api/v1/agents/{id}` and can be searched via `https://wellknown.network/api/v1/search`. Your agent’s live status is regularly checked with an 8-second probe timeout, ensuring the index reflects current availability.

This visibility can increase your agent’s usage and integration opportunities. Additionally, you can monitor your agent’s health and update your Agent Card as needed to maintain a live status.

## Common Mistakes to Avoid
- **Incorrect path or JSON format**: Your Agent Card must be exactly at `/.well-known/agent-card.json` and follow the JSON structure expected by the A2A protocol.
- **Skipping claim verification**: Without claiming ownership via DNS TXT or verification files, your record won’t show a verified owner, which may reduce trust.
- **Ignoring rate limits**: Wellknown’s API enforces 30 anonymous requests per minute and 120 keyed requests per minute, plus 5 anonymous submissions per hour. Exceeding these limits can cause request failures.
- **Not monitoring status**: Failing to check `https://wellknown.network/api/v1/agents/{id}/status` may leave you unaware if your agent becomes unavailable or stale.
- **Assuming unknown means failure**: The observed 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), including guides on records, status, claims, receipts, MCP, and continuity.

This guide reflects data and API details as of 2026-11-14T00:36:26.508Z.
