Довідник схеми · 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 у валідатор, щоб точно побачити, які поля потребують уваги.