Apa Itu Debugger Agent2Agent (A2A) dan Mengapa Anda Membutuhkannya

Anda membuat agen A2A. Agen sudah terhubung, berjalan, tetapi kadang mengembalikan hasil yang salah. Masalahnya: saat membuka konsol, Anda hanya melihat aliran envelope JSON-RPC dengan field penting terkubur beberapa level di dalam payload. Sulit memastikan apakah bug ada di transport, format pesan, autentikasi, atau logika agen. Di sinilah Debugger Agent2Agent (A2A) berguna.

Coba Apidog hari ini

Artikel ini membahas apa itu debugger A2A, kenapa debugging lalu lintas agent-to-agent sulit tanpa alat khusus, fitur yang perlu ada, dan alur praktis untuk mengisolasi masalah. Jika Anda belum familier dengan protokolnya, mulai dari apa itu Agent2Agent (A2A).

Apa itu debugger A2A?

Debugger A2A adalah alat untuk terhubung ke agen Agent2Agent, mengirim pesan uji, lalu memeriksa request dan response lengkap tanpa menulis kode klien sendiri.

Anggap saja seperti REST client untuk API, tetapi khusus untuk agen A2A. Anda bisa:

• Membaca Agent Card.
• Mengirim pesan uji.
• Menambahkan file, metadata, dan header.
• Melihat payload A2A yang dikirim dan diterima.
• Memeriksa response dalam format mentah maupun yang sudah dirender.

A2A adalah protokol terbuka untuk komunikasi antar agen AI. Protokol ini mendefinisikan Agent Card, siklus hidup task, format message, dan artifact yang dipertukarkan antar agen.

Debugger A2A berfungsi sebagai workbench untuk menjalankan semua bagian tersebut secara manual sebelum Anda memasukkannya ke workflow produksi.

Pertanyaan utama yang harus dijawab debugger adalah:

Dengan Agent Card ini, apa yang sebenarnya dilakukan agen saat menerima pesan ini?

Mengapa debugging A2A sulit tanpa debugger?

Lalu lintas agent-to-agent sering tidak terlihat jelas oleh alat debugging umum.

1. Log konsol tidak selalu cukup

SDK agen hanya mencatat hal yang dipilih oleh pembuatnya. Field seperti task ID, artifact part, metadata, atau payload terstruktur sering tidak muncul di stdout.

Akibatnya, Anda hanya melihat log seperti:

task completed

Tetapi tidak tahu payload apa yang dikirim, response apa yang diterima, atau field mana yang hilang.

2. Network tab sulit dibaca

Browser DevTools bisa menampilkan body HTTP mentah, tetapi payload A2A biasanya berupa JSON-RPC bertingkat.

Untuk menemukan apakah agen mengembalikan bagian text, file, atau artifact lain, Anda harus menggulir JSON panjang yang sulit dibaca.

3. Script uji cepat mudah rusak

Solusi sementara biasanya berupa curl atau script Python kecil.

Contoh:

curl -X POST http://localhost:3000/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Ringkas dokumen ini"
          }
        ]
      }
    }
  }'

Ini berguna untuk satu hari. Namun saat Agent Card berubah, skema autentikasi berganti, atau format pesan diperbarui, script tersebut mudah tidak sinkron.

4. Bug transport dan bug logika terlihat sama

Ketika agen memberi jawaban salah, penyebabnya bisa salah satu dari ini:

• Request tidak sesuai format.
• Header autentikasi salah.
• Metadata tidak sampai ke task handler.
• Koneksi streaming gagal.
• Prompt atau reasoning agen memang salah.

Tanpa melihat payload aktual di kabel, semuanya tampak seperti satu masalah: “agen rusak”.

Debugger A2A mengurangi ambiguitas ini dengan menampilkan request, response, dan field yang bermasalah secara langsung.

Apa yang dilakukan debugger A2A?

Debugger A2A yang baik setidaknya menangani empat area berikut.

1. Koneksi dan discovery

Langkah awal debugging adalah membaca Agent Card.

Biasanya Anda memasukkan URL seperti:

http://localhost:3000/.well-known/agent.json

Debugger kemudian mengambil dan memvalidasi Agent Card tersebut.

Field yang perlu terlihat antara lain:

• Nama agen.
• Deskripsi agen.
• Capability.
• Skill yang dideklarasikan.
• Tipe input yang didukung.
• Versi protokol.
• Endpoint yang digunakan.

Jika Agent Card tidak valid, debugger seharusnya memberi tahu field mana yang hilang atau salah, bukan hanya menampilkan pesan generik.

Contoh masalah yang perlu langsung terlihat:

{
  "error": "Missing required field: skills"
}

Dengan begitu, Anda memperbaiki manifest agen, bukan menebak-nebak masalah di layer lain.

2. Pengujian pesan

Setelah koneksi berhasil, Anda perlu mengirim pesan uji tanpa membuat payload JSON-RPC secara manual.

Debugger yang baik memungkinkan Anda mengirim:

• Teks biasa.
• Lampiran file.
• Metadata kustom.
• Header HTTP.
• Token autentikasi.

