A2A Agent Card: When Your Website Needs Agent-to-Agent Discovery

A website can describe content, APIs, and tools without being an agent.

An A2A Agent Card becomes relevant only when the product operates a remote agent that another agent can discover, evaluate, and send work to. That might be a support agent that resolves tickets, a booking agent that completes reservations, or a workflow agent that creates a deliverable and returns artifacts.

If there is no live A2A service behind the card, publishing one creates a false capability signal.

This guide turns the A2A Agent Card wiki entry into an implementation and review workflow. It belongs beside API Catalog SEO, Auth.md and OAuth Metadata, Agent Skills Index, and the wider Agent SEO audit.

What The Agent Card Actually Does

The A2A specification defines the Agent Card as the public description of an A2A server. A compatible client uses it to decide whether the remote agent fits a task and how to communicate with it.

The current public discovery location is:

https://agent.example.com/.well-known/agent-card.json

The official project changed the older /.well-known/agent.json path to /.well-known/agent-card.json in the 0.3 release line. New implementations should use the current path instead of copying older examples.

An Agent Card should answer five practical questions:

Question	Card area	Operational meaning
Who operates this agent?	Name, description, provider, documentation	A client can identify the service and find human-readable support
Where does it accept work?	supportedInterfaces	A client can choose a compatible protocol binding and endpoint
What can it do?	Capabilities and skills	A client can match a task to declared behavior
What formats does it accept and return?	Input and output modes	A client can prepare messages and expected artifacts
What access is required?	Security schemes and requirements	A client can obtain credentials through the correct external flow

The card is discovery metadata. It is not the agent implementation, a permission grant, or proof that a task will succeed.

Run A Fit Check Before Publishing

Use this decision table before adding an Agent Card to a website:

Product situation	A2A fit	Better first action
Content site with articles and no callable agent	Low	Maintain crawlability, sitemap, internal links, and readable docs
SaaS with a normal REST API but no A2A task endpoint	Low	Publish API docs, OpenAPI, and an API catalog where appropriate
Product with reusable prompts or capabilities but no remote A2A server	Low to medium	Document capabilities with an Agent Skills Index
Support, booking, commerce, or workflow agent accepting inter-agent tasks	High	Implement the A2A service and publish an Agent Card
Private enterprise agent used by configured partners	High	Use direct configuration or a private registry plus access controls

Three conditions should be true before public discovery:

1. A real A2A endpoint is deployed and owned by the publisher.
2. Every advertised skill has a supported task path, input contract, and failure behavior.
3. Authentication, authorization, rate limits, logging, and human escalation are ready for external callers.

If any condition is false, fix the service first. Metadata cannot make an unsafe or incomplete agent ready.

Build A Conservative Public Card

The exact schema follows the active A2A specification and should be generated or validated with a current official SDK. A simplified public card can look like this:

{
  "name": "Example Support Agent",
  "description": "Handles order-status questions and creates support cases.",
  "version": "1.4.0",
  "documentationUrl": "https://example.com/docs/support-agent",
  "supportedInterfaces": [
    {
      "url": "https://agent.example.com/a2a/v1",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extendedAgentCard": true
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "create-support-case",
      "name": "Create a support case",
      "description": "Creates a case after the user confirms the summary.",
      "tags": ["support", "case-management"],
      "examples": ["Open a case for my damaged delivery"]
    }
  ]
}

Treat this as an editorial example, not a substitute for schema validation. Protocol fields can evolve, and the deployed service must match the card exactly.

Avoid vague skills such as “handles anything” or “automates your business.” Use task-shaped descriptions with observable boundaries. A client should be able to tell what information is required, what action may occur, and when user confirmation is needed.

Separate Public And Extended Capabilities

The public card is fetchable discovery metadata. Do not put credentials, internal hostnames, hidden tools, customer identifiers, private prompts, or privileged workflows into it.

The A2A specification supports an authenticated extended Agent Card. If capabilities.extendedAgentCard is true, an authenticated client can request a richer card after obtaining credentials through the declared security scheme.

Use the layers deliberately:

