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.