# What is agent-card.json? | w2agent

> agent-card.json is a protocol for AI agent discovery. Learn how agents use .well-known/agent-card.json to describe their capabilities.

Source: https://w2agent.dev/learn/agent-card

1. [Home](/)
2. /[Learn](/learn)
3. /agent-card.json

# 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](/learn/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](/learn/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](/learn/ai-readiness-audit). If blocked by your [robots.txt](/learn/robots-txt-ai-bots) or CDN, agents can't reach it — so check both layers.

## Related Articles

- [Agent Servers (MCP & A2A)](/learn/agent-servers) — The server infrastructure that agent-card.json points agents toward.
- [SKILL.md](/learn/skill-md) — How coding agents discover and configure connections declared in agent-card.json.
- [robots.txt for AI Bots](/learn/robots-txt-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](/)
