AG-UI: Protokol Ringan untuk Interaksi Agen-Pengguna

Mengapa Aplikasi Agen Membutuhkan AG-UI

Sebelum melihat kodenya, izinkan saya menjelaskan mengapa kita memerlukan protokol baru sejak awal. Ini bermuara pada perbedaan mendasar antara fungsi dan agen.

Keterbatasan request/response

Dalam pengembangan web tradisional, interaksi bersifat transaksional. Anda meminta profil pengguna, dan server mengirimkannya. Ini pertukaran satu kali.

Agen, bagaimanapun, tidak dapat diprediksi dan memakan waktu. Saat Anda meminta agen untuk "debug mengapa pipeline CI Anda tiba-tiba mulai gagal setelah penggabungan rekan tim," ia tidak langsung mengembalikan objek JSON. Sebaliknya, ia mungkin:

1. Mengambil 50 log commit terakhir dari GitHub (Action).
2. Menyadari ada dependensi baru ditambahkan tanpa memperbarui lockfile (Observation).
3. Mencocokkan versi paket tersebut dengan CVE yang diketahui (Reasoning).
4. Menanyakan apakah Anda ingin rollback merge atau melakukan patch ke depan (Human-in-the-loop).

Saya akan menjelaskannya nanti di bagian "Jenis Event", tetapi untuk saat ini, ketahuilah bahwa permintaan HTTP standar akan time-out menunggu semua ini terjadi. Anda memerlukan cara untuk melakukan streaming pembaruan parsial ini agar pengguna tidak menatap layar yang membeku.

Kebutuhan spesifik agen

Agen memerlukan aliran informasi dua arah yang melampaui teks. Mereka perlu menyinkronkan State.

Bayangkan agen membantu Anda menulis laporan. Ia tidak sekadar mengobrol; ia mengedit dokumen. Baik Anda maupun agen mungkin mengetik pada waktu yang sama. AG-UI menangani ini dengan memperlakukan "dokumen" sebagai state bersama, menggunakan pembaruan efisien untuk menjaga layar Anda dan memori agen tetap sinkron tanpa saling menimpa pekerjaan.

Bagaimana Agen dan UI Berkomunikasi

AG-UI menggantikan model Remote Procedure Call (RPC) lama dengan model Event-Sourcing. Alih-alih menunggu jawaban akhir, agen mengirim aliran event yang stabil yang menjelaskan apa yang sedang dilakukannya.

Event stream

Anggap stream AG-UI sebagai ticker berita untuk "otak" agen Anda. Aplikasi klien (frontend Anda) berlangganan ticker ini dan memperbarui UI berdasarkan apa yang terlihat. Pendekatan ini melepaskan keterikatan logika: frontend React Anda tidak perlu tahu bagaimana agen berpikir, ia hanya perlu tahu apa yang harus ditampilkan.

AG-UI menghindari jeda menunggu. Gambar oleh Penulis.

Jenis event inti

Protokol mendefinisikan jenis event standar yang mencakup hampir setiap skenario interaksi. Berikut yang utama yang akan Anda lihat:

1. TEXT_MESSAGE_*: Event yang melakukan streaming teks yang dihasilkan secara bertahap. Ini biasanya melibatkan _START, _CONTENT (aliran token), dan _END yang bersama-sama menciptakan efek "mengetik" yang familier.

2. TOOL_CALL: Menandakan bahwa agen ingin melakukan sesuatu, seperti memeriksa cuaca atau mengkueri database. Yang penting, AG-UI dapat melakukan streaming argumen dari pemanggilan alat, memungkinkan UI Anda mengisi formulir terlebih dahulu bahkan sebelum agen selesai "berbicara."

3.  STATE_DELTA: Inilah penggerak utama untuk kolaborasi. Alih-alih mengirim ulang seluruh dokumen setiap kali satu huruf berubah, agen mengirim "diff" kecil (seperti "tambahkan 'hello' pada indeks 5").

4. INTERRUPT: Katup pengaman. Jika agen mencapai tindakan sensitif (seperti "Delete Database"), ia memancarkan event interrupt. Alur berhenti sampai pengguna mengirim kembali event persetujuan.

Multimodalitas dan langkah berpikir

