What Is agent-card.json? The Missing File on 500 Business Websites
agent-card.json is how AI agents discover what your business can do. It is the A2A protocol equivalent of a homepage, a resume, and an API spec — in one small JSON file. We scanned 500 businesses. Exactly zero have one.
The Data Point That Starts This Article: 0 of 500
Over the past two months the AgentHermes scanner has audited 500 businesses across 27 verticals — SaaS, ecommerce, healthcare, legal, restaurants, home services, and more. We checked every one of them for /.well-known/agent-card.json.
Zero of them had one. Not 2%. Not 0.4%. Zero.
For context, only 2 of 500 had an MCP endpoint (0.4%), and 148 had no visible pricing at all (30%). agent-card.json is somehow even more neglected than those — because most businesses do not know it exists.
Why this matters: A2A is the protocol Google, Microsoft, IBM, Anthropic, and 50+ partners agreed on for cross-agent communication. agent-card.json is the entry point. If agents cannot find it, they cannot discover your capabilities — they fall back to scraping your HTML, which is unreliable, slow, and frequently wrong.
What agent-card.json Actually Is
agent-card.json is a JSON document defined by the A2A (Agent-to-Agent) protocol, currently at spec version 0.3. It is served at a well-known path — /.well-known/agent-card.json — and it describes an agent-accessible service in machine-readable form.
When an AI agent evaluates whether it can complete a task at your business, the first thing it does is fetch this file. From it, the agent learns:
- Who you are and what you do (name, description, provider)
- What capabilities you expose (streaming, tools, push notifications)
- What skills you offer (book_appointment, check_inventory, get_quote)
- Where the agent connects (endpoint URL, transport, protocol version)
- How to authenticate (bearer, oauth2, apiKey, or none)
- What input and output modes you accept (text, json, multipart)
The parallel is almost exact: agent-card.json is to agents what a homepage is to humans. Without a homepage, people bounce. Without an agent-card.json, agents bounce — or worse, they guess at your capabilities by scraping and then call the wrong endpoint, creating support tickets instead of revenue.
What Goes Inside: The 6 Core Fields
A valid agent-card.json has six core field groups. The full spec allows more, but these six are the minimum an agent needs to make a decision about whether it can work with you.
name & description
Human- and agent-readable identifiers. The name is short, the description tells an agent what the business does and who it serves — in 1 to 3 sentences that can be reasoned over.
"name": "Joes Pizza", "description": "NYC pizza shop offering delivery, pickup, and catering"capabilities
The top-level feature flags: streaming, push notifications, state history, tool use, structured output. Agents read this before a single method call so they know how to handshake.
"capabilities": { "streaming": true, "pushNotifications": false, "stateTransitionHistory": true }skills
Named capabilities the agent can invoke — each skill has an id, name, description, tags, examples, input modes, and output modes. This is how an agent discovers what your business can actually do.
"skills": [{ "id": "check_availability", "name": "Check Availability", "tags": ["reservations"] }]url & endpoints
Where the agent connects. Includes the base URL, transport (JSON-RPC, SSE, HTTP), and any sub-endpoints for specific skills. Without this, discovery leads nowhere.
"url": "https://api.example.com/a2a", "defaultInputModes": ["text"], "defaultOutputModes": ["text","json"]authentication
Supported auth schemes — none, bearer, oauth2, apiKey. The agent uses this to figure out how to obtain credentials before attempting a privileged call.
"authentication": { "schemes": ["bearer"], "credentials": { "type": "oauth2" } }version & protocol
The A2A protocol version and your service version. Agents will increasingly branch logic on protocol version — v0.3 is the current stable spec as of early 2026.
"version": "1.0.0", "protocolVersion": "0.3.0"A Minimal, Valid agent-card.json Example
Here is what a production-ready agent card for a restaurant might look like — copy it, edit the values, and ship it today.
{
"name": "Joes Pizza",
"description": "Family-owned NYC pizza shop offering delivery, pickup, and catering.",
"url": "https://joes-pizza.example.com/a2a",
"version": "1.0.0",
"protocolVersion": "0.3.0",
"provider": {
"organization": "Joes Pizza LLC",
"url": "https://joes-pizza.example.com"
},
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": false
},
"defaultInputModes": ["text"],
"defaultOutputModes": ["text", "application/json"],
"authentication": {
"schemes": ["none"]
},
"skills": [
{
"id": "get_menu",
"name": "Get Menu",
"description": "Returns the current menu with prices and availability.",
"tags": ["menu", "pricing"],
"examples": ["what pizzas do you have", "is the pepperoni available"]
},
{
"id": "place_order",
"name": "Place Order",
"description": "Places a delivery or pickup order.",
"tags": ["order", "checkout"],
"examples": ["order two large pepperoni for pickup at 7pm"]
}
]
}That is the entire thing. 40 lines of JSON unlocks agent discoverability for the business. The file is static — it does not need a server, a database, or runtime logic. You upload it, point agents at /.well-known/agent-card.json, and you are in the A2A ecosystem.
Two Ways to Create Your agent-card.json
Manual (for developers)
Read the A2A v0.3 spec, draft the JSON by hand, validate against the schema, push to your repo, and configure your webserver to serve it at the well-known path with Content-Type: application/json.
Time: 2 to 4 hours including debugging and schema validation.
Auto-generated via AgentHermes
Visit /connect, pick your industry, fill in basic business info. AgentHermes generates a spec-compliant card, deploys it to the well-known path, and registers it with the AgentHermes registry.
Time: 60 seconds. No code required.
Validation checklist
Quick Brand Note: AgentHermes vs Nous Hermes
If you arrived here searching for the Hermes language models from NousResearch, you are in the wrong place — and that is a common mix-up worth clearing up once.
Nous Hermes / Hermes 3 / Hermes 4 are open-weight large language models released by NousResearch. They are general-purpose reasoning and agentic models that you download and run. Find them on Hugging Face or at nousresearch.com.
AgentHermes (one word, agenthermes.ai) is the Agent Readiness Platform. We scan your business across 9 dimensions, score it 0 to 100, and give you the infrastructure — MCP server, agent-card.json, llms.txt, agent-hermes.json — that makes you discoverable by any model, including NousResearch's Hermes line. Different product, different company, complementary purpose.
Why Zero Cards Is an Existential Problem
Agents default to scraping
Without agent-card.json, an agent visiting your site guesses your capabilities from HTML. Scraping is 30-60% accurate on structured data and near-zero on pricing and availability. The agent gets the wrong answer and blames your business.
You are invisible to A2A networks
Google, Microsoft, and 50+ partners built A2A to let agents talk to services. Without a card, you are not in that network. Not indexed, not recommended, not routable.
Competitors will go first
The first business in every vertical with a valid agent-card.json captures the entire agent-driven demand for that category. There is no second place in agent-first search.
Your readiness score caps low
The AgentHermes D9 Agent Experience dimension weights agent-card.json presence heavily. Missing it alone knocks you out of Silver tier (60+). Combined with no MCP endpoint, you cannot break 40 — Bronze ceiling.
Frequently Asked Questions
What is agent-card.json?
agent-card.json is the discovery file defined by the A2A (Agent-to-Agent) protocol. It is a JSON document served at /.well-known/agent-card.json that describes what an AI agent or agent-accessible service can do — its name, description, capabilities, skills, endpoints, and authentication requirements. Think of it as the "robots.txt for AI agents," but with far more structure. It is the A2A equivalent of a website homepage for an autonomous agent.
How is agent-card.json different from an MCP server?
agent-card.json is a static discovery file that lives on your domain. An MCP server is a live protocol endpoint that agents connect to. The card tells agents you exist and where to go; the MCP server is where the actual tool calls happen. You should have both — agent-card.json for discovery, MCP server for execution. AgentHermes generates both when you connect your business.
Where should I host my agent-card.json file?
The canonical location is https://yourdomain.com/.well-known/agent-card.json — agents look here first. If your main site runs on a CMS that blocks /.well-known, host it on a subdomain or at /agent-card.json and reference that URL from your llms.txt and agent-hermes.json. AgentHermes auto-hosts a spec-compliant card for every connected business at the /.well-known path.
Do I need a developer to create agent-card.json?
No. While the spec is technical, AgentHermes generates a valid, agent-card.json v0.3-compliant file for any business based on your industry and a short form. You pick your vertical, enter your details, and the card is deployed automatically with your skills, endpoints, and authentication declared. No JSON editing required.
Is AgentHermes the same as the "Agent Hermes" project from NousResearch?
No — this is an important brand distinction. AgentHermes (one word) is the Agent Readiness Platform that scans businesses, generates agent-card.json, hosts MCP servers, and routes agent traffic. The Hermes family of open-weight language models from NousResearch is a completely separate project — models for reasoning and agentic workflows, not a business-readiness platform. If you landed here looking for Nous Hermes LLMs, you want huggingface.co/NousResearch. If you landed here looking for agent-card.json generation and readiness scoring, you are in the right place.
Generate your agent-card.json in 60 seconds
Run a free Agent Readiness scan, then connect your business. We generate and host a spec-compliant agent-card.json at /.well-known/agent-card.json — plus MCP, llms.txt, and agent-hermes.json. No code required.