A2A Agent Cards: How AI Agents Discover and Communicate With Each Other

Your AI agents are invisible to each other. Over 150 organizations -- Salesforce, SAP, ServiceNow, LangChain -- have already adopted a fix: a single JSON file that turns any agent from a black box into a discoverable, contactable service. It is called an agent card, and it is the cornerstone of Google's Agent-to-Agent (A2A) protocol.

An agent card lives at a well-known URL and declares everything another agent needs to start collaborating: name, capabilities, skills, authentication requirements, and service endpoint. One file. Complete machine-readable identity. No proprietary SDK required.

The agents that ship agent cards get found. The ones that don't get skipped.

What Is the A2A Protocol?

The Agent-to-Agent (A2A) protocol is an open standard Google released in April 2025. It solves a fundamental gap: AI agents had no universal way to discover each other, negotiate tasks, or stream results -- regardless of framework or vendor.

That gap is now closed. A2A is built entirely on web standards you already know: HTTP, JSON-RPC, and Server-Sent Events (SSE). If you have built a REST API, you already understand the mental model. The protocol defines four core capabilities:

• •Discovery -- Agents publish agent cards describing what they can do
• •Task management -- Tasks follow a defined lifecycle (submitted, working, completed, failed)
• •Collaboration -- Agents share context and instructions to coordinate work
• •UX negotiation -- Agents declare supported input and output modes (text, images, structured data)

A2A is HTTP for AI agents. HTTP gave humans a universal way to request and serve web pages. A2A gives AI agents a universal way to request and serve tasks. That parallel is not incidental -- it is architectural.

Anatomy of an Agent Card

Every A2A interaction starts here. The agent card is a JSON document served at a predictable path under your domain, and it is the first thing any client agent reads before sending a single request. Here is a complete example:

{
  "name": "Clarvia Code Review Agent",
  "description": "Automated code review agent that analyzes pull requests for security vulnerabilities, performance issues, and best practice violations.",
  "url": "https://agents.clarvia.dev/a2a",
  "version": "1.2.0",
  "protocolVersion": "0.3.0",
  "provider": {
    "organization": "Clarvia AI Services",
    "url": "https://clarvia.dev",
    "contactEmail": "agents@clarvia.dev"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["Bearer"],
    "credentials": null
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "security-review",
      "name": "Security Review",
      "description": "Scans code for OWASP Top 10 vulnerabilities, injection risks, and authentication flaws.",
      "tags": ["security", "code-review", "owasp"],
      "inputModes": ["text"],
      "outputModes": ["text"]
    },
    {
      "id": "performance-review",
      "name": "Performance Review",
      "description": "Identifies N+1 queries, memory leaks, unnecessary re-renders, and other performance anti-patterns.",
      "tags": ["performance", "optimization", "code-review"],
      "inputModes": ["text"],
      "outputModes": ["text"]
    }
  ]
}

Identity and Versioning

The name, description, and version fields tell other agents -- and humans debugging at 2 AM -- exactly what this agent does. The protocolVersion field locks the card to a specific A2A spec version (currently 0.3.0). The url field points to the live JSON-RPC endpoint where task requests land.

Provider

The provider object answers the trust question: who built this and how do I reach them? In production multi-agent systems where agents autonomously select collaborators, this is the difference between getting chosen and getting ignored.

Capabilities

The capabilities object declares what A2A features the agent supports. Setting streaming: true signals that the agent can push incremental updates via SSE as it works -- critical for long-running tasks where silence feels like failure.

Skills

Skills are the section that matters most for discovery. Each skill is a discrete capability with its own ID, description, tags, and supported input/output modes. Write skill descriptions with one audience in mind: other AI agents will read these descriptions to decide whether your agent can handle their task. Vague descriptions mean missed opportunities.

Discovery: DNS for the AI Agent Web

How does one agent actually find another? The A2A protocol borrows a pattern the web perfected decades ago -- the same convention behind robots.txt, security.txt, and openid-configuration: a well-known URL path.

As of A2A v0.3, the standard path is:

https://your-domain.com/.well-known/agent-card.json

Five steps. That is the entire discovery-to-execution flow:

1. A client agent (or orchestrator) knows a domain and fetches /.well-known/agent-card.json
2. It reads the agent card to understand capabilities, skills, and authentication requirements
3. It authenticates using the declared scheme
4. It sends a JSON-RPC task request to the url endpoint specified in the card
5. The remote agent processes the task and returns results (or streams them via SSE)

