agent.json: telling AI agents what you offer

01What it does, and why you need it.

It lets an agent built by someone else find your service without prior knowledge of it. The agent fetches the file, reads the capabilities and skills listed, then calls the endpoint in the way the file specifies.

You need one only if you expose a service or agent for other agents to call. If you do, and the file is missing or at the wrong path, standards-compliant agents will not find you.

02Who should deal with this.

This sits with engineering, specifically whoever owns your public APIs or any AI agent you have built. Publishing the file is a small task: 1 static JSON file at 1 known path. Deciding what to put in it, and what to leave out, is an API design and security decision. For a brochure website with no API and no agent, there is nothing to publish and no checker should mark you down for it.

Level of importance

Low for most organisations today, rising for any business that intends to let AI agents transact with it rather than just read it.

03Where the name comes from.

agent.json is the discovery file defined by the Agent2Agent (A2A) protocol. A2A was announced by Google in Apr. 2025 and transferred to the Linux Foundation in Jun. 2025 for vendor-neutral governance. The protocol is now at version 1.0.0.

A2A calls the file an Agent Card. The specification describes it as a JSON document that describes the server’s identity, capabilities, skills, service endpoint URL, and how clients should authenticate and interact with it. An A2A server must make one available.

04agent.json or agent-card.json: the naming problem.

The original A2A path was /.well-known/agent.json. From version 0.3 the specification moved the card to /.well-known/agent-card.json, and that is where a version 1.0.0 client looks. The old path is deprecated but still recognised by some server libraries, which log a warning when it is used.

This matters in practice. In Jul. 2026 API Evangelist probed 22,341 domains for an Agent Card.

Domains probed

22,341

Had an Agent Card

65

Fully conformant

10

Still at the legacy path

15, sitting at /.well-known/agent.json, where a spec-compliant A2A 1.0.0 client will never look.

Their advice to those 15: serve the same document at /.well-known/agent-card.json and you are discoverable again. The safe approach is to serve the identical file at both paths.

05The /.well-known/ path.

The /.well-known/ prefix is defined by RFC 8615, an IETF standard from May 2019. It reserves a location on a domain for machine-readable metadata so that software knows where to look without guessing. The same path is used by security.txt and OpenID Connect’s openid-configuration. An agent card at /.well-known/agent-card.json follows that convention.

06What goes in the file.

The A2A discovery guide lists the key contents of an Agent Card:

Identity

Name, description and provider information.

Service endpoint

The URL for the A2A service.

Capabilities

Supported features such as streaming or push notifications.

Authentication

The required schemes, for example Bearer or OAuth2.

Skills

The tasks the agent performs, each with an id, name, description, input and output modes, and examples.

07A live example.

Cloudflare publishes an agent card for its own website at cloudflare.com/.well-known/agent.json. At the time of writing it reads:

cloudflare.com/.well-known/agent.json

{
  "name": "Cloudflare Site Agent",
  "description": "Provides machine-readable context and endpoints for AI assistants to understand Cloudflare website content.",
  "url": "https://www.cloudflare.com/.well-known/agent.json",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "skills": [
    {
      "id": "site-context",
      "name": "Site Context",
      "description": "Returns curated and markdown-first content for assistants.",
      "endpoint": "https://www.cloudflare.com/llms.txt"
    },
    {
      "id": "page-markdown",
      "name": "Page Markdown",
      "description": "Fetches markdown snapshots of site pages for citation-ready context.",
      "endpoint": "https://www.cloudflare.com/{path}.md"
    }
  ]
}

Cloudflare also publishes a top-level index at cloudflare.com/agents.json that points to the card:

cloudflare.com/agents.json

{
  "agents": [
    {
      "name": "Cloudflare Site Agent",
      "description": "Machine-readable endpoint catalog for AI assistants consuming Cloudflare website content.",
      "url": "https://www.cloudflare.com/.well-known/agent.json",
      "protocol": "a2a"
    }
  ]
}

2 things are worth noting. Cloudflare is using the older agent.json path, so a strict 1.0.0 client would not find it there. And the card describes a read-only content service, not a transactional agent: its 2 skills point to an llms.txt file and to Markdown versions of pages. This is a legitimate use of the format for a site that wants to tell assistants where its machine-readable content lives.

08How to create one.

1 · Write the file

Write the JSON file. Start from the field list above. Keep the description plain and specific. List only skills that the endpoint actually serves.

2 · Place it

Place it at /.well-known/agent-card.json. Serve the same file at /.well-known/agent.json for older clients.

