Agent2Agent (A2A) Protocol

Tiga hal ini akan membuat perjalananmu jauh lebih mulus:

• HTTP dan JSON: metode, header, kode status, dan Server-Sent Events (text/event-stream), yaitu cara server mengirim kabar terus-menerus lewat satu koneksi. Di A2A, identitas pemanggil dibawa header HTTP, bukan isi pesan.
• JSON-RPC 2.0: request punya id, method, dan params; response membawa result atau error dengan id yang sama. Binding JSON-RPC adalah cara paling umum memanggil agen A2A.
• Agen berbasis LLM: kamu pernah membangun agen yang memanggil alat. Topik Model Context Protocol di bidang ini adalah titik mulai yang dianjurkan, karena A2A paling mudah dipahami sebagai pasangannya.

Untuk mengikuti contoh kodenya dengan SDK resmi, siapkan Python 3.10 atau lebih baru.

Langkah pertama adalah melatih mata: mana sambungan antar-agen, mana sambungan ke alat? Gambar ulang diagram ini dan tunjukkan di mana garis A2A dan MCP lewat:

Untuk setiap sambungan, tanyakan satu hal: yang dihubungi ini alat atau agen?

• Alat (wilayah MCP) punya masukan dan keluaran yang jelas, dan biasanya tanpa keadaan: kalkulator, kueri basis data, layanan cuaca.
• Agen (wilayah A2A) bernalar, merencanakan, memakai banyak alat, menyimpan keadaan selama interaksi panjang, dan bisa bertanya balik.

Latihan: ambil satu sistem multi-agen yang kamu kenal dan tandai setiap sambungannya sebagai A2A atau MCP. Bila sebuah "agen" bisa dipanggil sekali, tanpa keadaan dan tanpa bertanya balik, mungkin sebenarnya ia alat.

Agent Card adalah kartu nama agen, dan setiap server A2A wajib menyediakannya. Alamat bakunya https://{domain}/.well-known/agent-card.json. Inilah kartu agen contoh di halaman ini, diambil apa adanya dari server yang dijalankan lalu dirapikan formatnya:

{
  "name": "Agen Penghitung Kata",
  "description": "Agen contoh yang menghitung kata dalam sebuah teks.",
  "supportedInterfaces": [{
    "url": "http://127.0.0.1:9999",
    "protocolBinding": "JSONRPC",
    "protocolVersion": "1.0"
  }],
  "version": "0.1.0",
  "capabilities": { "streaming": true },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [{
    "id": "hitung-kata",
    "name": "Penghitung kata",
    "description": "Menghitung jumlah kata dalam teks yang dikirim.",
    "tags": ["teks", "contoh"],
    "examples": ["Hitung kata: halo dunia yang indah"],
    "inputModes": ["text/plain"],
    "outputModes": ["text/plain"]
  }]
}

Saat client memilih antarmuka, urutan supportedInterfaces adalah urutan preferensi. Pilih yang pertama yang kamu dukung, pakai URL-nya, dan isi tenant persis seperti tertulis bila ada.

Selain lewat alamat baku, kartu bisa ditemukan lewat registri terkurasi atau konfigurasi langsung. Server dianjurkan mengirim Cache-Control dan ETag supaya client tak perlu mengunduh ulang kartu yang sama; agen contoh di atas sudah mengirim ETag.

Satu Message adalah satu giliran bicara. Ia membawa messageId buatan pengirimnya, role (ROLE_USER dari client, ROLE_AGENT dari agen), dan satu atau lebih Part. Anggap Part sebagai wadah: di versi 1.0, satu Part berisi tepat satu dari empat medan.

Jenis Part dikenali dari medan mana yang ada; medan kind dari versi lama sudah tak dipakai. Panduan migrasi resmi mencontohkannya begini:

if ("text" in part) {
  return part.text;
} else if ("url" in part) {
  return fetchFile(part.url);
} else if ("raw" in part) {
  return decodeBase64(part.raw);
} else if ("data" in part) {
  return part.data;
}

Artifact adalah hasil kerja. Ia punya artifactId yang unik di dalam Task-nya, name, dan Part-nya sendiri. Spesifikasi menganjurkan hasil dikirim sebagai Artifact, bukan Message, karena tak semua pesan disimpan di riwayat Task.

Latihan: rancang Part untuk tiga keluaran: ringkasan teks, grafik PNG, dan tabel hasil dalam JSON.

Banyak kebingungan di A2A bermula dari pengenal. Tiga aturan ini yang paling sering salah:

1. taskId selalu dibuat server. Client tak boleh membuat Task dengan ID-nya sendiri; taskId di pesan client wajib merujuk Task yang sudah ada. Bila tidak, jawabannya -32001 (TaskNotFoundError).
2. contextId mengelompokkan Task dan Message dari satu percakapan. Bila client hanya mengirim taskId, agen menyimpulkan contextId dari Task itu. Bila keduanya dikirim tetapi tak cocok, agen wajib menolak.
3. Task terminal tak bisa dilanjutkan. Perbaikan berarti Task baru di contextId yang sama, dengan referenceTaskIds.