If you are already exposing an OpenAPI specification for AI agents, agent cards complement that approach perfectly. OpenAPI describes your HTTP API endpoints in granular detail; an agent card describes your agent's high-level identity and skills in the A2A protocol. Together, they give AI clients both the "what can you do" and the "how exactly do I call you."

What the Clarvia GEO Checker Checks

Most teams assume their agents are discoverable. Most are wrong. Our GEO Checker tool tests what AI agents actually see when they look for your services. For A2A agent cards specifically, the audit validates:

• •Presence at the well-known path -- Is /.well-known/agent-card.json accessible and returning a 200 status?
• •Valid JSON -- Does the response parse as well-formed JSON?
• •Required fields -- Are name, description, url, version, and protocolVersion all present?
• •Skills quality -- Are skills defined with meaningful descriptions, IDs, and tags that other agents can use for discovery?
• •Authentication declaration -- If the agent requires auth, is it clearly specified?
• •Protocol version -- Is the declared protocolVersion current?
• •HTTPS enforcement -- Is the card served over HTTPS?
• •CORS headers -- Are appropriate CORS headers set so browser-based agent clients can fetch the card?

The audit also checks complementary discovery files including health check endpoints and OpenAPI specifications -- because an agent card that points to a dead service is worse than no card at all.

Run the audit now to see how your agent scores.

How to Implement an Agent Card

Shipping an agent card takes minutes. Below are production-ready implementations in Express.js and Flask -- copy, customize the skills array, deploy.

Express.js Implementation

const express = require('express');
const app = express();
const agentCard = {   name: 'My AI Agent',   description: 'A specialized agent for data analysis and reporting.',   url: 'https://api.example.com/a2a',   version: '1.0.0',   protocolVersion: '0.3.0',   provider: {     organization: 'Example Corp',     url: 'https://example.com',   },   capabilities: {     streaming: true,     pushNotifications: false,   },   defaultInputModes: ['text'],   defaultOutputModes: ['text'],   skills: [     {       id: 'data-analysis',       name: 'Data Analysis',       description: 'Analyzes CSV, JSON, or SQL datasets and returns statistical summaries, trend detection, and anomaly reports.',       tags: ['analytics', 'data', 'statistics'],       inputModes: ['text'],       outputModes: ['text'],     },   ], };
app.get('/.well-known/agent-card.json', (req, res) => {   res.set('Access-Control-Allow-Origin', '');   res.set('Cache-Control', 'public, max-age=3600');   res.json(agentCard); });

// Also serve the legacy path for backward compatibility app.get('/.well-known/agent.json', (req, res) => {   res.redirect(301, '/.well-known/agent-card.json'); });
app.listen(3000, () => {   console.log('A2A agent running on port 3000'); }); 

from flask import Flask, jsonify, redirect
app = Flask(__name__)
agent_card = {     "name": "My AI Agent",     "description": "A specialized agent for document processing and summarization.",     "url": "https://api.example.com/a2a",     "version": "1.0.0",     "protocolVersion": "0.3.0",     "provider": {         "organization": "Example Corp",         "url": "https://example.com",     },     "capabilities": {         "streaming": True,         "pushNotifications": False,     },     "defaultInputModes": ["text"],     "defaultOutputModes": ["text"],     "skills": [         {             "id": "summarize",             "name": "Document Summarization",             "description": "Accepts long-form text or documents and returns concise summaries with key points extracted.",             "tags": ["nlp", "summarization", "documents"],             "inputModes": ["text"],             "outputModes": ["text"],         },     ], }
@app.route("/.well-known/agent-card.json") def serve_agent_card():     response = jsonify(agent_card)     response.headers["Access-Control-Allow-Origin"] = ""     response.headers["Cache-Control"] = "public, max-age=3600"     return response
@app.route("/.well-known/agent.json") def legacy_agent_card():     return redirect("/.well-known/agent-card.json", code=301)
if __name__ == "__main__":     app.run(port=5000) 

A2A vs. MCP: Complementary Protocols

A2A is not the only protocol reshaping agent interoperability. Anthropic's Model Context Protocol (MCP) tackles a related but distinct problem. They are not competitors -- they are two layers of the same stack.

Make Your Agents Discoverable

Every day without an agent card is a day your AI agents are invisible to the ecosystem forming around them. One JSON file. A well-known URL. That is the entire gap between an agent that gets discovered and one that gets bypassed.

Run the GEO Checker to find out exactly where your agents stand, or contact our team to implement A2A across your organization. The multi-agent web is not theoretical anymore -- it is shipping. The question is whether your agents will be part of it.