Public card	Authenticated extended card
Service identity and public documentation	Partner- or role-specific skills
Public protocol interfaces	Protected workflow details
Safe capability summary	Additional limits or configuration available after authentication
Authentication requirements	Information authorized for that authenticated client

Authentication does not replace authorization. The service must still verify scopes, tenant boundaries, task ownership, and whether the caller may perform each action. Connect the card to standards-based discovery described in Auth.md and OAuth Metadata, not to embedded secrets.

Publish, Cache, And Validate

Use this four-stage workflow:

1. Inventory. Record the live endpoint, protocol binding and version, skills, modes, security requirements, documentation owner, and escalation path.
2. Publish. Serve the public JSON over HTTPS at /.well-known/agent-card.json on the A2A server domain.
3. Protect. Keep sensitive capabilities out of the public card, enforce authentication and authorization on the service, and use an extended card only when it has a real access-control model.
4. Revalidate. Test the card after every endpoint, skill, protocol, authentication, or deployment change.

The specification recommends ordinary HTTP caching. Send a sensible Cache-Control policy and an ETag; clients can then use conditional requests rather than downloading an unchanged card repeatedly.

curl -i https://agent.example.com/.well-known/agent-card.json
curl -I https://agent.example.com/.well-known/agent-card.json

Confirm all of the following:

• The URL returns successfully over HTTPS with JSON content.
• The response validates against the current Agent Card schema.
• Every supportedInterfaces URL resolves to the advertised A2A service.
• Protocol bindings and versions match the live implementation.
• Skills describe real supported tasks, not roadmap promises.
• Security schemes match the live authorization configuration.
• No secret or internal implementation detail appears in the public card.
• Cache-Control, ETag, and update behavior are intentional.
• Documentation and human escalation routes work.

Agent Cards may also be signed with JWS. If signing is used, follow the specification’s canonicalization and verification requirements; a decorative signature field that clients cannot validate adds no trust.

What This Means For SEO Teams

An Agent Card can make a real A2A service easier for compatible clients to discover. That is an infrastructure outcome, not an SEO ranking claim.

It does not:

• guarantee Google indexing, rankings, AI citations, or referral traffic;
• make ordinary website content easier to understand by itself;
• replace a sitemap, internal links, structured content, API documentation, or technical SEO;
• turn a chatbot widget into an A2A server;
• prove that the advertised agent is safe, accurate, or authorized.

SEO and content teams still have useful responsibilities: keep the public documentation findable, link discovery assets to the correct product surface, prevent stale capability claims, and route protocol changes to engineering and security owners.

Use Technical SEO and Bot Simulator to inspect the wider public surface. Use the Agent SEO audit to inventory discovery signals, then test the A2A service separately with protocol-aware and security tests.

The Next Action

If the product has a live remote agent, schedule a joint product, engineering, security, and content review:

1. Confirm the agent really accepts A2A tasks.
2. Map each public skill to a tested workflow and owner.
3. Publish the smallest accurate public card at the current well-known URI.
4. Keep privileged capabilities behind authenticated discovery and authorization.
5. Add deployment checks so the card cannot drift from the service.

If the product does not operate an A2A server, stop at clear documentation. Do not publish an Agent Card merely to look agent-ready.

Sources

• A2A Protocol Specification
• A2A Agent Discovery Guide
• A2A Project Releases
• RFC 8615: Well-Known Uniform Resource Identifiers
• RFC 7515: JSON Web Signature
• RFC 9111: HTTP Caching

Q&A

Does every website need an A2A Agent Card?

No. It is relevant when a product operates an A2A-compatible agent that accepts tasks from other agents. Content-only sites should focus on ordinary crawlability and useful documentation.

Where should an A2A Agent Card be published?

The current A2A specification defines https://{server-domain}/.well-known/agent-card.json for public discovery. Older examples using /.well-known/agent.json are legacy patterns.

Does an Agent Card improve SEO rankings or AI citations?

No. An Agent Card is a protocol discovery document for compatible A2A clients. It does not guarantee indexing, rankings, citations, traffic, or agent adoption.