Belajar A2A - Agent Card & Discovery

#Pendahuluan

Di episode 2 kita menyebut Agent Card sebagai gerbang discovery — metadata JSON yang membuat remote agent bisa "ditemukan" dan dipahami. Sekarang saatnya membedah dokumen itu field per field.

Episode 3 akan membuat kalian mampu dua hal: membaca Agent Card milik agent lain dengan percaya diri, dan menyusun Agent Card sendiri yang benar. Kita juga akan menelusuri sisi discovery-nya: bagaimana card dipublikasikan, di-fetch, dan — sejak v1.0 — bagaimana keasliannya diverifikasi lewat signed security card.

#Anatomi Agent Card

Agent Card adalah dokumen JSON yang dipublikasikan remote agent. Saat client ingin bekerja sama, inilah yang pertama kali ia baca. Field dasarnya sederhana:

{
  "name": "Agent Analisis Laporan",
  "description": "Membaca laporan keuangan dan merangkum risiko",
  "url": "https://analisis.example.com",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true
  },
  "skills": [],
  "authentication": {}
}

• name — nama singkat agent; kadang ditulis agentName pada versi awal.
• description — penjelasan fungsi agent, dipakai untuk matching kebutuhan.
• url — endpoint tempat client mengirim task (JSON-RPC endpoint).
• version — versi Agent Card itu sendiri.

#Capabilities: Apa yang Didukung Agent

Bagian capabilities mendeklarasikan kemampuan komunikasi agent. Ini penting karena client harus menyesuaikan cara bicaranya:

{
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "skills": {
      "readReport": true
    }
  }
}

• streaming — apakah agent mendukung respons parsial via SSE. Jika false, client hanya bisa menunggu hasil akhir.
• pushNotifications — apakah agent bisa menerima notifikasi push ke webhook (kita akan praktikkan di episode 7).
• skills — daftar kemampuan khusus yang dimiliki agent, dengan properti tambahan seperti deskripsi dan contoh input-output.

#Skills: Definisi Task yang Didukung

Bagian skills berisi daftar kemampuan tugas agent. Ini menjadi dasar routing: client mencocokkan kebutuhan dengan skill yang tersedia.

{
  "skills": [
    {
      "id": "summarize-report",
      "name": "Meringkas Laporan",
      "description": "Menerima dokumen dan menghasilkan ringkasan eksekutif",
      "tags": ["keuangan", "riset"],
      "examples": [
        {
          "name": "Ringkas PDF laporan triwulan",
          "description": "Input PDF, output ringkasan dengan poin risiko"
        }
      ]
    }
  ]
}

Setiap skill memiliki id unik, deskripsi yang bisa dipahami agent lain, dan examples — contoh input-output yang membantu client memahami cara memakai skill tersebut. Field tags memudahkan pencarian kemampuan di registry besar (topik episode 16).

#Authentication: Menyatakan Kebutuhan Akses

Field authentication memberi tahu client skema autentikasi yang wajib dipenuhi sebelum mengirim task. Jika kosong, endpoint terbuka untuk umum:

{
  "authentication": {
    "schemes": ["bearer"],
    "credentials": "client"
  }
}

• schemes — daftar skema yang didukung, misal bearer, oauth2, atau apikey.
• credentials — pihak yang memegang kredensial; nilai client berarti client yang harus menyediakan token.

Detail alur OAuth 2.1, API key, dan JWT akan kita bedah di episode 9. Untuk sekarang, yang perlu diingat: field ini adalah deklarasi, dan client berkewajiban menyesuaikan dirinya sebelum berkomunikasi.

#Signed Security Card: Keaslian di v1.0

Sejak v1.0, Agent Card bisa ditandatangani — hasilnya disebut signed security card. Tujuannya sederhana tapi krusial: memastikan card yang kalian baca benar-benar diterbitkan oleh agent yang mengaku menerbitkannya.

{
  "security": {
    "jwt": {
      "algorithm": "RS256",
      "issuer": "https://analisis.example.com",
      "subject": "agent-analisis",
      "audience": ["registry-a2a"]
    }
  },
  "signature": {
    "algorithms": ["RS256"]
  }
}

Field security.jwt berisi klaim identitas — penerbit, subjek, audiens — yang disusun sebagai JWS (JSON Web Signature). Client yang menerima card bisa memverifikasi tanda tangan menggunakan kunci publik penerbit. Kalau verifikasi gagal, card dianggap tidak tepercaya dan kolaborasi dihentikan. Keamanan penuh dari mekanisme ini akan kita dalami di episode 9 dan 14.

#Discovery: Publikasi, Fetcher, dan Verifikasi

#Publikasi URL

Cara paling sederhana memublikasikan Agent Card adalah menaruhnya di URL yang stabil — biasanya endpoint akar dari server agent:

curl -s https://analisis.example.com/.well-known/agent-card

Standar tidak mewajibkan satu path, tetapi konvensi .well-known/agent-card dipakai luas. Beberapa agent menawarkan endpoint khusus untuk card, misal /agent-card, yang mengembalikan JSON langsung — coba keduanya dengan curl -s https://analisis.example.com/.well-known/agent-card.

#Fetcher dan Cache

Setelah mengambil card, client biasanya menyimpannya di cache agar tidak mem-fetch ulang setiap kali ingin berkomunikasi. Pola umumnya:

• Ambil card saat inisialisasi koneksi pertama.
• Simpan bersama waktu kedaluwarsa (TTL).
• Muat ulang saat TTL habis atau saat terjadi error yang berhubungan dengan perubahan kapabilitas.

Praktik caching ini sangat berpengaruh pada performa saat satu client berkomunikasi dengan banyak remote agent — topik yang akan kita optimalkan di episode 18.

#Verifikasi Card

Sejak v1.0, flow discovery yang aman menjadi: fetch card, verifikasi tanda tangan security card-nya, baru memutuskan untuk berkomunikasi.

1. Ambil card dari URL remote agent
2. Cek field security.jwt ada atau tidak
3. Verifikasi tanda tangan dengan kunci publik issuer
4. Cocokkan klaim issuer dengan host yang diakses
5. Jika valid -> lanjut kirim task; jika tidak -> tolak

Langkah ketiga dan keempat mencegah serangan spoofing — situasi di mana penyerang memublikasikan card palsu atas nama agent lain. Kita akan membahas spoofing dan mitigasinya secara mendalam di episode 14.

#Penutup

Inilah inti yang harus dibawa pulang:

• Agent Card adalah metadata JSON dengan name, description, url, capabilities, skills, dan authentication.
• capabilities mendeklarasikan streaming, push notification, dan skill komunikasi.
• skills mendeskripsikan task yang bisa dikerjakan, lengkap dengan contoh input-output.
• authentication menyatakan skema keamanan yang wajib dipenuhi client.
• Signed security card di v1.0 memungkinkan verifikasi keaslian via tanda tangan JWS.
• Discovery mengalir dari publikasi URL, fetch, cache, hingga verifikasi sebelum berkomunikasi.

Di episode 4 kita masuk ke jantung eksekusi: Task lifecycle & messages — state machine dari submitted sampai completed/failed, progress dan metadata, peran message user/agent, tipe part teks/file/terstruktur, hingga streaming delta. Kalian akan memahami bagaimana sebuah task benar-benar "dikerjakan" di atas protokol. Sampai jumpa!