# a2a-agent-card

## What is A2A Agent Card?

**A2A Agent Card** is a JSON document at `/.well-known/agent.json` that describes an AI agent's capabilities in the **Google Agent-to-Agent (A2A) Protocol** format. It lets other AI agents and orchestrators automatically discover and invoke your agent without manual configuration.

```json
{
  "name": "Agent Ready Scanner",
  "description": "Scans websites for AI agent readiness",
  "version": "1.0.0",
  "url": "https://agentsready.io",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "scan",
      "name": "Scan URL",
      "description": "Scan a URL for agent readiness score"
    }
  ]
}
```

## Why do you need A2A Agent Card?

**Google Agent-to-Agent (A2A) Protocol** (2025) is a standard for agent-to-agent communication. If your service provides AI functionality, the Agent Card lets orchestrators (Claude, Gemini, other agents) automatically find and include your agent in composite workflows.

Without an Agent Card your agent exists "in the dark" — it can only be used through explicit manual setup.

Key scenarios:

- **Task delegation** — an orchestrator finds a specialized agent based on its card description
- **Skill discovery** — which specific tasks the agent can handle (see [Agent Skills](/glossary/agent-skills))
- **Federated agent registry** — third-party agent catalogs index cards by domain

## How do you implement A2A Agent Card?

Publish a JSON document at `/.well-known/agent.json`. Required fields: `name`, `version`, `url`. Adding `capabilities` and `skills` is strongly recommended.

**Example with multiple skills:**

```json
{
  "name": "My Data Agent",
  "description": "Provides data analysis and reporting capabilities",
  "version": "2.0.0",
  "url": "https://api.example.com/a2a",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "analyze",
      "name": "Analyze Dataset",
      "description": "Run statistical analysis on uploaded CSV",
      "inputModes": ["file", "text"],
      "outputModes": ["text", "json"]
    },
    {
      "id": "report",
      "name": "Generate Report",
      "description": "Create PDF report from analysis results",
      "inputModes": ["json"],
      "outputModes": ["file"]
    }
  ]
}
```

**Nginx — static publishing:**

```nginx
location = /.well-known/agent.json {
    alias /var/www/well-known/agent.json;
    add_header Content-Type application/json;
    add_header Access-Control-Allow-Origin *;
}
```

A2A Agent Card complements [MCP Server Card](/glossary/mcp-server-card): MCP describes tools and resources, while A2A describes the agent's high-level skills.

## How do we check A2A Agent Card?

The scanner sends a GET request to `/.well-known/agent.json` and verifies:

1. **HTTP 200** — file is accessible
2. **Valid JSON** — body parses without errors
3. **Required fields** — `name` and `version` are present
4. **Skills structure** — a `skills` array is present (at least one element with `id` and `name`)

**pass** — HTTP 200, valid JSON, required fields populated. **fail** — file is inaccessible, JSON is invalid, or required fields are missing.

[← All glossary terms](/en/glossary)