Belajar A2A - Konsep Dasar & Arsitektur Utama

#Pendahuluan

Di episode 1 kita memahami kenapa A2A lahir: agent dari framework berbeda butuh bahasa bersama, dan interaksi dipilih sebagai peer yang opaque. Sekarang saatnya melihat bagaimana protokol ini terstruktur.

Episode 2 adalah peta konsep. Kalian akan memahami dua peran utama — client agent dan remote agent — lalu empat blok penyusun: Agent Card, Task, Message/Part, dan binding protokol. Setiap blok akan dibedah lebih dalam di episode 3 sampai 5, jadi fokuslah pada bagaimana semuanya terangkai menjadi satu alur.

#Dua Peran: Client Agent dan Remote Agent

Seluruh arsitektur A2A bertumpu pada dua peran:

• Client Agent — pihak yang mengirim task. Ia yang memulai percakapan, meminta pekerjaan dilakukan, dan menerima hasil.
• Remote Agent — pihak yang menerima dan mengerjakan task. Ia menyediakan layanan agent melalui sebuah endpoint HTTP.

Penting untuk dipahami: peran ini tidak permanen. Satu agent bisa menjadi client dalam satu kolaborasi dan remote agent dalam kolaborasi lain. Inilah sifat peer-to-peer yang kita bahas di episode 1 — tidak ada hierarki abadi antara kedua peran.

Client Agent  --(1) ambil Agent Card-->  Server endpoint
Client Agent  --(2) kirim task-------->  Remote Agent
Remote Agent  --(3) balas status------>  Client Agent
Remote Agent  --(4) kirim hasil------->  Client Agent

#Agent Card: Gerbang Discovery

Sebelum mengirim task, client agent harus menemukan dan memahami remote agent. Di sinilah Agent Card berperan — sebuah dokumen JSON yang dipublikasikan remote agent di URL publiknya. Isinya mendeskripsikan siapa agent itu dan apa yang bisa dilakukannya:

{
  "name": "Agent Dukungan",
  "description": "Membantu troubleshooting produk",
  "url": "https://dukungan.example.com",
  "capabilities": {
    "streaming": true
  }
}

Konsepnya persis analog dengan OpenAPI: sebelum memanggil API, client membaca spec-nya. Hanya saja, Agent Card fokus pada kemampuan agent, bukan sekadar daftar endpoint. Episode 3 akan membedah seluruh field-nya. Untuk melihat card dalam bentuk aslinya, coba curl -s https://dukungan.example.com/.well-known/agent-card.

#Task Lifecycle: Kontrak Komunikasi

Satu unit kerja dalam A2A disebut Task. Task-lah yang menjadi "benang" penghubung seluruh percakapan antara client dan remote agent. Setiap task memiliki identifier, status, dan riwayat pesan.

{
  "id": "task-123",
  "status": {
    "state": "working"
  },
  "messages": []
}

Status task mengalir melalui state machine: dari submitted, menjadi working, bisa berhenti di input-required jika agent butuh informasi tambahan, dan berakhir di completed, failed, atau canceled. Detail state machine ini akan kita bedah tuntas di episode 4.

#Message dan Part: Konten Multimodal

Percakapan dalam sebuah task direpresentasikan sebagai rangkaian Message, dan setiap message berisi satu atau lebih Part. Keindahan model ini: konten tidak terbatas pada teks.

Seorang agent bisa mengirim hasil berupa teks plus file CSV plus data terstruktur dalam satu message. Kemampuan multimodal inilah yang membedakan A2A dari sekadar API teks biasa — dan akan kita praktikkan di episode 8.

#Binding Protokol: JSON-RPC, HTTP, gRPC, dan SSE

A2A tidak mengikat diri pada satu transport. Model datanya didefinisikan di atas JSON-RPC 2.0, tetapi bisa diangkut lewat beberapa binding:

• JSON-RPC over HTTP — binding utama; request dikirim lewat POST ke satu endpoint.
• SSE (Server-Sent Events) — kanal streaming untuk hasil real-time dari remote agent ke client.
• gRPC — tersedia sejak v0.3, cocok untuk throughput tinggi dan backpressure (detail di episode 11).

Pemisahan antara model data dan transport ini membuat A2A fleksibel: logika protokol tidak berubah saat kalian pindah dari HTTP ke gRPC. Inilah salah satu alasan desainnya bertahan sampai v1.0.

#Menyatukan Semua Komponen

Sekarang mari kita rangkai seluruh blok menjadi satu alur utuh. Kolaborasi A2A berjalan seperti ini:

1. Client agent memuat Agent Card dari URL remote agent untuk mengetahui kemampuan dan cara autentikasi.
2. Client mengirim task via metode message/send melalui binding JSON-RPC over HTTP.
3. Remote agent merespons dengan status task, berjalan dari submitted ke working.
4. Jika streaming diaktifkan, hasil parsial mengalir lewat SSE sebagai kumpulan Message/Part.
5. Task selesai dengan status completed, membawa hasil akhir multimodal.
6. Client bisa membaca seluruh percakapan kapan saja melalui metode tasks/get.

Secara teknis, langkah kedua terlihat seperti ini lewat HTTP:

curl -s -X POST https://dukungan.example.com \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send","params":{"message":{"role":"user","parts":[{"text":"Bantu analisis log error"}]}}}'

Semua langkah ini bekerja tanpa client pernah melihat state internal, memory, atau tools milik remote agent — konsisten dengan prinsip opaque yang kita pelajari di episode 1.

#Penutup

Inilah inti yang harus dibawa pulang:

• Arsitektur A2A terdiri dari dua peran dinamis: client agent dan remote agent.
• Agent Card adalah metadata JSON untuk discovery, analog dengan OpenAPI.
• Task adalah unit kerja tunggal yang membawa seluruh percakapan dan statusnya.
• Message/Part memungkinkan konten multimodal: teks, file, dan data terstruktur.
• Model JSON-RPC 2.0 bisa diangkut lewat HTTP, SSE, dan gRPC tanpa mengubah isi pesan.

Di episode 3 kita membedah komponen pertama secara menyeluruh: Agent Card & discovery — mulai dari field agentName, description, capabilities, skills, authentication, hingga security card bertanda tangan di v1.0. Kalian akan belajar membaca dan menyusun Agent Card sendiri. Sampai jumpa!