Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/a2a-agent-card

    A2A Agent Card is readable

    What it checks

    Whether the A2A Agent Card at /.well-known/agent-card.json can be read by an A2A client.

    State Verdict
    No card at agent-card.json, and nothing A2A-shaped at agent.json notApplicable
    404, or an HTML page answering for the path notApplicable
    JSON with none of the Agent Card’s keys (for example one document served at every path) notApplicable
    Body is not a JSON object fail
    A known field has the wrong type (capabilities not an object; skills, supportedInterfaces, defaultInputModes or defaultOutputModes not an array; name, description or version not a string; a skills or supportedInterfaces entry not an object; an interface url, protocolBinding or protocolVersion that is present but not a string; a 0.3-shape top-level url that is not a string) fail
    A Required field is missing warn
    A supportedInterfaces entry lacks url, protocolBinding or protocolVersion warn
    An interface URL is not an absolute https:// or wss:// URL warn
    The card sits only at the pre-1.0 path /.well-known/agent.json warn
    The card uses the 0.3 shape: a top-level url and no supportedInterfaces not judged; details.legacyShape
    Every Required field present and well-typed pass

    The audit reads the card only. It never calls the agent’s endpoint.

    Why it matters

    The reference A2A client, given a domain, sends a GET to /.well-known/agent-card.json. If the body does not parse as an Agent Card, the client has no card and cannot learn the agent’s skills or endpoint.

    Evidence

    • A2A 1.0 §8.2 names https://{server_domain}/.well-known/agent-card.json as the discovery path. §4.4.1 marks name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes and skills as Required — a2a-protocol.org/…/specification (verified 2026-10-18)
    • a2a.proto marks the same eight AgentCard fields REQUIRED, and marks url, protocol_binding and protocol_version REQUIRED on each AgentInterface — raw.githubusercontent.com/…/a2a.proto (verified 2026-10-18)
    • The discovery topic page: the client “performs an HTTP GET request” to that path — a2a-protocol.org/…/agent-discovery (verified 2026-10-18)
    • IANA registers agent-card.json as permanent, change controller Linux Foundation, 2025-08-01 — iana.org/…/well-known-uris.xhtml (verified 2026-10-18)
    • The reference SDK sets AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent-card.json'. Its resolver has no fallback to agent.json, ignores unknown fields, and raises AgentCardResolutionError on invalid JSON or a wrongly typed field. Its parse_agent_card converts a 0.3-shape card (top-level url) into a 1.0 interface, so such a card still loads — raw.githubusercontent.com/…/constants.py (verified 2026-10-18)
    • Copilot Studio: a person enters the agent’s endpoint URL, and “if your agent has a valid agent card on the standard .well-known URL, Copilot Studio automatically pulls the name and description for your agent from the card”. The same page’s note locates the card “at your agent’s endpoint + /.well-known/agent.json”: relative to the endpoint, and at the pre-1.0 file name, not at the domain root — learn.microsoft.com/…/add-agent-agent-to-agent (verified 2026-10-18)
    • A2A 0.3.0 (2025-07-30) changed the well-known URI from agent.json to agent-card.json as a breaking change — github.com/…/CHANGELOG.md (verified 2026-10-18)
    • Adoption is small. Of 20,185 hosts that answered a probe, 65 serve a card; 41 of those fail a hard structural rule and 15 sit only on the legacy path — raw.githubusercontent.com/…/2026-07-29-most-publish… (verified 2026-10-18)

    Counter-evidence: Both documented consumers are user-configured. A person types the agent’s endpoint or domain; no AI vendor documents crawling the open web for agent cards. Copilot Studio reads the card relative to the endpoint and names the pre-1.0 agent.json, so it does not confirm the domain-root agent-card.json read this audit checks.

    Limits

    • Only root-level cards are found. Frameworks often mount cards under a sub-path, such as /a2a/<agent>/.well-known/agent-card.json.
    • A card linked from an ard.json or ai-catalog.json entry is not followed.
    • Signatures are optional in A2A 1.0, so they are not judged. details.signed reports whether the card carries any.
    • An authenticated extended card (capabilities.extendedAgentCard) is not fetched.

    How it scores

    Grade: B — a published specification (A2A 1.0, Linux Foundation) on a permanently registered path, with real but small adoption. The reference SDK implements the domain-root read. The only vendor consumer, Copilot Studio, is configured by a person and reads the card relative to the endpoint, so the domain-root read is not documented vendor behaviour. The audit scores only sites that publish a card, so a site with no A2A agent loses nothing.

    • A card a client cannot load fails at high priority.
    • A card that loads but is incomplete, names an insecure interface or sits only at the old path warns.
    • A 0.3-shape card is not warned: the reference SDK converts it.

    Example finding

    {
  "name": "Booking Agent",
  "capabilities": ["streaming"],
  "skills": { "id": "book" }
}

    capabilities is an array and skills is an object. The reference SDK rejects the card.

    Sources

    Limits

    • Only root-level cards are found. Frameworks often mount cards under a sub-path, such as /a2a/<agent>/.well-known/agent-card.json.
    • A card linked from an ard.json or ai-catalog.json entry is not followed.
    • Signatures are optional in A2A 1.0, so they are not judged. details.signed reports whether the card carries any.
    • An authenticated extended card (capabilities.extendedAgentCard) is not fetched.