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 what your site does, what protocols it supports, and how agents can interact with it:

{
  "schema_version": "1.0",
  "name": "Acme Store",
  "description": "Online store for widgets and gadgets",
  "url": "https://acme.com",
  "capabilities": {
    "llms_txt": true,
    "structured_data": true,
    "api": {
      "type": "REST",
      "docs": "https://acme.com/api/docs"
    }
  },
  "protocols": {
    "robots_txt": true,
    "sitemap": true,
    "llms_txt": "https://acme.com/llms.txt"
  },
  "contact": {
    "email": "ai@acme.com"
  }
}

Key Fields

schema_version

Version of the agent-card spec. Currently "1.0".

name

Human-readable name of the site or service.

description

One-line description of what the site does.

capabilities

What the site supports — llms.txt, structured data, APIs, etc.

protocols

Which discovery protocols are available (robots.txt, sitemap, llms.txt).

contact

How to reach the site owner about AI-related issues.

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.

Audit your site now

Get a free AI readiness score and generate the files your site needs.

Start Free Audit
What is agent-card.json? | w2agent