Contoh input sederhana:

Tolong ringkas isi dokumen ini dalam 3 poin.

Di belakang layar, debugger membungkus input tersebut ke struktur A2A dan envelope JSON-RPC yang benar.

Ini mengurangi kesalahan manual seperti:

• Salah nama method.
• Salah struktur parts.
• Metadata ditempatkan di level yang keliru.
• Header autentikasi tidak dikirim.

3. Inspeksi response

Ini adalah fungsi terpenting dari debugger A2A.

Response A2A bisa berupa:

• String biasa.
• Artifact terstruktur.
• Referensi file.
• Gabungan text dan file.
• Payload streaming.
• Metadata tambahan.

Debugger yang baik tidak hanya menampilkan JSON mentah. Ia harus memberi beberapa tampilan untuk payload yang sama.

Di Debugger A2A Apidog, misalnya, ada tiga tampilan:

• Pratinjau: menampilkan struktur sebagai tree yang mudah dibaca.
• Konten: menampilkan output seperti yang akan dilihat pengguna.
• Data Mentah: menampilkan payload JSON-RPC lengkap untuk verifikasi field.

Contoh diagnosis:

• Pratinjau terlihat benar, tetapi Konten kosong.
• Artinya agen mungkin mengembalikan artifact terstruktur, tetapi renderer tidak bisa meratakannya menjadi konten pengguna.
• Masalahnya bukan transport, melainkan format output atau cara rendering.

Tanpa tampilan berlapis seperti ini, Anda harus membaca JSON panjang secara manual.

4. Autentikasi dan header

Agen produksi biasanya berada di balik autentikasi, gateway, atau reverse proxy.

Debugger A2A perlu mendukung pola umum seperti:

• Bearer Token.
• Basic Auth.
• API key via custom header.
• Header arbitrer untuk gateway.
• Tenant ID.
• Request signature.

Contoh header:

Authorization: Bearer <token>
X-Tenant-ID: tenant_123
X-Request-ID: debug-run-001

Ini penting karena header dan metadata A2A memiliki fungsi berbeda:

• Header HTTP dibaca oleh gateway, proxy, atau middleware.
• Metadata A2A dibaca oleh task handler agen.

Bug umum terjadi saat developer menaruh instruksi per pesan di header, padahal agen hanya membaca metadata.

Apidog A2A Debugger

Apidog menyediakan Debugger A2A di dalam klien standarnya.

Alur dasarnya:

1. Buka halaman A2A Debugger.
2. Masukkan URL Agent Card, misalnya:

   http://localhost:3000/.well-known/agent.json

1. Klik Connect.
2. Pastikan status berubah menjadi Connected.
3. Periksa metadata agen yang muncul.
4. Buka tab Messages.
5. Ketik pesan uji.
6. Opsional: tambahkan file, metadata, atau header.
7. Klik Send.
8. Baca response melalui Preview, Content, dan Raw Data.

Apidog menangani:

• Envelope JSON-RPC.
• Parsing response.
• Riwayat sesi.
• Server-sent events jika agen mendukung streaming.
• Pemisahan header HTTP dan metadata A2A.

Riwayat sesi berguna saat Anda perlu mengulang pesan yang sama beberapa kali sambil memperbaiki kode agen.

Debugger berjalan sebagai klien lokal. Lalu lintas langsung terjadi antara mesin Anda dan agen, bukan melalui server Apidog.

Untuk panduan lengkap, baca panduan Apidog A2A Debugger. Apidog juga menyediakan AI agent debugger untuk workflow pengujian agen yang lebih luas.

Checklist memilih debugger A2A

Saat membandingkan alat, gunakan checklist berikut.

Validasi Agent Card

Debugger harus menjelaskan kenapa Agent Card gagal.

Contoh output yang membantu:

Invalid Agent Card:
- missing field: name
- unsupported protocolVersion: 0.1
- skills[0].inputModes is required

Bukan hanya:

Failed to connect

Beberapa tampilan response

JSON mentah saja tidak cukup.

Minimal harus ada:

• Tampilan yang mudah dibaca manusia.
• Tampilan konten akhir.
• Payload mentah untuk verifikasi field.

Dukungan autentikasi lengkap

Pastikan mendukung:

• Bearer Token.
• Basic Auth.
• API key.
• Custom header.

Tanpa ini, Anda akan kembali menulis script manual.

Dukungan file dan metadata

Lalu lintas A2A nyata sering membawa lampiran dan konteks per pesan.

Debugger yang hanya mendukung text prompt akan melewatkan sebagian besar permukaan debugging.

Dukungan streaming

Jika agen menggunakan server-sent events, debugger harus bisa menampilkan bagian response saat tiba.

Ini penting untuk memeriksa:

• Chunk yang hilang.
• Urutan event.
• Response yang berhenti sebelum selesai.
• Payload final setelah stream ditutup.

Riwayat sesi

Saat debugging, Anda biasanya mengirim pesan yang sama berkali-kali.

Riwayat sesi membantu Anda:

