6 template JSON siap salin · A2A v1.0

Contoh A2A Agent Card

Jelajahi template A2A v1.0 praktis, pahami keputusan desainnya, lalu sesuaikan contoh apa pun untuk agent Anda sendiri.

Penemuan agent publik

Gunakan contoh ini untuk membentuk JSON yang diambil klien A2A lain sebelum memutuskan apakah agent Anda dapat menyelesaikan tugas.

Pengajuan marketplace

Sesuaikan provider, skill, tag, kapabilitas, dan metadata keamanan sehingga peninjau memahami apa yang dilakukan agent dan siapa yang mengoperasikannya.

Katalog agent internal

Standarkan deskripsi endpoint, autentikasi, dan skill di seluruh agent internal sebelum tim mengintegrasikannya ke dalam alur kerja.

Template JSON

Contoh Agent Card untuk agent dukungan, pemesanan, belanja, pengkodean, riset, dan alur kerja.

Validasi sebuah template

Filter

Agent Dukungan Pelanggan

Menangani pertanyaan produk, pencarian pesanan, pengembalian, dan penyerahan eskalasi.

Mengapa dibangun seperti ini

Kredensial klien OAuth 2.0 melindungi data pesanan: Agent Card mendeklarasikan URL token dan scope sehingga klien dapat mengautentikasi tanpa dokumentasi di luar jalur.
streaming dan pushNotifications keduanya true karena percakapan dukungan berlangsung lama dan pembaruan resolusi tiba secara asinkron.
Skill tunggal dibatasi pada satu batas tugas (mengklasifikasikan, menyelesaikan, mengeskalasi) alih-alih deskripsi samar "membantu pelanggan", sehingga router dapat mencocokkannya dengan tepat.

customer-support.json

{
  "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"
      ]
    }
  ]
}

Agent Pemesanan

Menemukan slot janji temu yang tersedia dan menyiapkan konfirmasi pemesanan.

Mengapa dibangun seperti ini

Kunci API dalam header sudah cukup di sini: pemesanan dibatasi ruang lingkup per tenant tetapi tidak membawa masalah persetujuan pengguna terdelegasi yang diselesaikan OAuth.
defaultOutputModes hanya application/json, menandakan bahwa pemanggil mendapatkan proposal reservasi terstruktur alih-alih prosa.
pushNotifications bernilai true sehingga agent dapat mengonfirmasi reservasi setelah backend penahan slot selesai, tanpa klien melakukan polling.

booking.json

{
  "name": "Agent Pemesanan",
  "description": "Mencari ketersediaan, mengusulkan opsi pemesanan, dan menyiapkan reservasi janji temu untuk disetujui.",
  "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": "Temukan dan siapkan pemesanan",
      "description": "Memeriksa ketersediaan sumber daya, membandingkan jangka waktu pemesanan, dan mengembalikan proposal reservasi terstruktur.",
      "tags": [
        "booking",
        "calendar",
        "availability"
      ],
      "examples": [
        "Temukan janji temu 30 menit besok sore."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

Agent Belanja

Membandingkan produk, ketersediaan, harga, dan batasan pembelian.

Mengapa dibangun seperti ini

Rekomendasi berperingkat di-streaming saat dihitung, jadi streaming bernilai true sementara pushNotifications tetap false — tidak ada yang terjadi setelah respons selesai.
Deskripsi skill berkomitmen untuk mengembalikan trade-off dan alasan, yang memberi tahu orkestrator bahwa agent ini menjelaskan peringkat alih-alih hanya mendaftar produk.
Scope OAuth mengontrol data terkait pembelian; demo belanja publik dapat sepenuhnya menghilangkan keamanan dan tetap menjadi Agent Card yang valid.

shopping.json

{
  "name": "Agent Belanja",
  "description": "Membandingkan produk dengan batasan pengguna dan mengembalikan peringkat opsi pembelian dengan pengorbanan.",
  "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 belanja",
      "description": "Mengevaluasi produk kandidat, memfilter berdasarkan batasan, dan mengembalikan rekomendasi yang diberi peringkat dengan alasan.",
      "tags": [
        "shopping",
        "commerce",
        "recommendations"
      ],
      "examples": [
        "Bandingkan laptop 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"
      ]
    }
  ]
}

Agent Pengkodean

Meninjau tugas kode, mengusulkan patch, dan menjelaskan keputusan implementasi.

Mengapa dibangun seperti ini

extendedAgentCard bernilai true: Agent Card publik mencantumkan skill generik "menerapkan perubahan kode", sementara skill khusus repositori hanya diungkapkan kepada klien terautentikasi melalui GetExtendedAgentCard.
Output text/plain dan application/json keduanya dideklarasikan karena agent mengembalikan penjelasan yang dapat dibaca manusia bersama patch yang dapat diterapkan mesin.
Streaming penting untuk loop kompilasi-dan-uji yang panjang; klien melihat kemajuan menengah alih-alih panggilan diam berdurasi beberapa menit.

