Penemuan ejen awam
Gunakan contoh ini untuk membentuk JSON yang diambil oleh klien A2A lain sebelum memutuskan sama ada ejen anda boleh menyelesaikan tugas.
6 templat JSON sedia disalin · A2A v1.0
Contoh A2A Agent Card
Semak imbas templat A2A v1.0 praktikal, fahami keputusan reka bentuknya, kemudian sesuaikan mana-mana contoh untuk ejen anda sendiri.
Penghantaran pasaran
Sesuaikan penyedia, skill, tag, keupayaan, dan metadata keselamatan supaya penyemak memahami apa yang ejen lakukan dan siapa yang mengendalikannya.
Katalog ejen dalaman
Piawaikan penerangan titik akhir, pengesahan, dan skill merentasi ejen dalaman sebelum pasukan mengintegrasikannya ke dalam aliran kerja.
Templat JSON
Agent Card contoh untuk ejen sokongan, tempahan, membeli-belah, pengekodan, penyelidikan, dan aliran kerja.
Tapis
Ejen Sokongan Pelanggan
Mengendalikan soalan produk, carian pesanan, pemulangan, dan penyerahan eskalasi.
Mengapa ia dibina sebegini
- Kelayakan klien OAuth 2.0 melindungi data pesanan: Agent Card mengisytiharkan URL token dan skop supaya klien boleh mengesahkan tanpa dokumentasi luar jalur.
- streaming dan pushNotifications kedua-duanya true kerana perbualan sokongan berlangsung lama dan kemas kini penyelesaian tiba secara tak segerak.
- Skill tunggal terhad kepada satu sempadan tugas (mengklasifikasikan, menyelesaikan, mengeskalasi) berbanding penerangan kabur "membantu pelanggan", supaya penghala dapat memadankannya dengan tepat.
{
"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"
]
}
]
}Ejen Tempahan
Mencari slot temu janji yang tersedia dan menyediakan pengesahan tempahan.
Mengapa ia dibina sebegini
- Kunci API dalam pengepala sudah memadai di sini: tempahan bersifat skop-penyewa tetapi tidak membawa masalah persetujuan pengguna terwakil yang diselesaikan oleh OAuth.
- defaultOutputModes hanya application/json, menandakan bahawa pemanggil mendapat cadangan tempahan berstruktur dan bukannya prosa.
- pushNotifications adalah true supaya ejen boleh mengesahkan tempahan selepas backend yang memegang slot selesai, tanpa klien perlu meninjau.
{
"name": "Ejen Tempahan",
"description": "Mencari ketersediaan, mencadangkan pilihan tempahan dan menyediakan tempahan janji temu untuk kelulusan.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/booking",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Contoh Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "find-and-prepare-booking",
"name": "Cari dan sediakan tempahan",
"description": "Menyemak ketersediaan sumber, membandingkan tetingkap tempahan dan mengembalikan cadangan tempahan berstruktur.",
"tags": [
"booking",
"calendar",
"availability"
],
"examples": [
"Cari temu janji 30 minit petang esok."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Ejen Membeli-belah
Membandingkan produk, ketersediaan, harga, dan kekangan pembelian.
Mengapa ia dibina sebegini
- Cadangan yang disusun mengalir semasa ia dikira, jadi streaming adalah true manakala pushNotifications kekal false — tiada apa berlaku selepas respons selesai.
- Penerangan skill komited untuk mengembalikan pertukaran dan rasional, yang memberitahu orkestrator bahawa ejen ini menerangkan kedudukan berbanding hanya menyenaraikan produk.
- Skop OAuth mengawal data berkaitan pembelian; demo membeli-belah awam boleh menghilangkan keselamatan sepenuhnya dan kekal sebagai Agent Card yang sah.
{
"name": "Ejen Membeli-belah",
"description": "Membandingkan produk dengan kekangan pengguna dan mengembalikan pilihan pembelian berperingkat dengan tukar ganti.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/shopping",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Contoh Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "compare-shopping-options",
"name": "Bandingkan pilihan membeli-belah",
"description": "Menilai produk calon, menapis mengikut kekangan, dan mengembalikan pengesyoran berperingkat dengan rasional.",
"tags": [
"shopping",
"commerce",
"recommendations"
],
"examples": [
"Bandingkan komputer riba ringan di bawah $1,200."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Ejen Pengekodan
Menyemak tugas kod, mencadangkan tampalan, dan menerangkan keputusan pelaksanaan.
Mengapa ia dibina sebegini
- extendedAgentCard adalah true: Agent Card awam menyenaraikan skill generik "laksanakan perubahan kod", manakala skill khusus repositori hanya didedahkan kepada klien disahkan melalui GetExtendedAgentCard.
- Kedua-dua output text/plain dan application/json diisytiharkan kerana ejen mengembalikan penjelasan boleh dibaca manusia bersama tampalan boleh digunakan mesin.
- Penstriman penting untuk gelung kompil-dan-uji yang panjang; klien melihat kemajuan pertengahan berbanding panggilan senyap berbilang minit.
{
"name": "Ejen Pengekodan",
"description": "Membantu tugasan kejuruteraan perisian dengan menganalisis kod, mencadangkan perubahan dan memulangkan nota pelaksanaan.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/coding",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Contoh Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "implement-code-change",
"name": "Laksanakan perubahan kod",
"description": "Membaca permintaan pengekodan, memeriksa fail yang berkaitan, mengembalikan cadangan tampalan dan meringkaskan langkah pengesahan.",
"tags": [
"coding",
"review",
"patches"
],
"examples": [
"Tambahkan penomboran pada API pengguna."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Ejen Penyelidikan
Mengumpul sumber, mengekstrak bukti, dan mengembalikan nota penyelidikan berstruktur.
Mengapa ia dibina sebegini
- Tiada securitySchemes langsung: titik akhir sengaja bersifat awam, dan meninggalkan medan itu adalah cara yang betul untuk menyatakannya — peta skema kosong akan menjadi kabur.
- Input hanya text/plain, kerana ringkasan penyelidikan bermula daripada soalan bahasa semula jadi; output berstruktur tiba sebagai nota application/json.
- Ini adalah Agent Card v1.0 minimum yang berguna: identiti, satu antara muka, keupayaan, mod, dan satu skill yang ditag dengan baik.
{
"name": "Ejen Penyelidikan",
"description": "Mengumpul bahan sumber, mengekstrak bukti dan menghasilkan nota penyelidikan berstruktur dengan petikan.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/research",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Contoh Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "prepare-research-brief",
"name": "Sediakan ringkasan penyelidikan",
"description": "Mencari sumber yang diluluskan, mengekstrak tuntutan dan bukti, dan mengembalikan ringkasan penyelidikan yang ringkas.",
"tags": [
"research",
"evidence",
"citations"
],
"examples": [
"Sediakan ringkasan yang disebut tentang dasar tenaga boleh diperbaharui."
]
}
]
}Ejen Aliran Kerja Dalaman
Menyelaraskan kelulusan, semakan status, dan kemas kini aliran kerja pejabat belakang.
Mengapa ia dibina sebegini
- application/json adalah satu-satunya mod input dan output: ejen ini dipanggil oleh sistem lain, tidak pernah oleh orang yang menaip prosa.
- OAuth 2.0 ditambah extendedAgentCard sesuai untuk audit perusahaan — pasukan keselamatan boleh melihat keperluan pengesahan secara awam manakala skill aliran kerja sensitif kekal di sebalik pengesahan.
- pushNotifications adalah penting kerana rantaian kelulusan mengambil masa berjam-jam atau berhari-hari; webhook menggantikan tinjauan untuk perubahan status.
{
"name": "Ejen Aliran Kerja Dalaman",
"description": "Menyelaraskan kelulusan dalaman, menyemak status sistem dan menyediakan kemas kini aliran kerja untuk pasukan operasi.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/workflow",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Contoh Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "coordinate-internal-workflow",
"name": "Menyelaraskan aliran kerja dalaman",
"description": "Menerima niat aliran kerja, menyemak keperluan dasar, mengumpulkan kelulusan dan melaporkan status akhir.",
"tags": [
"workflow",
"operations",
"approval"
],
"examples": [
"Minta kelulusan untuk menggunakan kemas kini gaji."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Sesuaikan dengan yakin
Cara menyesuaikan contoh Agent Card
Setiap contoh Agent Card sengaja dibuat cukup lengkap untuk disalin, tetapi Agent Card tidak sepatutnya diterbitkan tanpa perubahan. Anggap ia sebagai peta medan untuk pelayan A2A anda sendiri: gantikan identiti, titik akhir, penyedia, pengesahan, keupayaan, mod, dan butiran skill dengan nilai pengeluaran.
Agent Card yang paling kukuh menerangkan sempadan tugas ejen dalam kedua-dua bahasa mudah dan metadata boleh dibaca mesin. Klien seharusnya dapat mengetahui apa yang ejen boleh lakukan, apa yang tidak boleh dilakukan, URL mana untuk dipanggil, dan sama ada kelayakan diperlukan.
Sebelum menerbitkan
Gantikan setiap URL example.com dengan titik akhir A2A yang digunakan dan laman web penyedia anda.
Tulis semula nama skill, penerangan, tag (wajib dalam v1.0), dan contoh untuk sempadan tugas sebenar.
Tetapkan provider.organization dan naikkan version peringkat atas setiap kali kandungan Agent Card berubah.
Alih keluar medan pengesahan hanya apabila titik akhir sengaja bersifat awam.
Kekalkan defaultInputModes dan defaultOutputModes selaras dengan apa yang pelayan anda sebenarnya terima dan kembalikan.
Sahkan JSON akhir dan terbitkannya di /.well-known/agent-card.json pada domain perkhidmatan anda.
Sedia untuk membina
Mula dengan satu contoh, kemudian jadikannya milik anda sendiri.
Buka mana-mana corak dalam Penjana Agent Card, semak JSON, dan sahkannya sebelum menerbitkan.