What is agent-card.json?

A machine-readable file that tells AI agents what your site can do. Like a business card for the agentic web.

The Agentic Web

The web is shifting from humans browsing pages to AI agents acting on behalf of users. These agents need to discover what services a website offers, what APIs are available, and how to interact with them — automatically, without human guidance.

agent-card.json is a proposed protocol for this discovery. Served at /.well-known/agent-card.json, it describes your site's capabilities in a format AI agents can parse and act on.

The Schema

An agent-card.json file describes the agent's identity, what it can do (skills), and how to connect to it (supportedInterfaces). This is the A2A v1.0 shape:

{
  "name": "Acme Store",
  "description": "Online store for widgets and gadgets",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://acme.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Acme Corp",
    "url": "https://acme.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "product-search",
      "name": "Product Search",
      "description": "Search for products by name, category, or SKU",
      "tags": ["search", "products"]
    }
  ]
}

Key Fields

name

Required. Human-readable name of the agent or service.

description

Required. One-line description of what the agent does.

version

Required. Version of the agent (e.g. "1.0.0").

supportedInterfaces

Required, non-empty. Each entry has "url" (the A2A endpoint), "protocolBinding" (e.g. "JSONRPC", "GRPC", "HTTP+JSON") and "protocolVersion" (e.g. "1.0"). The first entry is the preferred one.

capabilities

Required object. Optional flags such as "streaming" and "pushNotifications".

defaultInputModes

Required. Media types the agent accepts (e.g. "text/plain").

defaultOutputModes

Required. Media types the agent returns (e.g. "text/plain", "application/json").

skills

Required. Discrete actions the agent can perform. Each skill has an id, name, description, and tags.

provider

Optional. Who operates the agent — "organization" and "url".

How Agents Discover It

AI agents follow the .well-known convention (RFC 8615). When an agent wants to interact with your site, it checks:

  1. https://example.com/.well-known/agent-card.json
  2. Falls back to checking for llms.txt, robots.txt, and sitemap.xml
  3. Uses the agent-card capabilities to determine how to interact

The .well-known path is significant: it's the same convention used by Let's Encrypt (ACME), OpenID Connect, and other machine-to-machine protocols. It signals that the file is meant for automated consumption, not human browsing.

Relationship to Other Protocols

vs. robots.txt

robots.txt controls access (can/can't crawl). agent-card.json describes capabilities (what's available). They're complementary.

vs. llms.txt

llms.txt provides content for AI consumption. agent-card.json provides metadata about the site's AI capabilities. Use both.

vs. OpenAPI

OpenAPI describes API endpoints in detail. agent-card.json is higher-level — it tells agents that an API exists and where to find the docs.

vs. ai-plugin.json

OpenAI's ChatGPT plugin manifest. agent-card.json is vendor-neutral and covers discovery beyond just ChatGPT plugins.

Getting Started

Publish an agent-card.json only if your site runs an A2A agent. w2agent can generate one from your site's capabilities when you give it that agent's endpoint with --a2a-endpoint. Without an endpoint it generates no card, because a card pointing at your homepage is a stub. Run an audit to check the card you publish.

A2A Protocol Compliance

agent-card.json is the discovery mechanism for Google's Agent-to-Agent (A2A) protocol — an open standard for agents communicating with each other. When an orchestrator agent (like Gemini or Claude) wants to delegate a task to a specialized agent, it looks up the agent-card.json to find what that agent can do and how to call it.

A2A v1.0 agent cards use the supportedInterfaces field to declare where and how to call the agent. The most common binding is JSONRPC — JSON-RPC 2.0 over HTTP, the binding used by w2agent's agent servers.

Older A2A v0.3 cards put the endpoint in a top-level url with preferredTransport. The audit still recognizes them but scores them partial until they add the v1.0 fields. A card whose only interface URL is your homepage is flagged as a stub and also scores partial: the homepage is not an A2A endpoint, so agents can't call it.

Agents that don't expose an agent-card.json are invisible to A2A orchestrators, regardless of how capable their underlying API is. This makes agent-card.json the most important single file for sites that want to participate in multi-agent workflows — more impactful than llms.txt for that specific use case.

Validating Your Agent Card

A valid agent-card.json must be served at the exact path /.well-known/agent-card.json with Content-Type application/json. Missing either breaks A2A discovery silently.

# Verify the file is accessible and valid JSON
curl -s https://your-site.com/.well-known/agent-card.json | jq .

# Check Content-Type header
curl -sI https://your-site.com/.well-known/agent-card.json | grep content-type

# Expected: content-type: application/json

w2agent's Agent Discovery category checks this path as part of the AI readiness audit. If blocked by your robots.txt or CDN, agents can't reach it — so check both layers.

Related Articles

  • Agent Servers (MCP & A2A) — The server infrastructure that agent-card.json points agents toward.
  • SKILL.md — How coding agents discover and configure connections declared in agent-card.json.
  • robots.txt for AI Bots — Ensure your agent-card.json path isn't blocked before agents can fetch it.

Score your site now

Get your free w2agent score and generate the files your site needs.

Get Your Score
What is agent-card.json? | w2agent