• Membandingkan hasil sebelum dan sesudah perubahan.
• Mengulang request.
• Melacak payload yang pernah berhasil.
• Menemukan perubahan perilaku agen.

Lalu lintas local-first

Debugger sebaiknya berbicara langsung dengan agen Anda, bukan merutekan payload melalui pihak ketiga.

Ini penting untuk:

• Data internal.
• Prompt sensitif.
• File pengguna.
• Lingkungan lokal atau staging.

Debugger yang memenuhi poin-poin ini mengubah debugging A2A dari tebak-tebakan menjadi proses “konfirmasi payload dulu”. Prinsip yang sama juga digunakan saat menguji agen AI yang memanggil API Anda.

Jika Anda juga menjalankan server MCP, baca panduan server MCP vs A2A untuk memahami kenapa biasanya Anda membutuhkan debugger berbeda untuk tiap protokol.

Alur debugging praktis

Saat agen A2A berperilaku salah, gunakan alur berikut.

1. Sambungkan ke Agent Card

Pastikan Agent Card bisa diambil dan valid.

Periksa:

• Nama agen benar.
• Skill yang diharapkan muncul.
• Input mode sesuai.
• Endpoint benar.
• Versi protokol sesuai.

Jika Agent Card gagal, perbaiki ini terlebih dahulu sebelum menguji pesan.

2. Kirim pesan terkecil

Mulai dari input paling sederhana.

Contoh:

Halo, balas dengan satu kalimat.

Jangan langsung menguji file, metadata, atau instruksi kompleks.

Tujuannya adalah memastikan jalur dasar berfungsi:

client -> agent -> response

3. Periksa raw data terlebih dahulu

Jangan langsung percaya tampilan pratinjau.

Buka Raw Data dan cek:

• Method JSON-RPC.
• Task ID.
• Message role.
• Parts.
• Artifact.
• Metadata.
• Error object jika ada.

Contoh field yang perlu diverifikasi:

{
  "role": "agent",
  "parts": [
    {
      "kind": "text",
      "text": "Halo, saya siap membantu."
    }
  ]
}

Jika field yang diharapkan tidak ada, kemungkinan masalah ada di kode agen.

4. Tambahkan metadata setelah text berhasil

Setelah text sederhana berhasil, baru tambahkan metadata.

Contoh:

{
  "priority": "high",
  "language": "id",
  "tenantId": "tenant_123"
}

Pastikan metadata tersebut muncul di payload A2A, bukan hanya di header HTTP.

5. Tambahkan file terakhir

Jika agen mendukung file, uji setelah text dan metadata berjalan.

Periksa apakah response menyertakan referensi file atau artifact yang benar.

6. Pisahkan bug transport dan bug logika

Gunakan aturan berikut:

• Jika request tidak sampai atau autentikasi gagal, masalah ada di transport atau gateway.
• Jika payload tidak sesuai skema, masalah ada di format request atau kode agen.
• Jika payload valid tetapi jawabannya salah, masalah kemungkinan ada di prompt, model, tool, atau reasoning agen.

Urutan ini membantu Anda menghindari debugging prompt padahal masalah sebenarnya ada di header atau payload.

Pertanyaan umum

Apa itu debugger A2A dalam satu kalimat?

Debugger A2A adalah alat untuk terhubung ke agen Agent2Agent, mengirim pesan uji, dan melihat request serta response lengkap agar Anda bisa men-debug integrasi agen tanpa menulis kode klien.

Bagaimana debugger A2A berbeda dari klien API biasa?

Klien API menguji endpoint HTTP umum.

Debugger A2A memahami struktur di atas HTTP, seperti:

• Agent Card.
• Task lifecycle.
• Message parts.
• Artifact.
• Metadata A2A.
• Payload JSON-RPC.

Jadi Anda tidak hanya melihat body mentah, tetapi juga struktur A2A yang sudah diparse.

Apakah saya masih perlu debugger A2A jika sudah punya log?

Ya.

Log hanya menampilkan hal yang dipilih oleh kode agen untuk dicatat. Debugger menampilkan lalu lintas aktual yang dikirim dan diterima.

Ini membantu membedakan:

• Bug transport.
• Bug autentikasi.
• Bug format payload.
• Bug logika agen.

Untuk konteks protokol, lihat apa itu Agent2Agent (A2A).

Apakah Apidog A2A Debugger gratis?

Ya. Debugger ini dibundel dengan klien standar Apidog. Anda bisa mengunduh Apidog dan membuka A2A Debugger dari panel samping pada versi terbaru.

Dapatkah debugger A2A menguji agen dari framework apa pun?

Ya, selama agen mengekspos Agent Card A2A yang valid.

Protokol A2A bersifat framework-agnostic, sehingga bisa digunakan dengan agen berbasis LangGraph, CrewAI, AutoGen, atau implementasi kustom.

Apakah debugger A2A menangani response streaming?

Debugger yang baik harus bisa melakukannya.

Jika agen mendukung server-sent events, debugger perlu membaca bagian response saat tiba, memperbarui tampilan secara real time, lalu menampilkan payload final setelah stream selesai.