Belajar A2A - Registry & Discovery Service

#Pendahuluan

Di episode 15 kita membangun observability: tracing task lifecycle dan audit log. Semua itu berasumsi kita sudah tahu agent mana yang dipanggil. Pertanyaan sebelumnya — bagaimana cara menemukan agent yang tepat di tengah puluhan atau ratusan agent? — belum kita jawab.

Di episode 3 kita belajar Agent Card untuk discovery satu-per-satu: client mengambil card di endpoint standar /.well-known/agent-card.json. Itu bekerja untuk skala kecil. Begitu jumlah agent bertambah, memegang daftar URL secara manual di setiap client tidak akan berkelanjutan. Kita butuh registry: satu tempat terpusat yang menyimpan, memvalidasi, dan menyajikan Agent Card.

Roadmap episode ini: kita mulai dari masalah discovery manual, lalu membangun service registry sebagai Agent Card store, mengenal dynamic discovery dengan heartbeat, melihat katalog ekosistem berisi ratusan agent, dan menutup dengan pola routing untuk memilih agent terbaik.

#Dari Hard-Coded URL Menuju Discovery

Pada skala kecil, pola umum adalah hard-coded URL: orchestrator menyimpan dictionary agent id ke URL dan mengekspornya dari konfigurasi.

config.py — pendekatan awal yang rapuh

AGENTS = {
    "pricing": "https://pricing.example.com/.well-known/agent-card.json",
    "shipping": "https://shipping.example.com/.well-known/agent-card.json",
    "translation": "https://translation.example.com/.well-known/agent-card.json",
}

Pendekatan ini rapuh. Setiap kali ada agent baru, alamat berubah, atau versi di-deploy, seluruh client harus di-update. Agent yang mati tetap dipanggil sampai error muncul. Di sinilah service registry menggantikan konfigurasi statis dengan dynamic discovery.

#Service Registry: Agent Card Store

Service registry adalah server yang menyimpan Agent Card dari banyak agent dan menyediakan API untuk mendaftar, mencari, dan mencabut. Beberapa implementasi registry menyediakan modul discovery langsung di dalam SDK, misalnya modul python_a2a.discovery yang menyediakan AgentRegistry, DiscoveryClient, dan helper enable_discovery.

Alur kerjanya sederhana: agent mendaftarkan card-nya ke registry saat start, registry menyimpan dan menyajikan, client bertanya ke registry untuk menemukan agent.

Endpoint yang umum diungkap registry:

POST /registry/register
POST /registry/unregister
GET  /registry/agents
POST /registry/heartbeat
GET  /a2a/agents

Contoh menjalankan registry dan mendaftarkan agent:

registry.py — jalankan registry

from python_a2a.discovery import AgentRegistry, run_registry
 
registry = AgentRegistry(name="Registry Internal A2A")
run_registry(registry, host="0.0.0.0", port=8000)

agent.py — daftarkan agent ke registry

from python_a2a import AgentCard, A2AServer, run_server
from python_a2a.discovery import enable_discovery
 
agent_card = AgentCard(
    name="kalkulator",
    description="Agent perhitungan harga dan ongkir.",
    url="http://localhost:8001",
    version="1.0.0",
)
agent = A2AServer(agent_card=agent_card)
enable_discovery(agent, registry_url="http://localhost:8000")
run_server(agent, host="0.0.0.0", port=8001)

Instalasi SDK-nya:

pip install python-a2a

#Dynamic Discovery dan Heartbeat

Registry hanya berguna jika datanya akurat. Agent bisa mati kapan saja, dan registry tidak boleh menyajikan agent yang sudah tidak sehat. Dua mekanisme yang menjaga akurasi:

1. Heartbeat — agent mengirim sinyal berkala, misalnya tiap 60 detik. Registry menandai agent yang tidak pernah mengirim heartbeat dalam waktu tertentu sebagai tidak aktif.
2. Pruning — registry secara periodik menghapus agent yang sudah lewat masa tenggang, sehingga daftar tidak dipenuhi sampah.

Client melakukan discovery untuk mendapatkan daftar agent aktif, atau cek langsung lewat curl http://localhost:8000/registry/agents:

client.py — temukan agent dari registry

from python_a2a.discovery import DiscoveryClient
 
client = DiscoveryClient(agent_card=None)
client.add_registry("http://localhost:8000")
agents = client.discover()
 
for agent in agents:
    print(f"{agent.name} at {agent.url} — {agent.description}")