Kamu bisa melihat aturan ini bekerja pada agen contoh: pesan ke Task yang sudah COMPLETED dijawab -32004 ("is in terminal state"), dan contextId yang tak cocok dengan Task-nya dijawab -32602.

Pasang SDK resmi dengan pip install "a2a-sdk[http-server]" uvicorn. Pembagian kerjanya enak: logika agen tinggal di AgentExecutor, SDK mengurus protokolnya. Ini inti agen penghitung kata di halaman ini, diringkas dari contoh helloworld resmi dan sudah dijalankan dengan a2a-sdk 1.2.2:

class PenghitungKataExecutor(AgentExecutor):
    async def execute(self, context, event_queue):
        task = context.current_task or new_task_from_user_message(context.message)
        if not context.current_task:
            await event_queue.enqueue_event(task)
        updater = TaskUpdater(event_queue=event_queue,
                              task_id=task.id, context_id=task.context_id)
        teks = get_message_text(context.message) or ''
        if not teks.strip():
            await updater.update_status(
                state=TaskState.TASK_STATE_INPUT_REQUIRED,
                message=new_text_message('Kirim teks yang ingin dihitung katanya.'))
            return
        await updater.update_status(state=TaskState.TASK_STATE_WORKING)
        await updater.add_artifact(
            parts=[new_text_part(text=f'{len(teks.split())} kata',
                                 media_type='text/plain')],
            name='hasil')
        await updater.update_status(state=TaskState.TASK_STATE_COMPLETED)

Alurnya: ambil atau buat Task, minta teks bila kosong, tandai sedang bekerja, serahkan Artifact, lalu tandai selesai. Untuk menyambungkannya ke web, DefaultRequestHandler menerima executor, InMemoryTaskStore(), dan Agent Card; create_agent_card_routes(card) menyajikan /.well-known/agent-card.json; create_jsonrpc_routes(handler, '/') menerima JSON-RPC; aplikasi Starlette-nya dijalankan dengan uvicorn.

Agen sudah menyala; saatnya menyapanya. Mulailah dari yang paling mentah, satu permintaan HTTP:

curl -s http://127.0.0.1:9999/ \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"msg-1","role":"ROLE_USER","parts":[{"text":"halo dunia yang indah"}]}}}'

Jawabannya Task TASK_STATE_COMPLETED dengan Artifact 4 kata. Berikutnya coba client SDK, yang membaca Agent Card lalu memilih antarmukanya sendiri:

async with httpx.AsyncClient() as http:
    card = await A2ACardResolver(
        httpx_client=http, base_url='http://127.0.0.1:9999').get_agent_card()
client = await create_client(agent=card,
                             client_config=ClientConfig(streaming=True))
pesan = new_text_message('tujuh kata dalam kalimat yang cukup pendek',
                         role=Role.ROLE_USER)
async for potongan in client.send_message(SendMessageRequest(message=pesan)):
    print(potongan)
await client.close()

Saat dijalankan, client ini menerima empat event berurutan: Task SUBMITTED, status WORKING, Artifact, lalu status COMPLETED.

Ingin memeriksa agen tanpa menulis kode? Ada A2A Inspector (Agent Card, pemeriksaan kesesuaian dasar, obrolan, dan konsol JSON-RPC mentah) dan A2A CLI (a2a card get, a2a send).

Bila Agent Card menyatakan capabilities.streaming: true, kamu bisa menonton pekerjaan agen secara langsung lewat SendStreamingMessage. Server menjawab 200 dengan Content-Type: text/event-stream, dan setiap baris data: berisi satu respons JSON-RPC. Pada agen contoh, alirannya terlihat begini (dipendekkan):

data: {"result": {"task": {… "state": "TASK_STATE_SUBMITTED" …}}}
data: {"result": {"statusUpdate": {… "state": "TASK_STATE_WORKING" …}}}
data: {"result": {"artifactUpdate": {… "text": "3 kata" …}}}
data: {"result": {"statusUpdate": {… "state": "TASK_STATE_COMPLETED" …}}}

Spesifikasi menetapkan beberapa aturan untuk aliran ini:

• untuk Task, event pertama selalu objek Task itu sendiri;
• urutan event tak boleh berubah, dan setiap aliran yang terbuka untuk Task yang sama menerima event yang sama;
• aliran ditutup saat Task mencapai keadaan terminal; medan final seperti di 0.3 sudah tidak ada;
• Artifact besar boleh dikirim bertahap: append: true menyambung potongan ke Artifact ber-ID sama, dan lastChunk: true menandai potongan terakhir.

Koneksi putus di tengah jalan? Buka aliran baru dengan SubscribeToTask. Event pertamanya Task dalam keadaan terkini, jadi tak ada kabar yang terlewat di antara GetTask dan berlangganan.

