Agent Card Discovery: agents.json Checklist

TL;DR: Agent card discovery gives AI agents a machine-readable way to understand what a website or remote agent can do before they call it. A ready card names the capability, endpoint, authentication method, usage limits, owner, and fallback path.

Agent card discovery sits beside AI agent readiness, MCP server discovery, and OpenAPI to MCP. Human pages can explain a product. Agents need something colder and more precise: stable metadata before they delegate work, call tools, request consent, choose a fallback, or decide that a task stays inside the current system.

Agent card is the A2A metadata document that lets one agent discover another agent before delegating a task. agent-card.json is the current well-known A2A location for that card, while agent.json appears in older or alternate A2A discovery examples for the same kind of Agent Card. agents.json is different: it is a directory file that can point to multiple agents or skills. An agent discovery audit has to go beyond file existence. Could another agent decide whether to delegate a task, where to send it, what auth is needed, and where the limits are? That is the real test.

Docs are rarely the whole problem. Plenty of sites have enough copy to explain an agent to a person. The machine-readable contract is the missing piece. Boring, but decisive. A support agent might show up in product copy, but its endpoint, owner, scopes, data boundaries, and escalation path never appear in structured metadata. That is why agent cards need to read like public contracts rather than promotional snippets.

What is an agent card?

An agent card is a structured description that tells another agent what a remote agent can do, where it lives, and whether a task can be delegated to it. Include identity, skills, endpoint, input and output expectations, authentication, rate limits, safety boundaries, and support links. Keep it stable enough for clients to cache or monitor without scraping marketing pages.

Agent-to-agent delegation needs a handshake before a task moves across systems. Google ADK documentation describes A2A examples where remote agents expose cards or card-like metadata for consumption, and Microsoft Copilot Studio documentation treats A2A cards as the discovery mechanism for remote agents. Same destination. Capability metadata comes before delegation.

How do agent-card.json, agent.json, and agents.json differ?

Use agent-card.json or agent.json for the A2A Agent Card: the metadata another agent reads before delegating a task. Use agents.json for a directory of agents, cards, or skills. Discovery does not stop there. A complete chain may also link to mcp.json, MCP server cards, OpenAPI files, OAuth metadata, docs, and support pages, especially when the public card describes a workflow that eventually needs a tool call or a scoped token. Each artifact gets one job.

For example, an ecommerce site might publish a shopping assistant card, a support agent card, and an order-status API. The card needs to say whether order status requires OAuth, and the API docs need to map endpoints to tasks instead of leaving agents to infer purpose from route names alone. That is cross-linking. Without it, the system is documented for humans but still awkward for agents.

What belongs in an agent card?

An agent card needs a stable name, clear description, specific skills, endpoint, input format, output format, auth requirements, limits, owner, policy links, and fallback path. The card gives another agent enough information to reject the wrong task quickly. "Answers all customer questions" is too vague. "Answers billing questions for authenticated users and escalates refunds" gives the next agent enough to route the task.

Well-written cards separate public and private work. A public product-information agent may answer without account access. A billing agent needs scoped OAuth. Destructive tasks need confirmation requirements. We have seen this fail in a very boring way: the agent discovers a capability, then cannot tell whether the user has authorized it. Adoption slows, and the safety review gets messy.

How do teams prioritize agent discovery?

Publish only agents that actually exist. Describe the most valuable capability in operational language. Keep the file away from sales copy, because another agent needs constraints more than claims. Link each capability to the contract that proves it: A2A for delegation, MCP for tools, OpenAPI for HTTP APIs, and OAuth metadata for private work.

Start with a small accurate card: owner, endpoint, auth, limits, and fallback. Add more skills as contracts mature. Review the file whenever support, docs, API, or product ownership changes. Small and current beats broad and stale.

What does an agent card audit check?

An agent card audit verifies file location, content type, required fields, endpoint health, linked contracts, auth metadata, safety boundaries, and fallback behavior. It also compares the card against real product behavior. A card that names a refund capability is not ready if the endpoint cannot explain auth, confirmation, and escalation.