Dynamic discovery membuat topologi jaringan bisa berubah tanpa mengubah kode client. Tambah agent baru, mulai heartbeat-nya, dan dalam hitungan detik agent lain menemukannya. Agent yang pensiun cukup berhenti heartbeat-nya dan otomatis menghilang dari hasil discovery.

#Katalog Ekosistem: Registry Publik

Registry tidak hanya untuk internal. Ekosistem A2A juga punya registry publik yang menampung agent dari banyak organisasi — katalog yang menampung ratusan partner dengan AgentCard terverifikasi. Beberapa registry publik bahkan menampilkan metrik seperti uptime dan latency per agent.

Model registry publik biasanya menyediakan:

• Search berdasarkan kata kunci dan skill tag.
• Filter berdasarkan conformance level (misalnya conformant terhadap spesifikasi versi tertentu).
• Verification — agent card yang telah diuji dan diverifikasi oleh tim registry.
• Metric — uptime, latency, dan status live.

Contoh pola pencarian di registry publik:

curl "https://a2aregistry.org/api/agents?skill=translation"

Kehadiran katalog publik mengubah cara kerja ekosistem. Agent dari organisasi berbeda bisa saling menemukan tanpa negosiasi satu-per-satu — cukup daftar di registry, publish card yang lengkap, dan agent lain yang mencari capabilities yang sama akan menemukanmu.

#Pola Routing: Capabilities, Rating, dan Latency

Menemukan agent hanyalah setengah perjalanan. Setelah dapat daftar kandidat, kita harus memilih yang terbaik untuk task tertentu. Kriteria yang umum dipakai:

• Capabilities — agent harus punya skill yang dibutuhkan task. Ini kriteria filter keras (hard constraint).
• Rating — kepercayaan dari pengalaman sebelumnya atau verifikasi registry.
• Latency — kecepatan respons; makin rendah makin baik.
• Health — status aktif dan stabil.

Pola yang dipakai Twilio untuk routing real-time layak ditiru: pilih node dengan latency terendah di antara yang sehat, dengan failover otomatis ke kandidat kedua jika yang pertama timeout. Karena latency bisa berubah, pengukuran dilakukan berkala, bukan sekali saat startup.

Implementasi scoring sederhana yang menggabungkan ketiga kriteria:

router.py — skor kandidat agent

def score(candidate, task):
    if task.get("capability") not in candidate["capabilities"]:
        return -1
    if candidate["health"] != "healthy":
        return -1
    s = 50.0
    s += candidate["rating"] * 20
    s += max(0.0, 200.0 - candidate["latency_ms"]) * 0.1
    return s
 
def pick_agent(candidates, task):
    return max(candidates, key=lambda c: score(c, task))

Pola yang baik juga menambahkan sticky routing: task yang merupakan kelanjutan dari task sebelumnya diteruskan ke agent yang sama agar session state konsisten, kecuali agent itu jatuh. Dan saat routing gagal, fallback ke kandidat kedua mencegah single point of failure.

#Penutup

Pada episode ini kita menyelesaikan pertanyaan discovery dan routing. Service registry menjadi Agent Card store terpusat dengan API registrasi, pencarian, dan heartbeat untuk menjaga akurasi. Registry publik membuka katalog ekosistem berisi ratusan agent dengan verifikasi dan metrik. Dan pola routing berbasis capabilities, rating, dan latency — terinspirasi pola latency-aware Twilio — memastikan task mendarat di agent yang paling tepat.

Inti yang harus dibawa pulang:

• Service registry menggantikan hard-coded URL dengan dynamic discovery.
• Heartbeat dan pruning menjaga daftar agent tetap akurat di registry.
• Registry publik menyediakan search, filter, verifikasi, dan metrik untuk katalog ekosistem.
• Routing memakai filter keras capabilities, lalu skor berbasis rating dan latency.
• Pola latency-aware ala Twilio memilih node tercepat yang sehat dengan failover otomatis.

Sekarang agent-agent bisa menemukan dan memilih satu sama lain secara dinamis. Namun task yang dikirim masih berupa pola sederhana. Bagaimana jika satu task perlu dipecah ke banyak agent, menunggu persetujuan manusia, atau diulang saat gagal?

Di episode 17 selanjutnya kita akan membahas Advanced Task Patterns: orchestrasi fan-out dan fan-in antar agent, workflow human-in-the-loop dengan state input-required dan resubmission, serta manajemen state seperti idempotency, retry, long-running task, dan checkpoint-resume. Sampai jumpa!