A2A Agent Card

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

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

{
  "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)
• Federated agent registry — сторонние каталоги агентов индексируют карточки по домену

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

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

Пример с несколькими skills:

{
  "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 — статическая публикация:

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: 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 невалидный или отсутствуют обязательные поля.