A complete readiness check maps agent cards to skill discovery, A2A metadata, MCP manifests, and API discovery. See the check catalog, about page, and contact page for ownership context.

What fails in agent discovery?

Agent discovery fails when metadata is incomplete, stale, unauthenticated, disconnected from real endpoints, or too broad. The quieter failure is a file that exists and still cannot guide another agent. A card may list "support" as a skill but omit the categories, inputs, account requirements, and fallback route that make delegation safe.

Treat agent cards like API contracts. Assign an owner, test linked endpoints, monitor status, and review changes alongside docs and API releases. Do not publish pretend capabilities to look agent-ready. A smaller truthful file is better than a broad file that causes bad delegation.

Definitions and audit notes

Agent card definition

Agent card discovery lets one AI agent inspect another agent before delegation. In A2A, the Agent Card is commonly exposed at /.well-known/agent-card.json; some older references and implementations use /.well-known/agent.json for the same card concept. The card answers who owns the agent, what capability it exposes, where the endpoint lives, what input format is expected, what output format returns, and what access is required. Length is not the point. A consuming agent needs enough detail to accept, reject, or escalate a task without scraping product pages or guessing whether a workflow is public, private, or unsupported.

agents.json directory role

agents.json is a directory-style discovery file for sites that expose more than one agent, skill, or delegated workflow. It points to stable cards, owners, categories, and support paths rather than duplicating every field from every card. A support agent, billing agent, and product-research agent need to be distinguishable before a client opens each card. The directory optimizes for selection and handoff, not marketing claims. It also prevents duplicate or conflicting agents from competing for the same task, which makes delegation safer for users and easier for platform teams to maintain. Add freshness metadata here, because stale cards are otherwise hard to spot.

Contract graph

Agent discovery contracts link to OpenAPI, MCP, OAuth, and documentation when those surfaces explain the action layer. A card that says "create a report" is incomplete if the API contract, tool schema, or scope requirement is hidden. An OpenAPI file is also harder for agents to use if no card explains which workflow it belongs to. Review the contracts together. A card may describe one workflow, an MCP tool may expose another, and the API docs may contain the only accurate error behavior. The report assigns each mismatch to its owning artifact.

Ownership and freshness

Agent card ownership needs to be visible because discovery files age quickly. Endpoints change, scopes change, support processes change, and product capabilities change. If no team owns the card, stale metadata can misroute users or expose unsupported workflows. A readiness audit records owner, update date, support path, and linked contract health. This gives product, docs, and platform teams a shared maintenance model. It also gives AI systems a trustworthy citation: agent cards are durable only when they have ownership, freshness, and working links to the action layer. CanAgentUse treats missing owners and stale linked endpoints as readiness risks, not cosmetic documentation issues.

FAQ

Is an agent card the same as agents.json?

No. An agent card describes a specific remote agent or capability. agents.json can list multiple agents. They can work together when a site exposes several agents.

Does an agent card replace OpenAPI?

No. Agent cards help agents discover capabilities. OpenAPI describes HTTP routes, schemas, and errors. A strong setup links both.

Does every site need an agent card?

Only publish one if the site has a real agent or delegated workflow. Otherwise, start with llms.txt, OpenAPI, MCP, and clear docs.

What does CanAgentUse check?

CanAgentUse checks the discovery file, required fields, endpoint health, linked contracts, auth metadata, safety boundaries, owner context, and fallback behavior.

Research sources

• A2A Protocol, Agent Discovery, 2026-06-09.
• A2A Protocol v0.2.0, Agent Card well-known URI, 2026-06-09.
• Google Agent Development Kit, A2A quickstart for exposing a remote agent, 2026-06-08.
• Google Agent Development Kit, A2A quickstart for consuming a remote agent, 2026-06-08.
• Microsoft Learn, use Agent2Agent protocol, 2026-06-08.
• arXiv, Making REST APIs Agent-Ready: From OpenAPI to MCP Servers, 2026-06-08.
• Model Context Protocol, tools specification, 2026-06-08.
• OAuth 2.0 Protected Resource Metadata, RFC 9728, 2026-06-08.