Odniesienie do schematu · 14 fieldsA2A v1.0
Agent Card to standaryzowany dokument JSON, który informuje klientów A2A, kim jest agent, gdzie się z nim skontaktować, co potrafi zrobić, i jak chroniony jest dostęp. To odniesienie obejmuje każde pole v1.0 z typami, wymaganiami, przykładami, oraz błędami, które walidatory wykrywają najczęściej.
Jak działa wykrywanie
Klient A2A pobiera Agent Card z well-known URI, ocenia umiejętności, możliwości, i wymagania bezpieczeństwa względem swojego zadania, a następnie wywołuje preferowany interfejs — pierwszy wpis w supportedInterfaces. Jeśli capabilities.extendedAgentCard ma wartość true, uwierzytelnieni klienci mogą zażądać bogatszej Agent Card poprzez operację GetExtendedAgentCard.
Specyfikacja rejestruje /.well-known/agent-card.json jako standardową lokalizację. Starsze wdrożenia v0.x używały /.well-known/agent.json, dlatego nasz walidator sprawdza oba.
# 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" }
],
...
}Odniesienie pól
Flagi wymagalności są zgodne z definicjami protobuf v1.0 w oficjalnej specyfikacji. Linki kotwiczące sprawiają, że każde pole można cytować z issues, recenzji, i wyników CI.
Czytelna dla człowieka nazwa agenta.
Wyświetlana na listach marketplace i w interfejsach klienta. Zachowaj ją krótką i konkretną — klienci używają jej jako głównej etykiety przy porównywaniu kandydujących agentów.
Częsty błąd: Użycie ogólnej nazwy jak "AI Assistant", która nie daje systemom routingu niczego do rozróżnienia.
"name": "Agent planowania tras geoprzestrzennych"
Co robi agent i kiedy inny agent powinien go wywołać.
To główny sygnał tekstowy zarówno dla integratorów-ludzi, jak i routerów opartych na LLM decydujących, czy Twój agent pasuje do zadania. Podaj domenę zadania, kluczowe możliwości, i granice.
Częsty błąd: Jednowierszowe opisy poniżej 20 znaków. Routery nie mogą dopasować tego, czego nie opisujesz.
"description": "Zapewnia zaawansowane planowanie tras, analizę ruchu i usługi generowania niestandardowych map."
Uporządkowana lista endpointów i wiązań protokołu. Pierwszy wpis jest preferowany.
Nowość w v1.0: zastępuje stare pola najwyższego poziomu url, preferredTransport, i additionalInterfaces. Każdy wpis deklaruje własny url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, lub niestandardowy URI wiązania), protocolVersion, i opcjonalny klucz routingu najemcy — dzięki czemu jeden agent może obsługiwać wiele wersji protokołu i transportów jednocześnie.
Częsty błąd: Deklarowanie wiązania, którego serwer faktycznie nie obsługuje pod tym URL — specyfikacja wymaga, aby każdy wpis był dokładny.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Kto obsługuje agenta: organizacja i strona internetowa.
Sygnał zaufania dla marketplace'ów i audytów korporacyjnych. v1.0 zmieniło nazwę pola name na organization; url jest wymagane wewnątrz obiektu, gdy jest obecne.
Częsty błąd: Dalsze używanie provider.name (sprzed v1.0). Walidatory czytające Agent Card v1.0 go nie rozpoznają.
"provider": {
"organization": "Przykład Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Wersja samego agenta, nie protokołu.
Pozwala klientom wykryć, kiedy Agent Card uległa istotnej zmianie i ponownie ocenić zgodność. Postępuj zgodnie z własnym schematem wydań, zazwyczaj semver.
Częsty błąd: Mylenie tego z wersją protokołu A2A — ta znajduje się teraz w każdym wpisie supportedInterfaces.
"version": "1.2.0"
Link do czytelnej dla człowieka dokumentacji agenta.
Daje integratorom miejsce do przeczytania pełnej umowy API, limitów szybkości, i warunków, które nie należą do dokumentu wykrywania.
Częsty błąd: Wskazywanie na stronę główną marketingową zamiast dokumentacji technicznej.
"documentationUrl": "https://docs.example.com/agent"
Flagi funkcji protokołu: streaming, pushNotifications, extensions, extendedAgentCard.
Klienci NIE MOGĄ wywoływać funkcji, których nie zadeklarowałeś — niezadeklarowane wywołania streamingu zwracają błędy. extendedAgentCard: true ogłasza bogatszą uwierzytelnioną Agent Card poprzez operację GetExtendedAgentCard. v1.0 usunęło stateTransitionHistory.
Częsty błąd: Deklarowanie streaming: true, gdy serwer nie ma endpointu streamingu. Klienci go wywołają i zawiodą.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Nazwane schematy uwierzytelniania: klucz API, uwierzytelnianie HTTP, OAuth 2.0, OpenID Connect, lub wzajemne TLS.
Każdy nazwany schemat obejmuje jeden konkretny obiekt schematu (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Klienci odkrywają stąd, jak się uwierzytelnić — same poświadczenia są zawsze uzyskiwane poza pasmem.
Częsty błąd: Osadzanie rzeczywistego klucza API lub tokenu w Agent Card. Agent Card jest dokumentem publicznym.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Które zadeklarowane schematy (i zakresy) są wymagane do wywołania agenta.
Każdy wpis mapuje nazwę schematu z securitySchemes na potrzebne zakresy, odzwierciedlając wzorzec wymagań bezpieczeństwa OpenAPI. Pomiń oba pola całkowicie dla celowo publicznych agentów.
Częsty błąd: Deklarowanie securitySchemes, ale bez wymagań security, pozostawiając klientom zgadywanie, czy uwierzytelnianie jest wymuszane.
"security": [{ "google": ["openid", "profile", "email"] }]Typy mediów, które agent akceptuje we wszystkich umiejętnościach.
Standardowe typy MIME, takie jak text/plain, application/json, lub image/png. Poszczególne umiejętności mogą nadpisywać własnymi inputModes.
Częsty błąd: Pominięcie pola. Jest wymagane w v1.0 — klienci potrzebują go do kształtowania żądań.
"defaultInputModes": ["application/json", "text/plain"]
Typy mediów, które agent zwraca we wszystkich umiejętnościach.
Mówi wywołującym, czy spodziewać się prozy, ustrukturyzowanego JSON, obrazów, czy plików. Umiejętności mogą nadpisywać per umiejętność za pomocą outputModes.
Częsty błąd: Wymienianie tylko text/plain, gdy agent faktycznie zwraca ustrukturyzowane artefakty.
"defaultOutputModes": ["application/json", "image/png"]
Konkretne umiejętności, w których agent prawdopodobnie odniesie sukces.
Każda umiejętność wymaga id, name, description, i tags; examples, tryby per umiejętność, i bezpieczeństwo per umiejętność są opcjonalne. Umiejętności są jednostką wykrywania — routery dopasowują do nich zadania, więc ogranicz każdą do jednej granicy zadania.
Częsty błąd: Umiejętności bez tagów. Tagi stały się wymagane w v1.0 i napędzają dopasowywanie na poziomie umiejętności.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Optymalizator trasy uwzględniający ruch",
"description": "Oblicza optymalne trasy jazdy na podstawie ruchu drogowego w czasie rzeczywistym...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Zaplanuj trasę z punktu A do punktu B, unikając opłat drogowych."]
}]Podpisy JSON Web dowodzące, że Agent Card została wydana przez dostawcę.
Każdy podpis niesie chroniony nagłówek JWS base64url i wartość podpisu, obliczoną na kanonizowanej wg RFC 8785 (JCS) Agent Card. Klienci POWINNI zweryfikować co najmniej jeden podpis przed zaufaniem Agent Card pobranej z otwartego internetu.
Częsty błąd: Podpisanie karty, a następnie edytowanie dowolnego pola — nawet nieznaczące dla białych znaków zmiany wartości unieważniają JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL do ikony reprezentującej agenta.
Używane przez katalogi i interfejsy klienta. Serwuj ją przez HTTPS ze stabilnej lokalizacji.
Częsty błąd: Łączenie z ikoną na innej, niezaufanej domenie, która może zmienić się bez ostrzeżenia pod Twoim wpisem.
"iconUrl": "https://agent.example.com/icon.png"
Migracja wersji
Jeśli Twoja Agent Card wciąż ma url lub preferredTransport najwyższego poziomu, poprzedza ona v1.0. Walidator automatycznie oznacza każde z nich.
| Pole v0.x | Zamiennik v1.0 | Dlaczego się zmieniło |
|---|---|---|
| url | supportedInterfaces[0].url | Preferowany endpoint jest teraz po prostu pierwszym wpisem interfejsu. |
| preferredTransport | supportedInterfaces[] ordering | Preferencja jest wyrażana przez kolejność tablicy zamiast osobnego pola. |
| additionalInterfaces | supportedInterfaces[] | Wszystkie interfejsy znajdują się w jednej uporządkowanej tablicy. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Każdy interfejs deklaruje własną wersję protokołu, umożliwiając obsługę wielu wersji. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Przeniesione do obiektu capabilities; RPC zostało przemianowane na GetExtendedAgentCard. |
| provider.name | provider.organization | Przemianowane dla jasności. |
| capabilities.stateTransitionHistory | — removed | Nie jest częścią v1.0; w razie potrzeby zamodeluj równoważne zachowanie jako rozszerzenie. |
Szablon
Umieść te interfejsy w kliencie, serwerze, lub kontroli CI, aby analizować i tworzyć Agent Cards z bezpieczeństwem typów. Odzwierciedlają one definicje protobuf w oficjalnym repozytorium specyfikacji, w postaci JSON camelCase, w jakiej publikowane są Agent Card.
Budujesz zamiast tego Agent Card ręcznie? Generator tworzy dokładnie tę formę.
// 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> }Integralność
Ponieważ Agent Cards są pobierane z otwartego internetu, v1.0 formalizuje podpisywanie: Agent Card (bez pola signatures i wartości domyślnych) jest kanonizowana za pomocą RFC 8785 JSON Canonicalization, a następnie podpisywana jako JWS. Klienci powinni zweryfikować co najmniej jeden podpis — poprzez nagłówek kid/jku lub zaufany magazyn kluczy — zanim podejmą działanie na podstawie Agent Card. Wiele podpisów wspiera rotację kluczy.
Serwuj Agent Card na /.well-known/agent-card.json przez HTTPS.
Każdy wpis supportedInterfaces jest osiągalny i mówi zadeklarowanym wiązaniem.
Umiejętności mają wymagane tagi oraz opisy z jasnymi granicami zadań.
Zadeklarowane możliwości pasują do serwera — niezadeklarowane funkcje muszą zwracać błędy, zadeklarowane muszą działać.
securitySchemes opisuje, jak się uwierzytelnić; żadne poświadczenia nie pojawiają się nigdzie w Agent Card.
version jest zwiększane za każdym razem, gdy zmienia się zawartość Agent Card.
Agent obsługi klienta z OAuth 2.0, streamingiem, i powiadomieniami push — obecne wszystkie wymagane pola. Więcej wzorców znajduje się w bibliotece przykładów.
{
"name": "Agent Obsługi Klienta",
"description": "Odpowiada na pytania obsługi klienta, pobiera kontekst zamówienia i przekazuje nierozwiązane problemy zespołowi ludzkiemu.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Przykładowa firma",
"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": "Rozwiąż żądanie obsługi klienta",
"description": "Klasyfikuje żądanie obsługi klienta, zbiera potrzebny kontekst, proponuje rozwiązanie i eskaluje, gdy poziom zaufania jest niski.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Pomóż mi zwrócić moje zamówienie."
]
}
],
"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"
]
}
]
}FAQ
Zmiany wersji, pola wykrywania, i szczegóły publikacji decydujące o tym, czy Agent Card przejdzie recenzję.
v1.0 skonsolidowało url, preferredTransport, i additionalInterfaces w jedną uporządkowaną tablicę supportedInterfaces, w której każdy wpis deklaruje własny url, protocolBinding, i protocolVersion. supportsAuthenticatedExtendedCard przeniesiono do capabilities.extendedAgentCard, provider.name stało się provider.organization, tagi umiejętności stały się wymagane, a podpisy Agent Card JWS zostały sformalizowane kanonizacją RFC 8785.
Nie. Agent Card to dokument wykrywania dla agenta. Podsumowuje tożsamość, interfejsy, możliwości, umiejętności, tryby, dostawcę, i metadane bezpieczeństwa, podczas gdy pełny schemat API opisuje szczegółowe formy żądań i odpowiedzi. Odgrywa rolę, jaką README lub przegląd OpenAPI odgrywa dla usługi: wystarczy, aby zdecydować, czy i jak ją wywołać.
name, description, supportedInterfaces, skills (z tagami), defaultInputModes, defaultOutputModes, capabilities, provider, i metadane bezpieczeństwa. Systemy routingu dopasowują zadania do Twojego description i tagów umiejętności, a następnie używają interfejsów i możliwości do zaplanowania rzeczywistego wywołania.
Publikuj tylko umiejętności bezpieczne dla nieuwierzytelnionego wykrywania. Jeśli potrzebna jest bogatsza prywatna Agent Card, ustaw capabilities.extendedAgentCard na true i udostępnij wrażliwe umiejętności poprzez uwierzytelnioną operację GetExtendedAgentCard.
Pod well-known URI https://twoja-domena/.well-known/agent-card.json, serwowaną z typem treści application/a2a+json (application/json również działa w praktyce). Wcześniejsze implementacje używały /.well-known/agent.json, więc publikowanie obu podczas przejścia jest pragmatycznym wyborem.
Wykorzystaj schemat w praktyce
Wygeneruj Agent Card w formacie v1.0 na podstawie szczegółów Twojej usługi, lub wklej istniejącą Agent Card do walidatora, aby zobaczyć dokładnie, które pola wymagają uwagi.
Z bloga
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 readPrzeczytaj przewodnikHow-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 readPrzeczytaj przewodnikIntegrationLearn 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 readPrzeczytaj przewodnikArtykuły publikowane są po angielsku.