Protokol ini tidak terbatas pada teks. Ia menangani multimodalitas, yakni melakukan streaming gambar, audio, dan lampiran file bersamaan dengan percakapan. Ini juga menstandarkan Thinking Steps, memisahkan pemikiran internal agen (jejak penalaran) dari respons publik akhir. Anda mungkin memperhatikan pola serupa saat menggunakan alat seperti ChatGPT, di mana indikator progres atau langkah perantara ditampilkan terpisah dari respons akhir. Ini memungkinkan Anda memutuskan apakah akan menampilkan progres eksekusi kepada pengguna atau hanya hasil akhirnya.

Blok Pembangun AG-UI

Sekarang setelah Anda memahami alurnya, mari lihat fitur spesifik yang membuat AG-UI andal bagi pengembang.

Generative UI

Teks itu bagus, tetapi terkadang bagan lebih baik. Generative UI memungkinkan agen memutuskan saat runtime bahwa ia sebaiknya menampilkan komponen UI alih-alih teks.

AG-UI melakukan streaming event; A2UI mendefinisikan komponen. Gambar oleh Penulis.

Ada pembedaan di sini yang sering mengecoh orang (akan saya singgung lagi di bagian framework): AG-UI adalah mekanisme pengiriman (lapisan transport), dan A2UI (Agent-to-User Interface) adalah definisi UI (payload). Agen dapat menggunakan event TOOL_CALL AG-UI untuk mengangkut payload A2UI, sebuah pohon JSON deklaratif yang mendeskripsikan komponen UI (seperti "Kartu Harga Saham"). Frontend Anda menerimanya dan merender bagan sebenarnya.

State bersama dengan JSON Patch

Menangani state bersama itu rumit. Jika agen mengirim objek konteks 5MB besar setiap detik, aplikasi Anda akan tersendat.

AG-UI menyelesaikannya dengan JSON Patch (RFC 6902). Seperti yang saya sebutkan sebelumnya terkait sinkronisasi state, ketika agen mengubah nilai dalam memorinya, ia menghitung perbedaannya dan mengirim STATE_DELTA.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]Didukung oleh

Klien menerima instruksi ringan ini dan menerapkannya ke state lokalnya. Efisiensi inilah yang membuat kolaborasi real-time dengan agen menjadi mungkin.

AG-UI di Lanskap Protokol

Anda mungkin pernah mendengar protokol lain seperti MCP (Model Context Protocol). Penting untuk mengetahui posisi AG-UI dalam tumpukan agar Anda tidak menggunakan alat yang salah untuk pekerjaan yang ada.

Tumpukan agen

Saya suka menganggapnya sebagai segitiga komunikasi:

1. MCP (Agen ↔ Alat): Menghubungkan agen ke dunia backend: database, repo GitHub, dan API internal. Ini tentang mendapatkan informasi.
2. A2A (Agen ↔ Agen): Memungkinkan agen saling berbicara, mendelegasikan tugas ke sub-agen.
3. AG-UI (Agen ↔ Pengguna): Ini adalah "Mil Terakhir." Menghubungkan kecerdasan agen ke pengguna manusia.

Trinitas Protokol yang menghubungkan agen. Gambar oleh Penulis.

AG-UI tidak peduli bagaimana agen mendapatkan data (itu tugas MCP, seperti yang saya sebutkan di atas); yang dipedulikan hanyalah bagaimana menampilkannya kepada Anda.

Menerapkan AG-UI

Mari lihat seperti apa praktiknya. Pengembang biasanya berinteraksi dengan AG-UI dalam tiga cara: membangun 1) Aplikasi Agen (menghubungkan frontend ke agen), membangun 2) Integrasi (membuat framework kompatibel), atau membangun 3) Klien (membuat frontend baru). Kebanyakan dari Anda akan berada di kategori pertama.

Saya akan menjelaskan kodenya sebentar lagi, tetapi pahami dulu bahwa Anda biasanya tidak akan menulis handler protokol mentah sendiri. Pustaka yang menangani pengemasan. Namun memahami alurnya diperlukan untuk debugging.

Membangun kanal event

Kebanyakan implementasi menggunakan Server-Sent Events (SSE) karena sederhana, ramah firewall, dan sempurna untuk streaming satu arah dari server ke klien. Saya sudah menyinggung ini sebelumnya, tetapi SSE adalah kunci yang membuat protokol ini begitu ringan dibandingkan WebSocket.

Dalam penyiapan tipikal (seperti dengan Microsoft Agent Framework atau CopilotKit), server Anda mengekspos endpoint yang meng-upgrade koneksi menjadi stream.

