Довідник схеми · 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": "Агент GeoSpatial Route Planner"
Що робить агент і коли інший агент повинен його викликати.
Це основний сигнал у вільній формі як для інтеграторів-людей, так і для маршрутизаторів на основі 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 випущено провайдером.
Кожен підпис містить захищений заголовок JWS у форматі base64url і значення підпису, обчислене над канонізованою за 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 у валідатор, щоб точно побачити, які поля потребують уваги.
З блогу
Compare A2A vs MCP: what each protocol connects, where they overlap, and why production AI agent systems often use both for tools and agent collaboration.
9 min readЧитати посібникHow-toLearn how to create an agent.json file for A2A v1.0, including required Agent Card fields, the well-known URL, response headers, and common mistakes.
11 min readЧитати посібникIntegrationLearn how to publish an A2A Agent Card from Google ADK, LangGraph, CrewAI, or Semantic Kernel by mapping framework concepts to standard discovery fields.
10 min readЧитати посібникСтатті публікуються англійською мовою.