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 (interfaces):

{
  "id": "acme/store",
  "name": "Acme Store",
  "description": "Online store for widgets and gadgets",
  "url": "https://acme.com",
  "provider": {
    "name": "Acme Corp",
    "url": "https://acme.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "product-search",
      "name": "Product Search",
      "description": "Search for products by name, category, or SKU"
    }
  ],
  "interfaces": [
    {
      "type": "streamable-http",
      "url": "https://acme.com/mcp"
    }
  ]
}

Key Fields

id

Unique identifier for the agent (e.g. "acme/store"). Scoped to the provider.

name

Human-readable name of the agent or service.

description

One-line description of what the agent does.

url

The agent's canonical URL.

provider

Who operates the agent — requires "name" and "url" sub-fields.

capabilities

Transport capabilities. "streaming" indicates SSE/stream support; "pushNotifications" for webhooks.

skills

Array of discrete actions the agent can perform. Each skill has an id, name, and description.

interfaces

Transport endpoints. Each entry has a "type" (e.g. "streamable-http") 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

w2agent generates an agent-card.json based on your site's actual capabilities. It detects which protocols you support, what APIs are available, and creates the file automatically. Run an audit to see what your agent card would look like.

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-compliant agent cards use the interfaces field to declare transport types. The most common is streamable-http — an HTTP endpoint that supports both standard request/response and streaming via SSE. This is the same transport used by w2agent's agent servers.

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 Protocols 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