3 · Content type

Serve it with Content-Type: application/json.

4 · Caching

Add HTTP caching headers. The A2A guidance notes cards change infrequently and should be cached.

5 · No secrets

Do not put secrets in it. The A2A specification strongly recommends out-of-band dynamic credentials rather than static secrets in the card. If the card itself is sensitive, protect the endpoint with authentication.

An illustrative card for a business that exposes 1 skill:

Illustrative card, 1 skill

{
  "name": "Example Bookings Agent",
  "description": "Checks availability and creates bookings for Example Ltd.",
  "url": "https://api.example.com/a2a",
  "version": "1.0.0",
  "provider": {
    "organization": "Example Ltd",
    "url": "https://www.example.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "check-availability",
      "name": "Check availability",
      "description": "Returns available slots for a given date and service.",
      "inputModes": ["text"],
      "outputModes": ["text"],
      "examples": ["Is there a slot on 12 Oct. for a 30 minute consultation?"]
    }
  ]
}

For a static site this is a file in the public folder. For a framework it is a route that returns JSON. Test it from the command line:

Test

curl -s https://www.example.com/.well-known/agent-card.json | jq .

09Things that share the name but are not the same.

Several proposals use a similar filename. They are not interchangeable and a checker that flags “agent.json” may mean any of them.

agents.json (plural)

From Wildcard AI, a separate open specification, built on OpenAPI, that describes the actions an agent can take through a site’s API. It is at version 0.1.0 and is an early-stage proposal, not an adopted web standard. It only matters for sites that expose real actions such as checkout or booking.

Agent Web Protocol

Publishes its own agent.json at the domain root, with fields such as awp_version, domain, intent and capabilities. It is unrelated to A2A.

NAIS

Network Agent Identity Standard, proposing a DNS TXT record at _agent.<domain> that points to /.well-known/agent.json.

If a report says you are missing agent.json, ask which specification it is checking against before doing anything.

10Sources.

01Official Agent2Agent (A2A) protocol site and current specification, maintained under the Linux Foundation. a2a-protocol.org/latest/
02A2A’s guide to agent discovery, listing what an Agent Card contains, the 3 discovery methods and the security guidance on credentials and caching. a2a-protocol.org/latest/topics/agent-discovery/
03A2A GitHub repository, including the normative spec/a2a.proto definition of the Agent Card and all protocol messages. github.com/a2aproject/A2A
04Background on A2A, its announcement by Google in Apr. 2025 and transfer to the Linux Foundation in Jun. 2025. en.wikipedia.org/wiki/Agent2Agent
05RFC 8615, the IETF standard that defines the /.well-known/ path prefix used for agent-card.json and similar files. www.rfc-editor.org/rfc/rfc8615.html
06Cloudflare’s live agent card for its own website, a working example of the format. www.cloudflare.com/.well-known/agent.json
07Cloudflare’s index file listing its agents and pointing to the card. www.cloudflare.com/agents.json
08API Evangelist’s Jul. 2026 probe of 22,341 domains, with the finding that 65 published a card, 10 were conformant and 15 used the legacy path. apievangelist.com/2026/07/29/most-published-agent-cards-are-not-actually-a2a/
09Field-by-field comparison of agent cards served by agents on Google Cloud Run, AWS Bedrock AgentCore and Azure Container Apps, measured Aug. 2026. dev.to/gde/cross-cloud-a2a-agent-card-field-comparison-2hod
10The A2A Python SDK change that added the deprecated /.well-known/agent.json path alongside the new one, with a warning when it is used. github.com/a2aproject/a2a-python/pull/352.diff
11Wildcard AI’s agents.json specification, built on OpenAPI, version 0.1.0. github.com/wild-card-ai/agents-json
12Plain-English explainer of agents.json, who is behind it and why AI readiness checkers flag it. weareqed.com/what-is-agents-json/
13Short explanation of how agents.json differs from llms.txt. dev.to/turva-dev/what-agentsjson-is-42ea
14The Agent Web Protocol’s separate agent.json proposal, placed at the domain root. www.agent-json.org/
15NAIS specification, a DNS plus /.well-known/agent.json discovery proposal. github.com/nais-standard/spec
16An AI visibility checker’s description of its agent.json test, useful for seeing how these files are being assessed. www.okfor.ai/checks/agent-json
17Example of an agent framework serving an A2A card, with a sample response showing the standard fields. docs.praison.ai/docs/api/praisonaiagents/a2a/get-agent-card

agent.json: the file that tells AI agents what your service can do.