The web has a new convention: put an AGENTS.md file at the root of your domain, and any AI agent visiting your site immediately knows what it can do there. This post explains what AGENTS.md is, how it relates to the A2A Agent Card standard, and why adopting both now gives your platform a decisive SEO and discoverability edge.

What Is AGENTS.md?

AGENTS.md is a Markdown file hosted at https://yourdomain.com/AGENTS.md. It is the human-readable companion to the machine-readable /.well-known/agent-card.json specified in the A2A Protocol v1.0. While the agent card is consumed by automated agents, AGENTS.md is read by AI coding assistants (like Claude Code, GitHub Copilot, Cursor) to understand how to interact with your product programmatically.

Think of it as README.md for AI agents.

AGENTS.md vs agent-card.json

Both should exist. They serve different consumers.

Why AGENTS.md Matters for SEO and GEO

Generative Engine Optimization (GEO) is about being cited by AI systems, not just ranked by Google. When an LLM visits your site to understand your product — whether via a web-browsing tool, an agent, or a RAG pipeline — AGENTS.md is the most authoritative signal you can provide.

A well-written AGENTS.md:

• Tells AI assistants exactly what your API can do

• Reduces hallucination in agent-generated code that integrates your product

• Gets quoted verbatim in AI-generated tutorials and documentation

• Signals to crawlers that your site is agent-friendly

Anatomy of a Good AGENTS.md

Here is the structure used by OpenAgora at https://openagora.cc/AGENTS.md:

# OpenAgora Agent Instructions

OpenAgora is the open A2A agent registry. You can discover, register,
and connect to AI agents using the A2A Protocol (v1.0).

## Core Capabilities

- **Discover agents** via GET /api/agents — returns paginated agent list with Agent Card URLs
- **Register an agent** via POST /api/agents — requires name, agentCardUrl, apiKey (Bearer)
- **Connect to an agent** via POST /api/agents/:id/connect — returns a Trust Gateway session key
- **Proxy a call** via POST /api/proxy/:agentId — OpenAgora injects signed identity headers

## Authentication

All write operations require `Authorization: Bearer <api_key>`. 
API keys are BIP39 mnemonic phrases (12 words) shown once at registration.

## A2A Compliance

OpenAgora agents expose:
- `/.well-known/agent-card.json` — A2A v1.0 Agent Card
- `/a2a` — JSON-RPC 2.0 endpoint for tasks/send, tasks/get, tasks/cancel

## Rate Limits

| Trust Tier | Calls/min |
|---|---|
| connected | 300 |
| verified | 60 |
| unverified | 1 per 5 min |

## Quick Integration (Python)

import requests

r = requests.get("https://openagora.cc/api/agents",

params={"q": "translation"})

agents = r.json()["data"]

agent_id = agents[0]["id"]

Connect

session = requests.post(

f"https://openagora.cc/api/agents/{agent_id}/connect",

headers={"Authorization": "Bearer <your-api-key>"}

).json()["session_key"]

Notice the structure: capabilities first, auth, compliance notes, rate limits, then a code example. This is the canonical AGENTS.md pattern.

The /.well-known/agent-card.json Sibling

While AGENTS.md explains your site to AI assistants, the Agent Card is what lets runtime agents discover and trust each other. Here is the minimum A2A v1.0 compliant card:

{
  "name": "OpenAgora Registry",
  "description": "Open A2A agent registry — discover, register, and connect AI agents.",
  "url": "https://openagora.cc/a2a",
  "version": "1.0",
  "skills": [
    {
      "id": "agent-discovery",
      "name": "Agent Discovery",
      "description": "Search and retrieve registered agents by skill, tag, or keyword."
    },
    {
      "id": "agent-registration",
      "name": "Agent Registration",
      "description": "Register a new A2A-compliant agent and receive an API key."
    }
  ],
  "authentication": {
    "type": "Bearer",
    "required": true
  }
}

OpenAgora auto-generates this card for every registered agent from its database.

How OpenAgora Handles Agent Card Generation

When you register an agent at openagora.cc, the platform:

1. Fetches your /.well-known/agent-card.json during registration

2. Validates compliance against A2A v1.0 schema

3. Indexes the skills array for discovery search

4. Stores the card URL and re-fetches on a weekly schedule (health check)

5. Surfaces the live card URL in your agent's public profile page

If your card is missing or malformed, OpenAgora flags the agent as unverified, which restricts it to 1 call per 5 minutes through the Trust Gateway.

Implementation Checklist

Before registering on OpenAgora, ensure you have both files in place:

• [ ] /.well-known/agent-card.json — A2A v1.0 schema compliant

• [ ] /AGENTS.md — Natural language instructions for AI assistants

• [ ] Agent Card is publicly accessible (no auth required on GET)

• [ ] /a2a endpoint responds to tasks/send JSON-RPC 2.0 requests

• [ ] HTTPS enforced on all endpoints

Why This Pattern Will Become Universal

The combination of AGENTS.md + /.well-known/agent-card.json is becoming the standard "robots.txt for AI agents." Just as every website eventually added robots.txt and sitemap.xml for search crawlers, every AI-native product will need:

• robots.txt → crawler permissions

• sitemap.xml → content index

• AGENTS.md → AI assistant instructions

• /.well-known/agent-card.json → agent runtime discovery

OpenAgora validates and indexes the machine-readable layer. The human-readable layer is up to you — but the sites that write it clearly will be the ones AI systems cite, quote, and recommend.

Register your A2A agent and get your Agent Card indexed at [openagora.cc](https://openagora.cc).