Справочник по схеме · 14 fieldsA2A v1.0
Agent Card — это стандартизированный JSON-документ, который сообщает клиентам A2A, кто такой агент, где к нему обратиться, что он умеет, и как защищён доступ. Этот справочник охватывает каждое поле v1.0 с типами, требованиями, примерами, и ошибками, которые валидаторы обнаруживают чаще всего.
Как работает обнаружение
Клиент A2A получает Agent Card по well-known URI, оценивает навыки, возможности и требования безопасности применительно к своей задаче, а затем вызывает предпочитаемый интерфейс — первую запись в supportedInterfaces. Если capabilities.extendedAgentCard равно true, аутентифицированные клиенты могут запросить более полную Agent Card через операцию GetExtendedAgentCard.
Спецификация регистрирует /.well-known/agent-card.json как стандартное расположение. Более старые развёртывания v0.x использовали /.well-known/agent.json, поэтому наш валидатор проверяет оба варианта.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Справочник полей
Флаги обязательности следуют определениям protobuf v1.0 из официальной спецификации. Якорные ссылки делают каждое поле цитируемым в issue, ревью и выводе CI.
Человекочитаемое имя агента.
Отображается в списках маркетплейсов и клиентских интерфейсах. Делайте его коротким и конкретным — клиенты используют его как основную метку при сравнении агентов-кандидатов.
Частая ошибка: Использование общего имени вроде «AI Assistant», которое не даёт системам маршрутизации ничего, на основе чего можно различать агентов.
"name": "Агент планировщика геопространственных маршрутов"
Что делает агент и когда другой агент должен его вызывать.
Это основной сигнал в свободной форме как для интеграторов-людей, так и для маршрутизаторов на основе LLM, решающих, подходит ли ваш агент для задачи. Укажите область задачи, ключевые возможности и границы.
Частая ошибка: Однострочные описания короче 20 символов. Маршрутизаторы не могут сопоставить то, что вы не описали.
"description": "Обеспечивает расширенное планирование маршрутов, анализ трафика и услуги по созданию пользовательских карт."
Упорядоченный список конечных точек и протокольных привязок. Первая запись является предпочитаемой.
Новое в v1.0: заменяет старые поля верхнего уровня url, preferredTransport и additionalInterfaces. Каждая запись объявляет собственный url, protocolBinding (JSONRPC, GRPC, HTTP+JSON или пользовательский URI привязки), protocolVersion, и опциональный ключ маршрутизации арендатора — так один агент может одновременно обслуживать несколько версий протокола и транспортов.
Частая ошибка: Объявление привязки, которую сервер фактически не обслуживает по этому URL — спецификация требует, чтобы каждая запись была точной.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Кто управляет агентом: организация и веб-сайт.
Сигнал доверия для маркетплейсов и корпоративных аудитов. В v1.0 поле name переименовано в organization; url обязателен внутри объекта, если он присутствует.
Частая ошибка: Продолжение использования provider.name (до v1.0). Валидаторы, читающие Agent Card v1.0, не распознают это поле.
"provider": {
"organization": "Пример Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Версия самого агента, а не протокола.
Позволяет клиентам обнаруживать существенные изменения Agent Card и повторно оценивать совместимость. Следуйте собственной схеме релизов, обычно semver.
Частая ошибка: Путать это с версией протокола A2A — она теперь находится в каждой записи supportedInterfaces.
"version": "1.2.0"
Ссылка на человекочитаемую документацию агента.
Даёт интеграторам место для чтения полного контракта API, ограничений частоты запросов, и условий, которым не место в документе обнаружения.
Частая ошибка: Указание на маркетинговую домашнюю страницу вместо технической документации.
"documentationUrl": "https://docs.example.com/agent"
Флаги функций протокола: streaming, pushNotifications, extensions, extendedAgentCard.
Клиенты НЕ ДОЛЖНЫ вызывать функции, которые вы не объявили — необъявленные вызовы потоковой передачи возвращают ошибки. extendedAgentCard: true объявляет о более полной аутентифицированной Agent Card через операцию GetExtendedAgentCard. В v1.0 удалено stateTransitionHistory.
Частая ошибка: Объявление streaming: true, когда у сервера нет конечной точки потоковой передачи. Клиенты вызовут её и получат сбой.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Именованные схемы аутентификации: ключ API, HTTP-аутентификация, OAuth 2.0, OpenID Connect, или взаимный TLS.
Каждая именованная схема оборачивает один конкретный объект схемы (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Клиенты узнают отсюда, как проходить аутентификацию — сами учётные данные всегда получаются вне канала.
Частая ошибка: Встраивание реального ключа API или токена в Agent Card. Agent Card — это публичный документ.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Какие объявленные схемы (и области действия) требуются для вызова агента.
Каждая запись сопоставляет имя схемы из securitySchemes с необходимыми областями действия, отражая паттерн требований безопасности OpenAPI. Полностью опустите оба поля для намеренно публичных агентов.
Частая ошибка: Объявление securitySchemes без требований security, из-за чего клиентам приходится гадать, применяется ли аутентификация.
"security": [{ "google": ["openid", "profile", "email"] }]Типы медиа, которые агент принимает во всех навыках.
Стандартные MIME-типы, такие как text/plain, application/json или image/png. Отдельные навыки могут переопределить их своими собственными inputModes.
Частая ошибка: Пропуск поля. Оно обязательно в v1.0 — клиентам оно нужно для формирования запросов.
"defaultInputModes": ["application/json", "text/plain"]
Типы медиа, которые агент возвращает во всех навыках.
Сообщает вызывающим, ожидать ли текст, структурированный JSON, изображения или файлы. Навыки могут переопределить это по-навыково с помощью outputModes.
Частая ошибка: Указание только text/plain, когда агент фактически возвращает структурированные артефакты.
"defaultOutputModes": ["application/json", "image/png"]
Конкретные возможности, в которых агент, вероятно, будет успешен.
Каждый навык требует id, name, description, и tags; examples, режимы для конкретного навыка, и безопасность для конкретного навыка необязательны. Навыки — это единица обнаружения — маршрутизаторы сопоставляют задачи с ними, поэтому ограничивайте каждый одной границей задачи.
Частая ошибка: Навыки без тегов. Теги стали обязательными в v1.0 и определяют сопоставление на уровне навыков.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Оптимизатор маршрутов с учетом трафика",
"description": "Рассчитывает оптимальные маршруты движения, используя данные о пробках в реальном времени...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Спланируйте маршрут от А до Б, избегая платных дорог."]
}]Подписи JSON Web, доказывающие, что Agent Card выпущена провайдером.
Каждая подпись содержит защищённый base64url заголовок JWS и значение подписи, вычисленное над канонизированной по RFC 8785 (JCS) Agent Card. Клиентам СЛЕДУЕТ проверять хотя бы одну подпись перед тем, как доверять Agent Card, полученной из открытого веба.
Частая ошибка: Подписание карточки с последующим редактированием любого поля — даже незначительные для пробелов изменения значений делают JWS недействительной.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL значка, представляющего агента.
Используется каталогами и клиентскими интерфейсами. Раздавайте его по HTTPS со стабильного расположения.
Частая ошибка: Ссылка на значок на другом, ненадёжном домене, который может измениться в обход вашего листинга.
"iconUrl": "https://agent.example.com/icon.png"
Миграция версии
Если ваша Agent Card всё ещё содержит верхнеуровневые url или preferredTransport, она предшествует v1.0. Валидатор автоматически помечает каждое из этих полей.
| Поле v0.x | Замена v1.0 | Почему изменилось |
|---|---|---|
| url | supportedInterfaces[0].url | Предпочитаемая конечная точка теперь просто первая запись интерфейса. |
| preferredTransport | supportedInterfaces[] ordering | Предпочтение выражается порядком массива вместо отдельного поля. |
| additionalInterfaces | supportedInterfaces[] | Все интерфейсы находятся в одном упорядоченном массиве. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Каждый интерфейс объявляет собственную версию протокола, обеспечивая поддержку нескольких версий. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Перемещено в объект capabilities; RPC переименован в GetExtendedAgentCard. |
| provider.name | provider.organization | Переименовано для ясности. |
| capabilities.stateTransitionHistory | — removed | Не является частью v1.0; при необходимости смоделируйте эквивалентное поведение как расширение. |
Шаблонный код
Добавьте эти интерфейсы в клиент, сервер или проверку CI, чтобы разбирать и создавать Agent Card с типовой безопасностью. Они отражают определения protobuf из официального репозитория спецификации, в camelCase-форме JSON, в которой публикуются Agent Card.
Собираете Agent Card вручную? Генератор создаёт именно эту структуру.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Целостность
Поскольку Agent Card получают из открытого веба, v1.0 формализует подписание: Agent Card (без поля signatures и значений по умолчанию) канонизируется по RFC 8785 JSON Canonicalization, затем подписывается как JWS. Клиентам следует проверять хотя бы одну подпись — через заголовок kid/jku или доверенное хранилище ключей — прежде чем действовать на основе Agent Card. Несколько подписей поддерживают ротацию ключей.
Раздавайте Agent Card по адресу /.well-known/agent-card.json через HTTPS.
Каждая запись supportedInterfaces доступна и использует заявленную привязку.
Навыки имеют обязательные теги и описания с чёткими границами задач.
Объявленные возможности соответствуют серверу — необъявленные функции должны возвращать ошибки, объявленные должны работать.
securitySchemes описывает, как проходить аутентификацию; учётные данные нигде в Agent Card не появляются.
version повышается при каждом изменении содержимого Agent Card.
Агент поддержки клиентов с OAuth 2.0, потоковой передачей и push-уведомлениями — присутствуют все обязательные поля. Больше паттернов доступно в библиотеке примеров.
{
"name": "Агент поддержки клиентов",
"description": "Отвечает на вопросы службы поддержки клиентов, извлекает контекст заказа и передает нерешенные проблемы человеческой команде.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Пример Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Решение запроса в службу поддержки клиентов",
"description": "Классифицирует запрос на поддержку клиентов, собирает необходимый контекст, предлагает решение и передает на более высокий уровень, когда доверие низкое.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Помогите мне вернуть заказ."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Частые вопросы
Изменения версии, поля обнаружения, и детали публикации, которые определяют, пройдёт ли Agent Card проверку.
v1.0 объединила url, preferredTransport и additionalInterfaces в один упорядоченный массив supportedInterfaces, где каждая запись объявляет собственные url, protocolBinding и protocolVersion. supportsAuthenticatedExtendedCard перемещено в capabilities.extendedAgentCard, provider.name стало provider.organization, теги навыков стали обязательными, и подписи Agent Card JWS были формализованы с канонизацией RFC 8785.
Нет. Agent Card — это документ обнаружения для агента. Он суммирует идентичность, интерфейсы, возможности, навыки, режимы, провайдера и метаданные безопасности, тогда как полная схема API описывает детальные форматы запросов и ответов. Она играет для сервиса ту же роль, что README или обзор OpenAPI: достаточно, чтобы решить, стоит ли его вызывать и как.
name, description, supportedInterfaces, skills (с тегами), defaultInputModes, defaultOutputModes, capabilities, provider, и метаданные безопасности. Системы маршрутизации сопоставляют задачи с вашим description и тегами навыков, затем используют интерфейсы и возможности для планирования фактического вызова.
Публикуйте только те навыки, которые безопасны для неаутентифицированного обнаружения. Если нужна более полная приватная Agent Card, установите capabilities.extendedAgentCard в true и раскрывайте чувствительные навыки через аутентифицированную операцию GetExtendedAgentCard.
По well-known URI https://{ваш-домен}/.well-known/agent-card.json, с типом содержимого application/a2a+json (application/json также работает на практике). Более ранние реализации использовали /.well-known/agent.json, поэтому публикация обоих во время перехода — прагматичный выбор.
Примените схему на практике
Сгенерируйте Agent Card в формате v1.0 на основе деталей вашего сервиса, или вставьте существующую Agent Card в валидатор, чтобы точно увидеть, какие поля требуют внимания.