EN
Связаться
Глава 22

Опубликуйте честную Agent Card

Agent Card - это discovery-документ агента: имя, описание, interfaces, версия протокола, capabilities, security schemes, режимы данных по умолчанию и skills. Клиент читает card до вызова любых опциональных операций - и потому card является публичным лицом и обещанием агента одновременно.

Рабочая card выглядит так: она честно объявляет, что агент умеет и как с ним говорить.

TypeScript
export function createReleaseAgentCard(baseUrl: string): AgentCard {
  return {
    name: "Release Review Agent",
    description: "Проверяет снимок релиза по утверждённой политике и возвращает отчёт.",
    supportedInterfaces: [{
      url: `${baseUrl}/`,
      protocolBinding: "JSONRPC",
      tenant: "",
      protocolVersion: A2A_PROTOCOL_VERSION
    }],
    provider: {
      organization: "Developer Protocol Book",
      url: "https://example.com/developer-protocol-book"
    },
    version: "1.0.0",
    documentationUrl: `${baseUrl}/docs`,
    capabilities: {
      streaming: true,
      pushNotifications: false,
      extensions: [],
      extendedAgentCard: false
    },
    securitySchemes: {},
    securityRequirements: [],
    defaultInputModes: ["text/plain"],
    defaultOutputModes: ["text/markdown", "application/json"],
    skills: [{
      id: "review_release",
      name: "Проверка релиза",
      description: "Проверяет CI, тесты, уязвимости, обратимость миграции и готовность отката.",
      tags: ["release", "ci", "security", "rollback"],
      examples: ["Проверь релиз web-portal@2.4.0"],
      inputModes: ["text/plain"],
      outputModes: ["text/markdown", "application/json"],
      securityRequirements: []
    }],
    signatures: []
  };
}

Находят её по стандартному адресу, и клиент проходит по card сверху вниз, прежде чем что-либо отправить.

GET /.well-known/agent-card.json
Accept: application/json

Клиент выбирает supportedInterfaces[]
проверяет protocolVersion + protocolBinding
проверяет streaming/push/extendedAgentCard
согласует input/output media types
затем применяет declared security scheme

Ключевое слово в заголовке главы - "честную". Каждое поле card клиент использует для реального решения, и потому у каждого есть своя типичная ошибка дизайна.

Поле · Использует клиент · Ошибка дизайна

  • supportedInterfaces - URL, binding, version; Указать localhost в production
  • capabilities - Можно ли streaming/push/extended card; Объявить feature без реализации
  • skills - Выбор агента и примеры задач; Маркетинговое "делает всё"
  • modes - Media negotiation; Вернуть неоговоренный формат
  • security - Как аутентифицировать request; Секрет в самой card
  • signatures - Проверка происхождения card; Считать подпись authorization

Разберём самые опасные. supportedInterfaces даёт URL, binding и версию - и указать здесь localhost в продакшене значит сломать всех клиентов. capabilities объявляет streaming/push/extended card - объявить фичу без реализации хуже, чем не объявить вовсе. skills - это выбор агента и примеры задач, а не маркетинговое "делает всё". А подпись в signatures проверяет происхождение card, но сама по себе не является authorization.

Card является обещанием совместимости. Version control нужен не только коду агента. Изменение семантики skill, требуемого input mode или security requirement может быть breaking-изменением даже при том же HTTP-endpoint. Меняете смысл - меняйте версию.

Card объявляет, как с агентом говорить. Сам разговор переносится сообщениями - и здесь A2A аккуратно отделяет общение от результата работы.

Ссылки