# a2a-agent-card

## Что такое A2A Agent Card?

**A2A Agent Card** — JSON-документ по адресу `/.well-known/agent.json`, описывающий возможности AI-агента в формате **Google Agent-to-Agent (A2A) Protocol**. Позволяет другим AI-агентам и оркестраторам автоматически обнаружить и вызвать ваш агент без ручной конфигурации.

```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"
    }
  ]
}
```

## Зачем нужна A2A Agent Card?

**Google Agent-to-Agent (A2A) Protocol** (2025) — стандарт межагентной коммуникации. Если ваш сервис предоставляет AI-функциональность, Agent Card позволяет оркестраторам (Claude, Gemini, другим агентам) автоматически найти и включить ваш агент в составные workflows.

Без Agent Card агент существует «в темноте» — его можно использовать только при явной ручной настройке.

Ключевые сценарии:

- **Делегирование задач** — оркестратор находит специализированного агента по его описанию в карточке
- **Обнаружение skills** — какие именно задачи агент умеет решать (см. [Agent Skills](/glossary/agent-skills))
- **Federated agent registry** — сторонние каталоги агентов индексируют карточки по домену

## Как реализовать A2A Agent Card?

Опубликуйте JSON по адресу `/.well-known/agent.json`. Обязательные поля: `name`, `version`, `url`. Рекомендуется добавить `capabilities` и `skills`.

**Пример с несколькими 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 — статическая публикация:**

```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 дополняет [MCP Server Card](/glossary/mcp-server-card): MCP описывает инструменты и ресурсы, A2A — высокоуровневые skills агента.

## Как мы проверяем A2A Agent Card?

Сканер делает GET-запрос на `/.well-known/agent.json` и проверяет:

1. **HTTP 200** — файл доступен
2. **Валидный JSON** — тело парсится без ошибок
3. **Обязательные поля** — присутствуют `name` и `version`
4. **Структура skills** — присутствует массив `skills` (хотя бы один элемент с `id` и `name`)

**pass** — HTTP 200, валидный JSON, обязательные поля заполнены. **fail** — файл недоступен, JSON невалидный или отсутствуют обязательные поля.

[← Все термины глоссария](/glossary)