coding.json

{
  "name": "Agent Pengkodean",
  "description": "Membantu tugas rekayasa perangkat lunak dengan menganalisis kode, mengusulkan perubahan, dan mengembalikan catatan implementasi.",
  "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": "Menerapkan perubahan kode",
      "description": "Membaca permintaan pengkodean, memeriksa file yang relevan, mengembalikan proposal patch, dan merangkum langkah-langkah verifikasi.",
      "tags": [
        "coding",
        "review",
        "patches"
      ],
      "examples": [
        "Tambahkan penomoran halaman ke API pengguna."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

Agent Riset

Mengumpulkan sumber, mengekstrak bukti, dan mengembalikan catatan riset terstruktur.

Mengapa dibangun seperti ini

Sama sekali tidak ada securitySchemes: endpoint sengaja dibuat publik, dan menghilangkan bidang tersebut adalah cara yang benar untuk menyatakannya — peta skema kosong akan ambigu.
Input hanya text/plain, karena ringkasan riset dimulai dari pertanyaan bahasa alami; output terstruktur tiba sebagai catatan application/json.
Ini adalah Agent Card v1.0 minimal yang berguna: identitas, satu interface, kapabilitas, mode, dan satu skill yang diberi tag dengan baik.

research.json

{
  "name": "Agent Riset",
  "description": "Mengumpulkan bahan sumber, mengekstrak bukti, dan menghasilkan catatan penelitian terstruktur dengan kutipan.",
  "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": "Siapkan ringkasan penelitian",
      "description": "Mencari sumber yang disetujui, mengekstrak klaim dan bukti, dan mengembalikan ringkasan penelitian singkat.",
      "tags": [
        "research",
        "evidence",
        "citations"
      ],
      "examples": [
        "Siapkan ringkasan singkat mengenai kebijakan energi terbarukan."
      ]
    }
  ]
}

Agent Alur Kerja Internal

Mengoordinasikan persetujuan, pemeriksaan status, dan pembaruan alur kerja back-office.

Mengapa dibangun seperti ini

application/json adalah satu-satunya mode input dan output: agent ini dipanggil oleh sistem lain, tidak pernah oleh orang yang mengetik prosa.
OAuth 2.0 ditambah extendedAgentCard cocok untuk audit perusahaan — tim keamanan dapat melihat persyaratan autentikasi secara publik sementara skill alur kerja sensitif tetap berada di balik autentikasi.
pushNotifications penting karena rantai persetujuan memakan waktu berjam-jam atau berhari-hari; webhook menggantikan polling untuk perubahan status.

internal-workflow.json

{
  "name": "Agent Alur Kerja Internal",
  "description": "Mengkoordinasikan persetujuan internal, memeriksa status sistem, dan menyiapkan pembaruan alur kerja untuk tim 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": "Mengkoordinasikan alur kerja internal",
      "description": "Menerima maksud alur kerja, memeriksa persyaratan kebijakan, mengumpulkan persetujuan, dan melaporkan status akhir.",
      "tags": [
        "workflow",
        "operations",
        "approval"
      ],
      "examples": [
        "Minta persetujuan untuk menyebarkan pembaruan penggajian."
      ]
    }
  ],
  "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 percaya diri

Cara menyesuaikan contoh Agent Card

Setiap contoh Agent Card sengaja dibuat cukup lengkap untuk disalin, tetapi Agent Card tidak boleh diterbitkan tanpa perubahan. Perlakukan sebagai peta bidang untuk server A2A Anda sendiri: ganti identitas, endpoint, provider, autentikasi, kapabilitas, mode, dan detail skill dengan nilai produksi.

Agent Card terkuat menjelaskan batas tugas agent baik dalam bahasa sederhana maupun metadata yang dapat dibaca mesin. Klien harus dapat mengetahui apa yang bisa dilakukan agent, apa yang tidak bisa dilakukan, URL mana yang harus dipanggil, dan apakah kredensial diperlukan.

Sebelum menerbitkan

Ganti setiap URL example.com dengan endpoint A2A yang telah di-deploy dan situs web provider Anda.

Tulis ulang nama skill, deskripsi, tag (wajib di v1.0), dan contoh untuk batas tugas yang sebenarnya.

Atur provider.organization dan naikkan version tingkat atas setiap kali konten Agent Card berubah.

Hapus bidang autentikasi hanya ketika endpoint sengaja dibuat publik.

Jaga defaultInputModes dan defaultOutputModes tetap selaras dengan apa yang sebenarnya diterima dan dikembalikan server Anda.

Validasi JSON akhir dan terbitkan di /.well-known/agent-card.json pada domain layanan Anda.

Validasi sebuah contoh Baca panduan schema

Siap membangun

Mulai dengan sebuah contoh, lalu jadikan milik Anda sendiri.

Buka pola apa pun di Generator Agent Card, tinjau JSON, dan validasi sebelum menerbitkan.

Buka Generator Agent Card Validasi sebuah Agent Card