.well-known/agent-card.json

What is agent-card.json?

A JSON file in your .well-known folder that follows the A2A protocol's Agent Card format: structured metadata describing your business's identity, capabilities, and skills. Think of it as a business card written for machines, the discovery document A2A-aware agents fetch first to understand what a domain offers.

Why AI agents need it

A2A is the emerging common language for agent-to-agent communication, its own maintainers describe Agent Cards as working like OpenAPI specs for REST APIs: a calling agent fetches the card first to understand what the remote party can do. As multi-agent workflows spread (an assistant delegating "find me three local quotes" to sub-agents), the card is how your business gets discovered and described in those flows.

The business value for you

Agents get a structured capability card so they can discover what the business can do. Publishing one now positions your site for the agent-to-agent ecosystem while it is still early. The card is static, cheap to maintain, and tracks a spec with major-vendor backing.

How it came to be

Google announced the Agent2Agent protocol in April 2025 and donated it to the Linux Foundation in June 2025, making it a vendor-neutral, community-governed standard. Version 1.0, the first stable, production-ready release, landed in March 2026, adding Signed Agent Cards for cryptographic identity verification. The protocol's steering committee includes AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow.

Sources: A2A Protocol (Linux Foundation) • Linux Foundation, A2A one-year milestones (April 2026)

Adoption

Strong on the platform side, early on the website side. The Linux Foundation reported more than 150 supporting organizations by April 2026 (up from about 50 a year earlier), production deployments across multiple industries, SDKs in five languages, and 22,000+ GitHub stars. Static Agent Cards on ordinary business websites are still rare, which is the early-mover opening.

Source: Linux Foundation press release (April 9, 2026)

The technical reality

The card must follow the A2A schema (identity, capability, and skill fields with correct types), describe your business accurately, and sit at the right well-known path. The spec is still evolving post-1.0, so the file needs to track upstream changes. Our path and shape track the upstream A2A specification, and the managed subscription keeps the card current. One honest boundary: we ship the static discovery card. A live A2A server endpoint is a server-side deployment on our roadmap, and we say so plainly.

What happens if you skip it

A2A-aware agents checking your .well-known folder find nothing, so your business is invisible to structured agent-to-agent discovery and gets represented by inference, or not at all, in multi-agent workflows.