Menunggu pekerjaan berjam-jam dengan koneksi terbuka tentu tidak praktis. Secara bawaan SendMessage menunggu sampai Task terminal atau terputus; untuk pekerjaan panjang, kirim "configuration": {"returnImmediately": true}. Jawabannya Task yang masih berjalan, dan client bebas memilih cara memantaunya.

Push notification butuh capabilities.pushNotifications: true. Client mendaftarkan TaskPushNotificationConfig (url webhook, token opsional, dan authentication) di dalam SendMessage atau lewat CreateTaskPushNotificationConfig. Agen lalu mengirim POST berisi StreamResponse: task, message, statusUpdate, atau artifactUpdate.

• Agen wajib menyertakan kredensial sesuai authentication, dan dianjurkan memvalidasi URL webhook: tolak alamat loopback (127.0.0.0/8), rentang IP privat, dan alamat link-local untuk mencegah SSRF.
• Webhook client wajib memverifikasi pengirimnya dan menjawab 2xx. Kiriman yang sama bisa datang dua kali, jadi proseslah secara idempoten, lalu ambil Task lengkap dengan GetTask.

Agen yang baik tidak menebak; ia bertanya bila perlu. Coba kirim pesan berisi spasi saja ke agen contoh, dan ia menjawab:

{
  "task": {
    "id": "969eea8d-…",
    "status": {
      "state": "TASK_STATE_INPUT_REQUIRED",
      "message": {
        "role": "ROLE_AGENT",
        "parts": [{ "text": "Kirim teks yang ingin dihitung katanya." }]
      }
    }
  }
}

Client melanjutkan dengan Message baru yang membawa taskId yang sama, dan Task yang sama itu berakhir TASK_STATE_COMPLETED.

TASK_STATE_AUTH_REQUIRED dipakai saat agen butuh otorisasi di tengah tugas, misalnya token OAuth untuk API lain atau persetujuan manusia sebelum tindakan yang merusak. Agen wajib memakai Task, menyertakan pesan status yang menjelaskan kebutuhannya, dan menerima kredensial di luar jalur A2A, kecuali disepakati lain lewat ekstensi.

Kabar baiknya, mengamankan agen A2A tidak butuh ilmu baru: perlakukan ia seperti aplikasi web perusahaan biasa.

• Transport: produksi wajib HTTPS (atau TLS untuk gRPC); TLS 1.3 dianjurkan.
• Autentikasi: Agent Card mengumumkan skemanya di securitySchemes dan securityRequirements: kunci API, HTTP auth, OAuth 2.0, OpenID Connect, atau mTLS. Kredensial diperoleh di luar protokol dan dikirim di header setiap permintaan, dan server wajib mengautentikasi setiap permintaan.
• Otorisasi: milik implementasi, misalnya per skill lewat cakupan OAuth. GetTask, ListTasks, dan operasi Task lain wajib dibatasi pada yang boleh dilihat pemanggil, dan pemeriksaannya dilakukan sebelum kueri yang bisa membocorkan keberadaan data.
• Galat: jangan bedakan "tidak ada" dari "tak berhak"; spesifikasi menganjurkan keduanya dijawab sebagai tidak ditemukan.
• Kartu lanjutan: detail yang hanya untuk client tertentu (skill tambahan, kuota) taruh di extended Agent Card, yang hanya dikembalikan GetExtendedAgentCard kepada client terautentikasi.
• Kartu bertanda tangan: buang medan bernilai bawaan dan medan signatures, kanonkan JSON-nya dengan RFC 8785, lalu tanda tangani dengan JWS (RFC 7515). Header terlindungnya memuat alg, typ, dan kid, opsional jku. Client dianjurkan memverifikasi setidaknya satu tanda tangan sebelum memercayai kartu.

Karena 0.3 dan 1.0 masih hidup berdampingan, kamu perlu paham cara keduanya bernegosiasi. Versi A2A berbentuk Major.Minor (misalnya 1.0); nomor patch tidak dipakai saat negosiasi.

1. Client wajib mengirim A2A-Version di setiap permintaan (boleh juga sebagai parameter kueri). Nilai kosong dibaca sebagai 0.3.
2. Server wajib memproses dengan semantik versi yang diminta, atau menjawab VersionNotSupportedError (-32009).
3. Agen yang sedang bermigrasi menawarkan dua antarmuka di supportedInterfaces, satu dengan protocolVersion 0.3 dan satu 1.0, lalu client memilih yang cocok.

Pada agen contoh 1.0 kamu bisa melihat akibatnya: tanpa header jawabannya -32009; dengan A2A-Version: 0.5 juga -32009; dan nama metode 0.3 message/send dijawab -32601 (Method not found).

Sebelum menyatakan agenmu sesuai spesifikasi, jalankan A2A TCK:

./run_tck.py --sut-host http://127.0.0.1:9999 --level must

TCK menguji binding yang diumumkan Agent Card. --level memilih tingkat RFC 2119 (must, should, atau may), dan laporannya ditulis ke folder reports/.