Langganan event sederhana

Berikut contoh konseptual bagaimana klien frontend mendengarkan stream. Perhatikan bagaimana kita menangani berbagai jenis event untuk memperbarui UI.

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};Didukung oleh

Pola ini menyembunyikan kompleksitas logika internal agen. Frontend Anda hanyalah "pemutar" untuk event yang dikirim agen.

Integrasi dan Dukungan Ekosistem

Anda tidak harus membangun semuanya dari nol. Ekosistem berkembang pesat, dengan platform dan framework besar berkonvergensi pada pola interaksi berbasis event yang serupa.

"Segitiga Emas" alat

Microsoft menggambarkan "Segitiga Emas" untuk pengembangan agen:

1. DevUI: Untuk memvisualisasikan proses berpikir agen (debugging).
2. OpenTelemetry: Untuk mengukur performa dan biaya.
3. AG-UI: Untuk terhubung ke pengguna.

Framework yang didukung

Ekosistem ini berkembang pesat. Di luar para pemain besar, dukungan meluas di berbagai lini:

1. Microsoft Agent Framework: Memiliki middleware native untuk ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Bertindak sebagai "Browser" untuk AG-UI, menyediakan frontend React lengkap yang tahu cara merender event ini secara langsung.

3. Ekosistem Python: Framework seperti LangGraph, CrewAI, Mastra, Pydantic AI, Agno, dan LlamaIndex dapat diekspos sebagai endpoint AG-UI.

4. SDK: Meskipun TypeScript dan Python dominan, SDK aktif atau dalam pengembangan untuk Kotlin, Go, Dart, Java, dan Rust.

Keandalan, Debugging, dan Keamanan

Membuka jalur komunikasi langsung antara AI dan browser menimbulkan risiko. Berikut cara menjaga aplikasi Anda tetap aman.

Trusted frontend server

Jangan pernah membiarkan klien terhubung langsung ke runtime agen mentah Anda. Seperti yang saya tekankan di bagian "Mengapa Aplikasi Agen Membutuhkan AG-UI", selalu gunakan Trusted Frontend Server (pola BFF). Server ini bertindak sebagai penjaga gerbang. Ia menambahkan autentikasi, pembatasan laju, dan validasi input sebelum meneruskan pesan pengguna ke agen.

Pertimbangan keamanan

Prompt injection

Pengguna berbahaya mungkin mencoba menimpa instruksi agen Anda melalui serangan prompt injection. Seperti yang saya sebutkan sebelumnya, middleware Anda harus menyanitasi input.

Pemanggilan alat tidak sah

Hanya karena agen bisa menghapus file bukan berarti pengguna saat ini boleh melakukannya. Server tepercaya Anda harus memfilter alat yang tersedia bagi agen berdasarkan izin pengguna.

Keamanan state

Karena state dibagikan melalui JSON patch, waspadalah terhadap prototype pollution. Pastikan pustaka patch Anda melarang perubahan pada properti terlindungi seperti __proto__.

Debugging dengan Dojo

Jika agen Anda bertingkah aneh, gunakan AG-UI Dojo. Ini adalah suite pengujian yang memungkinkan Anda memvisualisasikan stream event mentah. Ini membantu Anda menemukan masalah seperti JSON patch yang salah bentuk atau pemanggilan alat yang berjalan tetapi tidak mengembalikan hasil.

Kesimpulan

Kita telah membahas arsitektur, jenis event, dan pola implementasi AG-UI.

Saya menyadari bahwa pengembang individu atau seseorang di perusahaan kecil tidak serta-merta akan "mengadopsi AG-UI" lalu tiba-tiba "memisahkan frontend dari backend". Semua ini memerlukan keputusan arsitektural yang signifikan, dukungan dari banyak tim, dan sumber daya yang tidak dimiliki kebanyakan orang.

Namun memahami AG-UI tetap penting meskipun Anda tidak menerapkannya. Saat Anda mengevaluasi framework agen atau memutuskan untuk membangun sendiri atau menggunakan platform, mengetahui seperti apa komunikasi agen-UI yang "baik" akan menajamkan penilaian Anda. Anda akan menyadari saat suatu alat memaksa Anda ke pola yang rapuh.

Jika Anda ingin menyelami lebih dalam membangun sistem ini, lihat kursus kami Introduction to AI Agents dan Building Scalable Agentic Systems untuk meningkatkan keterampilan Anda ke level berikutnya.