Referensi schema · 14 fieldsA2A v1.0
Agent Card adalah dokumen JSON terstandarisasi yang memberi tahu klien A2A siapa agent tersebut, di mana menghubunginya, apa yang bisa dilakukannya, dan bagaimana akses diamankan. Referensi ini mencakup setiap bidang v1.0 dengan tipe, persyaratan, contoh, dan kesalahan yang paling sering ditemukan validator.
Cara kerja penemuan
Klien A2A mengambil Agent Card dari URI well-known, mengevaluasi skill, kapabilitas, dan persyaratan keamanan terhadap tugasnya, lalu memanggil interface pilihan — entri pertama dalam supportedInterfaces. Jika capabilities.extendedAgentCard bernilai true, klien yang terautentikasi dapat meminta Agent Card yang lebih kaya melalui operasi GetExtendedAgentCard.
Spesifikasi mendaftarkan /.well-known/agent-card.json sebagai lokasi standar. Deployment v0.x yang lebih lama menggunakan /.well-known/agent.json, itulah sebabnya validator kami memeriksa keduanya.
# 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" }
],
...
}Referensi bidang
Tanda wajib mengikuti definisi protobuf v1.0 dalam spesifikasi resmi. Tautan jangkar membuat setiap bidang dapat dikutip dari issue, tinjauan, dan output CI.
Nama agent yang dapat dibaca manusia.
Ditampilkan dalam daftar marketplace dan UI klien. Buat singkat dan spesifik — klien menggunakannya sebagai label utama saat membandingkan agent kandidat.
Kesalahan umum: Menggunakan nama generik seperti "AI Assistant" yang tidak memberi sistem routing apa pun untuk dibedakan.
"name": "Agen Perencana Rute GeoSpasial"
Apa yang dilakukan agent dan kapan agent lain harus memanggilnya.
Ini adalah sinyal teks bebas utama baik bagi integrator manusia maupun router berbasis LLM yang memutuskan apakah agent Anda cocok untuk suatu tugas. Nyatakan domain tugas, kemampuan utama, dan batasan.
Kesalahan umum: Deskripsi satu baris di bawah 20 karakter. Router tidak dapat mencocokkan apa yang tidak Anda deskripsikan.
"description": "Menyediakan perencanaan rute tingkat lanjut, analisis lalu lintas, dan layanan pembuatan peta khusus."
Daftar berurutan endpoint dan protocol binding. Entri pertama lebih diutamakan.
Baru di v1.0: menggantikan bidang tingkat atas lama url, preferredTransport, dan additionalInterfaces. Setiap entri mendeklarasikan url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, atau URI binding kustom), protocolVersion, dan kunci perutean tenant opsional sendiri — sehingga satu agent dapat melayani beberapa versi protokol dan transport secara bersamaan.
Kesalahan umum: Mendeklarasikan binding yang sebenarnya tidak dilayani server pada URL tersebut — spesifikasi mensyaratkan setiap entri harus akurat.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Siapa yang mengoperasikan agent: organisasi dan situs web.
Sinyal kepercayaan untuk marketplace dan audit perusahaan. v1.0 mengganti nama bidang name menjadi organization; url wajib di dalam objek jika ada.
Kesalahan umum: Masih menggunakan provider.name (pra-v1.0). Validator yang membaca Agent Card v1.0 tidak akan mengenalinya.
"provider": {
"organization": "Contoh Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Versi agent itu sendiri, bukan protokol.
Memungkinkan klien mendeteksi kapan Agent Card berubah secara material dan mengevaluasi ulang kompatibilitas. Ikuti skema rilis Anda sendiri, biasanya semver.
Kesalahan umum: Mencampuradukkan ini dengan versi protokol A2A — yang sekarang berada di setiap entri supportedInterfaces.
"version": "1.2.0"
Tautan ke dokumentasi yang dapat dibaca manusia untuk agent.
Memberi integrator tempat untuk membaca kontrak API lengkap, batas laju, dan ketentuan yang tidak termasuk dalam dokumen penemuan.
Kesalahan umum: Menunjuk ke halaman beranda pemasaran alih-alih dokumentasi teknis.
"documentationUrl": "https://docs.example.com/agent"
Flag fitur protokol: streaming, pushNotifications, extensions, extendedAgentCard.
Klien TIDAK BOLEH memanggil fitur yang tidak Anda deklarasikan — panggilan streaming yang tidak dideklarasikan mengembalikan error. extendedAgentCard: true mengumumkan Agent Card terautentikasi yang lebih kaya melalui operasi GetExtendedAgentCard. v1.0 menghapus stateTransitionHistory.
Kesalahan umum: Mendeklarasikan streaming: true padahal server tidak memiliki endpoint streaming. Klien akan memanggilnya dan gagal.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Skema autentikasi bernama: kunci API, autentikasi HTTP, OAuth 2.0, OpenID Connect, atau TLS mutual.
Setiap skema bernama membungkus satu objek skema konkret (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Klien menemukan cara autentikasi dari sini — kredensial itu sendiri selalu diperoleh di luar jalur.
Kesalahan umum: Menyematkan kunci API atau token aktual di dalam Agent Card. Agent Card adalah dokumen publik.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Skema yang dideklarasikan (dan scope) mana yang diperlukan untuk memanggil agent.
Setiap entri memetakan nama skema dari securitySchemes ke scope yang dibutuhkannya, mencerminkan pola persyaratan keamanan OpenAPI. Hilangkan kedua bidang sepenuhnya untuk agent yang sengaja bersifat publik.
Kesalahan umum: Mendeklarasikan securitySchemes tetapi tanpa persyaratan security, membiarkan klien menebak apakah autentikasi diberlakukan.
"security": [{ "google": ["openid", "profile", "email"] }]Jenis media yang diterima agent di semua skill.
Jenis MIME standar seperti text/plain, application/json, atau image/png. Skill individual dapat menimpa dengan inputModes mereka sendiri.
Kesalahan umum: Menghilangkan bidang tersebut. Ini wajib di v1.0 — klien membutuhkannya untuk membentuk permintaan.
"defaultInputModes": ["application/json", "text/plain"]
Jenis media yang dikembalikan agent di semua skill.
Memberi tahu pemanggil apakah harus mengharapkan prosa, JSON terstruktur, gambar, atau file. Skill dapat menimpa per skill dengan outputModes.
Kesalahan umum: Hanya mencantumkan text/plain padahal agent sebenarnya mengembalikan artefak terstruktur.
"defaultOutputModes": ["application/json", "image/png"]
Kemampuan konkret yang kemungkinan besar berhasil dilakukan agent.
Setiap skill memerlukan id, name, description, dan tags; examples, mode per skill, dan keamanan per skill bersifat opsional. Skill adalah unit penemuan — router mencocokkan tugas terhadapnya, jadi batasi masing-masing pada satu batas tugas.
Kesalahan umum: Skill tanpa tag. Tag menjadi wajib di v1.0 dan mendorong pencocokan tingkat skill.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Pengoptimal Rute Sadar Lalu Lintas",
"description": "Menghitung rute mengemudi optimal menggunakan lalu lintas waktu nyata...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Rencanakan rute dari A ke B dengan menghindari tol."]
}]JSON Web Signature yang membuktikan Agent Card diterbitkan oleh provider.
Setiap tanda tangan membawa header JWS terlindungi base64url dan nilai tanda tangan, dihitung atas Agent Card yang dikanonisasi RFC 8785 (JCS). Klien SEBAIKNYA memverifikasi setidaknya satu tanda tangan sebelum mempercayai Agent Card yang diambil dari web terbuka.
Kesalahan umum: Menandatangani kartu lalu mengedit bidang apa pun — bahkan perubahan nilai yang tidak signifikan pada spasi kosong membuat JWS tidak valid.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL ke ikon yang mewakili agent.
Digunakan oleh katalog dan UI klien. Sajikan melalui HTTPS dari lokasi yang stabil.
Kesalahan umum: Menautkan ikon pada domain lain yang tidak tepercaya yang dapat berubah tanpa sepengetahuan Anda di balik listing Anda.
"iconUrl": "https://agent.example.com/icon.png"
Migrasi versi
Jika Agent Card Anda masih memiliki url atau preferredTransport tingkat atas, itu mendahului v1.0. Validator menandai masing-masing ini secara otomatis.
| Bidang v0.x | Pengganti v1.0 | Mengapa berubah |
|---|---|---|
| url | supportedInterfaces[0].url | Endpoint pilihan sekarang hanyalah entri interface pertama. |
| preferredTransport | supportedInterfaces[] ordering | Preferensi dinyatakan dengan urutan array, bukan bidang terpisah. |
| additionalInterfaces | supportedInterfaces[] | Semua interface berada dalam satu array berurutan. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Setiap interface mendeklarasikan versi protokolnya sendiri, memungkinkan dukungan multi-versi. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Dipindahkan ke objek capabilities; RPC diganti namanya menjadi GetExtendedAgentCard. |
| provider.name | provider.organization | Diganti namanya demi kejelasan. |
| capabilities.stateTransitionHistory | — removed | Bukan bagian dari v1.0; modelkan perilaku setara sebagai ekstensi jika diperlukan. |
Boilerplate
Masukkan interface ini ke dalam klien, server, atau pemeriksaan CI untuk mengurai dan menghasilkan Agent Card dengan keamanan tipe. Ini mencerminkan definisi protobuf di repositori spesifikasi resmi, dalam bentuk JSON camelCase tempat Agent Card dipublikasikan.
Membangun Agent Card secara manual sebagai gantinya? Generator menghasilkan bentuk yang persis ini.
// 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> }Integritas
Karena Agent Card diambil dari web terbuka, v1.0 meresmikan penandatanganan: Agent Card (dikurangi bidang signatures dan nilai default) dikanonisasi dengan RFC 8785 JSON Canonicalization, lalu ditandatangani sebagai JWS. Klien sebaiknya memverifikasi setidaknya satu tanda tangan — melalui header kid/jku atau penyimpanan kunci tepercaya — sebelum bertindak berdasarkan Agent Card. Beberapa tanda tangan mendukung rotasi kunci.
Sajikan Agent Card di /.well-known/agent-card.json melalui HTTPS.
Setiap entri supportedInterfaces dapat dijangkau dan menggunakan binding yang dideklarasikan.
Skill memiliki tag wajib ditambah deskripsi dengan batas tugas yang jelas.
Kapabilitas yang dideklarasikan sesuai dengan server — fitur yang tidak dideklarasikan harus mengembalikan error, yang dideklarasikan harus berfungsi.
securitySchemes menjelaskan cara autentikasi; tidak ada kredensial yang muncul di mana pun dalam Agent Card.
version dinaikkan setiap kali konten Agent Card berubah.
Agent dukungan pelanggan dengan OAuth 2.0, streaming, dan notifikasi push — semua bidang wajib ada. Pola lainnya ada di pustaka contoh.
{
"name": "Agent Dukungan Pelanggan",
"description": "Menjawab pertanyaan dukungan pelanggan, mengambil konteks pesanan, dan meneruskan masalah yang belum terselesaikan ke tim manusia.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Contoh 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": "Selesaikan permintaan dukungan pelanggan",
"description": "Mengklasifikasikan permintaan dukungan pelanggan, mengumpulkan konteks yang diperlukan, mengusulkan resolusi, dan mengeskalasinya ketika kepercayaan rendah.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Bantu saya mengembalikan pesanan saya."
]
}
],
"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"
]
}
]
}Pertanyaan umum
Perubahan versi, bidang penemuan, dan detail penerbitan yang menentukan apakah Agent Card lolos peninjauan.
v1.0 menggabungkan url, preferredTransport, dan additionalInterfaces menjadi satu array supportedInterfaces berurutan di mana setiap entri mendeklarasikan url, protocolBinding, dan protocolVersion sendiri. supportsAuthenticatedExtendedCard dipindahkan ke capabilities.extendedAgentCard, provider.name menjadi provider.organization, tag skill menjadi wajib, dan tanda tangan Agent Card JWS diresmikan dengan kanonisasi RFC 8785.
Tidak. Agent Card adalah dokumen penemuan untuk sebuah agent. Ini merangkum identitas, interface, kapabilitas, skill, mode, provider, dan metadata keamanan, sementara schema API lengkap mendeskripsikan bentuk permintaan dan respons secara rinci. Ini memainkan peran yang dimainkan README atau ringkasan OpenAPI untuk sebuah layanan: cukup untuk memutuskan apakah dan bagaimana memanggilnya.
name, description, supportedInterfaces, skills (dengan tag), defaultInputModes, defaultOutputModes, capabilities, provider, dan metadata keamanan. Sistem routing mencocokkan tugas terhadap description dan tag skill Anda, lalu menggunakan interface dan kapabilitas untuk merencanakan panggilan sebenarnya.
Hanya publikasikan skill yang aman untuk penemuan tanpa autentikasi. Jika Agent Card privat yang lebih kaya diperlukan, atur capabilities.extendedAgentCard ke true dan ekspos skill sensitif melalui operasi GetExtendedAgentCard yang terautentikasi.
Di URI well-known https://{domain-anda}/.well-known/agent-card.json, disajikan dengan tipe konten application/a2a+json (application/json juga berfungsi dalam praktiknya). Implementasi sebelumnya menggunakan /.well-known/agent.json, jadi mempublikasikan keduanya selama transisi adalah pilihan yang pragmatis.
Manfaatkan schema
Hasilkan Agent Card berbentuk v1.0 dari detail layanan Anda, atau tempel Agent Card yang sudah ada ke validator untuk melihat persis bidang mana yang memerlukan perhatian.