Rujukan skema · 14 fieldsA2A v1.0
Agent Card ialah dokumen JSON piawai yang memberitahu klien A2A siapakah agen tersebut, di mana untuk menghubunginya, apa yang boleh dilakukannya, dan bagaimana akses dilindungi. Rujukan ini merangkumi setiap medan v1.0 dengan jenis, keperluan, contoh, dan kesilapan yang paling kerap dikesan oleh pengesah.
Cara penemuan berfungsi
Klien A2A mengambil Agent Card daripada URI well-known, menilai skill, keupayaan, dan keperluan keselamatan berdasarkan tugasnya, kemudian memanggil antara muka pilihan — entri pertama dalam supportedInterfaces. Jika capabilities.extendedAgentCard adalah true, klien yang disahkan boleh meminta Agent Card yang lebih kaya melalui operasi GetExtendedAgentCard.
Spesifikasi mendaftarkan /.well-known/agent-card.json sebagai lokasi standard. Penggunaan v0.x yang lebih lama menggunakan /.well-known/agent.json, itulah sebabnya pengesah kami menyemak kedua-duanya.
# 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" }
],
...
}Rujukan medan
Bendera wajib mengikut definisi protobuf v1.0 dalam spesifikasi rasmi. Pautan sauh menjadikan setiap medan boleh dipetik daripada isu, semakan, dan output CI.
Nama agen yang boleh dibaca manusia.
Dipaparkan dalam senarai pasaran dan UI klien. Kekalkan ia pendek dan khusus — klien menggunakannya sebagai label utama semasa membandingkan agen calon.
Kesilapan biasa: Menggunakan nama generik seperti "AI Assistant" yang tidak memberikan sistem penghalaan apa-apa untuk dibezakan.
"name": "Ejen Perancang Laluan GeoSpatial"
Apa yang agen lakukan dan bila agen lain patut memanggilnya.
Ini adalah isyarat teks bebas utama untuk kedua-dua pengintegrasi manusia dan penghala berasaskan LLM yang memutuskan sama ada agen anda sesuai untuk tugas. Nyatakan domain tugas, keupayaan utama, dan batasan.
Kesilapan biasa: Penerangan satu baris di bawah 20 aksara. Penghala tidak dapat memadankan apa yang anda tidak terangkan.
"description": "Menyediakan perancangan laluan lanjutan, analisis trafik dan perkhidmatan penjanaan peta tersuai."
Senarai tersusun bagi titik akhir dan pengikatan protokol. Entri pertama diutamakan.
Baharu dalam v1.0: menggantikan medan peringkat atas lama url, preferredTransport, dan additionalInterfaces. Setiap entri mengisytiharkan url sendiri, protocolBinding (JSONRPC, GRPC, HTTP+JSON, atau URI pengikatan tersuai), protocolVersion, dan kunci penghalaan penyewa pilihan — supaya satu agen boleh melayani pelbagai versi protokol dan pengangkutan serentak.
Kesilapan biasa: Mengisytiharkan pengikatan yang sebenarnya tidak dilayani oleh pelayan pada URL tersebut — spesifikasi memerlukan setiap entri tepat.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Siapa yang mengendalikan agen: organisasi dan laman web.
Isyarat kepercayaan untuk pasaran dan audit perusahaan. v1.0 menamakan semula medan name kepada organization; url adalah wajib di dalam objek apabila hadir.
Kesilapan biasa: Masih menggunakan provider.name (pra-v1.0). Pengesah yang membaca Agent Card v1.0 tidak akan mengecamnya.
"provider": {
"organization": "Contoh Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Versi agen itu sendiri, bukan protokol.
Membolehkan klien mengesan apabila Agent Card telah berubah secara material dan menilai semula keserasian. Ikuti skema keluaran anda sendiri, biasanya semver.
Kesilapan biasa: Mengelirukan ini dengan versi protokol A2A — yang kini berada pada setiap entri supportedInterfaces.
"version": "1.2.0"
Pautan kepada dokumentasi boleh dibaca manusia untuk agen.
Memberikan pengintegrasi tempat untuk membaca kontrak API penuh, had kadar, dan terma yang tidak sepatutnya berada dalam dokumen penemuan.
Kesilapan biasa: Menunjuk ke laman utama pemasaran dan bukannya dokumentasi teknikal.
"documentationUrl": "https://docs.example.com/agent"
Bendera ciri protokol: streaming, pushNotifications, extensions, extendedAgentCard.
Klien TIDAK BOLEH memanggil ciri yang tidak anda isytiharkan — panggilan streaming yang tidak diisytiharkan mengembalikan ralat. extendedAgentCard: true mengumumkan Agent Card disahkan yang lebih kaya melalui operasi GetExtendedAgentCard. v1.0 mengalih keluar stateTransitionHistory.
Kesilapan biasa: Mengisytiharkan streaming: true apabila pelayan tidak mempunyai titik akhir streaming. Klien akan memanggilnya dan gagal.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Skema pengesahan bernama: kunci API, pengesahan HTTP, OAuth 2.0, OpenID Connect, atau TLS bersama.
Setiap skema bernama membalut satu objek skema konkrit (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Klien menemui cara mengesahkan dari sini — kelayakan itu sendiri sentiasa diperoleh di luar jalur.
Kesilapan biasa: Membenamkan kunci API atau token sebenar dalam Agent Card. Agent Card adalah dokumen awam.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Skema yang diisytiharkan (dan skop) yang diperlukan untuk memanggil agen.
Setiap entri memetakan nama skema daripada securitySchemes kepada skop yang diperlukannya, mencerminkan corak keperluan keselamatan OpenAPI. Tinggalkan kedua-dua medan sepenuhnya untuk agen yang sengaja awam.
Kesilapan biasa: Mengisytiharkan securitySchemes tetapi tanpa keperluan security, membiarkan klien meneka sama ada pengesahan dikuatkuasakan.
"security": [{ "google": ["openid", "profile", "email"] }]Jenis media yang diterima agen merentasi semua skill.
Jenis MIME standard seperti text/plain, application/json, atau image/png. Skill individu boleh mengatasi dengan inputModes mereka sendiri.
Kesilapan biasa: Mengabaikan medan tersebut. Ia wajib dalam v1.0 — klien memerlukannya untuk membentuk permintaan.
"defaultInputModes": ["application/json", "text/plain"]
Jenis media yang dikembalikan agen merentasi semua skill.
Memberitahu pemanggil sama ada untuk mengharapkan prosa, JSON berstruktur, imej, atau fail. Skill boleh mengatasi setiap skill dengan outputModes.
Kesilapan biasa: Hanya menyenaraikan text/plain sedangkan agen sebenarnya mengembalikan artifak berstruktur.
"defaultOutputModes": ["application/json", "image/png"]
Keupayaan konkrit yang agen berkemungkinan berjaya.
Setiap skill memerlukan id, name, description, dan tags; examples, mod setiap skill, dan keselamatan setiap skill adalah pilihan. Skill adalah unit penemuan — penghala memadankan tugas terhadapnya, jadi hadkan setiap satu kepada satu sempadan tugas.
Kesilapan biasa: Skill tanpa tag. Tag menjadi wajib dalam v1.0 dan menggerakkan pemadanan peringkat skill.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Pengoptimum Laluan Sedar Trafik",
"description": "Mengira laluan pemanduan optimum menggunakan trafik masa nyata...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Rancang laluan dari A ke B mengelakkan tol."]
}]Tandatangan JSON Web yang membuktikan Agent Card dikeluarkan oleh penyedia.
Setiap tandatangan membawa pengepala JWS dilindungi base64url dan nilai tandatangan, dikira ke atas Agent Card yang dikanonikalisasikan RFC 8785 (JCS). Klien SEHARUSNYA mengesahkan sekurang-kurangnya satu tandatangan sebelum mempercayai Agent Card yang diambil daripada web terbuka.
Kesilapan biasa: Menandatangani kad kemudian menyunting mana-mana medan — malah perubahan nilai ruang putih yang tidak signifikan membatalkan JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL kepada ikon yang mewakili agen.
Digunakan oleh katalog dan UI klien. Sajikannya melalui HTTPS daripada lokasi yang stabil.
Kesilapan biasa: Memaut ikon pada domain lain yang tidak dipercayai yang boleh berubah tanpa pengetahuan di sebalik penyenaraian anda.
"iconUrl": "https://agent.example.com/icon.png"
Migrasi versi
Jika Agent Card anda masih mempunyai url atau preferredTransport peringkat atas, ia mendahului v1.0. Pengesah menandakan setiap satu ini secara automatik.
| Medan v0.x | Penggantian v1.0 | Mengapa ia berubah |
|---|---|---|
| url | supportedInterfaces[0].url | Titik akhir pilihan kini hanyalah entri antara muka pertama. |
| preferredTransport | supportedInterfaces[] ordering | Keutamaan dinyatakan melalui susunan array dan bukannya medan berasingan. |
| additionalInterfaces | supportedInterfaces[] | Semua antara muka berada dalam satu array tersusun. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Setiap antara muka mengisytiharkan versi protokol sendiri, membolehkan sokongan pelbagai versi. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Dipindahkan ke objek capabilities; RPC dinamakan semula kepada GetExtendedAgentCard. |
| provider.name | provider.organization | Dinamakan semula untuk kejelasan. |
| capabilities.stateTransitionHistory | — removed | Bukan sebahagian daripada v1.0; modelkan tingkah laku setara sebagai lanjutan jika perlu. |
Boilerplate
Letakkan antara muka ini ke dalam klien, pelayan, atau semakan CI untuk menghurai dan menghasilkan Agent Card dengan keselamatan jenis. Ia mencerminkan definisi protobuf dalam repositori spesifikasi rasmi, dalam bentuk JSON camelCase yang Agent Card diterbitkan.
Membina Agent Card secara manual sebaliknya? Penjana menghasilkan bentuk tepat 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> }Integriti
Kerana Agent Card diambil daripada web terbuka, v1.0 merasmikan penandatanganan: Agent Card (tolak medan signatures dan nilai lalai) dikanonikalisasikan dengan RFC 8785 JSON Canonicalization, kemudian ditandatangani sebagai JWS. Klien sepatutnya mengesahkan sekurang-kurangnya satu tandatangan — melalui pengepala kid/jku atau kedai kunci dipercayai — sebelum bertindak ke atas Agent Card. Beberapa tandatangan menyokong putaran kunci.
Sajikan Agent Card di /.well-known/agent-card.json melalui HTTPS.
Setiap entri supportedInterfaces boleh dicapai dan bertutur pengikatan yang diisytiharkan.
Skill mempunyai tag wajib berserta penerangan dengan sempadan tugas yang jelas.
Keupayaan yang diisytiharkan sepadan dengan pelayan — ciri yang tidak diisytiharkan mesti mengembalikan ralat, yang diisytiharkan mesti berfungsi.
securitySchemes menerangkan cara untuk mengesahkan; tiada kelayakan muncul di mana-mana dalam Agent Card.
version dinaikkan setiap kali kandungan Agent Card berubah.
Agen sokongan pelanggan dengan OAuth 2.0, streaming, dan pemberitahuan tolak — semua medan wajib hadir. Lebih banyak corak terdapat dalam pustaka contoh.
{
"name": "Ejen Sokongan Pelanggan",
"description": "Menjawab soalan sokongan pelanggan, mendapatkan semula konteks pesanan dan meningkatkan isu yang tidak dapat diselesaikan kepada pasukan 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 sokongan pelanggan",
"description": "Mengklasifikasikan permintaan sokongan pelanggan, mengumpulkan konteks yang diperlukan, mencadangkan penyelesaian dan meningkat apabila keyakinan rendah.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Bantu saya pulangkan 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"
]
}
]
}Soalan lazim
Perubahan versi, medan penemuan, dan butiran penerbitan yang menentukan sama ada Agent Card lulus semakan.
v1.0 menggabungkan url, preferredTransport, dan additionalInterfaces ke dalam satu array supportedInterfaces tersusun di mana setiap entri mengisytiharkan url, protocolBinding, dan protocolVersion sendiri. supportsAuthenticatedExtendedCard dipindahkan ke capabilities.extendedAgentCard, provider.name menjadi provider.organization, tag skill menjadi wajib, dan tandatangan Agent Card JWS dirasmikan dengan kanonikalisasi RFC 8785.
Tidak. Agent Card ialah dokumen penemuan untuk agen. Ia meringkaskan identiti, antara muka, keupayaan, skill, mod, penyedia, dan metadata keselamatan, manakala skema API penuh menerangkan bentuk permintaan dan respons terperinci. Ia memainkan peranan yang dimainkan README atau gambaran keseluruhan OpenAPI untuk perkhidmatan: mencukupi untuk memutuskan sama ada dan bagaimana untuk memanggilnya.
name, description, supportedInterfaces, skills (dengan tag), defaultInputModes, defaultOutputModes, capabilities, provider, dan metadata keselamatan. Sistem penghalaan memadankan tugas dengan description dan tag skill anda, kemudian menggunakan antara muka dan keupayaan untuk merancang panggilan sebenar.
Hanya terbitkan skill yang selamat untuk penemuan tidak disahkan. Jika Agent Card peribadi yang lebih kaya diperlukan, tetapkan capabilities.extendedAgentCard kepada true dan dedahkan skill sensitif melalui operasi GetExtendedAgentCard yang disahkan.
Pada URI well-known https://{domain-anda}/.well-known/agent-card.json, disajikan dengan jenis kandungan application/a2a+json (application/json juga berfungsi dalam praktik). Pelaksanaan terdahulu menggunakan /.well-known/agent.json, jadi menerbitkan kedua-duanya semasa peralihan adalah pilihan pragmatik.
Manfaatkan skema
Jana Agent Card berbentuk v1.0 daripada butiran perkhidmatan anda, atau tampal Agent Card sedia ada ke dalam pengesah untuk melihat dengan tepat medan mana yang memerlukan perhatian.