Membangun Averra AI dengan Kotlin, Spring Boot, dan Next.js

Averra AI adalah workspace AI untuk mencari informasi dari dokumen dan database, membuat file, mengelola tugas, menyusun rencana kerja, serta menjalankan workflow melalui percakapan.

Lingkungan pengembangannya menggunakan Mac dan laptop Ubuntu yang terhubung melalui jaringan USB untuk akses SSH, sedangkan kemampuan laptop Ubuntu untuk menjalankan model dibahas dalam pengujian AI lokal dengan VRAM 6 GiB. Koneksi tersebut menyediakan akses ke mesin Ubuntu, dan hasil pengujiannya menunjukkan beban model yang dapat ditangani perangkat itu.

Melalui aplikasi web, pengguna mengirim pesan, membaca jawaban, dan mengunduh file yang dihasilkan. Di belakangnya, backend memeriksa sesi pengguna, mengakses sumber informasi yang diizinkan, menjalankan pekerjaan, lalu menyimpan hasilnya.

Cara Averra menangani permintaan#

Misalnya, pengguna meminta ringkasan dokumen dalam bentuk spreadsheet. Setelah memeriksa sesi, aplikasi meneruskan pesan dan konteks percakapan kepada agent, yang menggunakan model untuk menentukan langkah yang diperlukan lalu memanggil tools untuk mengerjakannya.

Agent mencari bagian dokumen yang relevan dan menggunakan isinya untuk menyusun spreadsheet. Script pembuat spreadsheet beserta file sementaranya disimpan di workspace, yaitu direktori kerja percakapan, kemudian runner menjalankan script tersebut dalam lingkungan eksekusi terpisah.

Setelah hasilnya diperiksa, agent memanggil tool publish untuk menyimpan spreadsheet sebagai artifact, istilah untuk file hasil yang tersedia melalui aplikasi. Pengguna kemudian dapat mengunduhnya melalui link yang tetap memerlukan pemeriksaan hak akses.

Proses tersebut melibatkan beberapa komponen, yaitu percakapan, pencarian dokumen, eksekusi script, dan penyimpanan file, yang masing-masing ditempatkan pada layanan berbeda sesuai kebutuhan akses dan pekerjaannya.

Backend dan aplikasi web#

Aplikasi web dibangun dengan Next.js dan React, sedangkan backend menggunakan Kotlin dan Spring Boot dengan pekerjaan yang dibagi ke empat layanan.

service-platform menangani akun, percakapan, file, tugas, proyek pengguna, dan rencana mingguan. Assistant dapat mengusulkan penempatan tugas berdasarkan konteks pekerjaan dan waktu yang tersedia, lalu pengguna meninjaunya sebelum rencana diterapkan.

service-agentic menjalankan agent, pencarian dokumen, workflow, dan integrasi model. Workflow disusun sebagai graph yang setiap node-nya mewakili satu langkah kerja, dan tipe input serta output menentukan node mana yang dapat dihubungkan, sehingga ketidakcocokan data dapat ditemukan sebelum eksekusi. Langkah seperti menafsirkan pertanyaan dapat memakai model, sedangkan langkah seperti menyaring tabel menjalankan operasi yang telah ditentukan.

service-runner mengeksekusi script di workspace. Karena script yang dibuat model dapat berisi kesalahan atau perintah yang tidak sesuai, eksekusinya dipisahkan dari proses agent agar script tidak mewarisi akses ke kredensial dan database aplikasi. Runner berjalan sebagai pengguna non-root tanpa kredensial aplikasi, dengan pembatasan filesystem dan jaringan pada deployment container. Akibatnya, runner tidak mengambil bahan dari internet sendiri, melainkan memakai input yang sudah disiapkan agent melalui tools sebelum script dijalankan.

service-browser menyediakan sesi Chromium untuk pekerjaan yang memerlukan interaksi dengan halaman web, dengan proses browser yang terpisah dari layanan yang menjalankan agent dan menyimpan data pengguna.

Keempat layanan tersebut terhubung dengan aplikasi web dan penyimpanan melalui susunan berikut:

flowchart TD
    U[Aplikasi web] --> E[Edge nginx]
    E --> P[service-platform]
    E --> A[service-agentic]
    P <-->|gRPC| A
    A --> R[service-runner]
    A --> B[service-browser]
    P --> D[(dashboard_db)]
    A --> K[(agentic_db)]
    A --> W[Workspace percakapan]
    R --> W

Pada diagram tersebut, nginx menerima request dari aplikasi web dan meneruskannya ke layanan yang sesuai tanpa menangani hal lain selain routing. Kedua layanan yang menerima HTTP API, yaitu platform dan agent, memeriksa token pengguna masing-masing, sehingga pemeriksaan identitas tidak memerlukan proses gateway tambahan.

Pemeriksaan sesi tetap menghubungkan keduanya: layanan agent menanyakan status sesi kepada platform agar token dari sesi yang sudah diakhiri tidak terus digunakan. Konsekuensinya, request ke agent bergantung pada ketersediaan pemeriksaan sesi platform, dan request ditolak jika status sesi tidak dapat dipastikan.

Layanan backend berkomunikasi melalui gRPC agar operasi dan bentuk pesan yang dipertukarkan memiliki kontrak bersama. Kontrak tersebut ditulis dalam protobuf, lalu digunakan untuk menghasilkan kode client dan antarmuka server, sehingga kedua layanan memakai definisi tipe pesan yang sama.

Dukungan streaming pada gRPC dipakai untuk mengirim respons agent secara bertahap melalui StreamPipeline. Pada jalur export, baris spreadsheet dan isi dokumen juga dikirim dalam potongan agar seluruh hasil tidak perlu dikemas menjadi satu pesan besar. Meski begitu, perubahan kontrak tetap perlu menjaga nomor dan tipe field supaya layanan yang masih memakai versi sebelumnya tetap dapat berkomunikasi.

Aplikasi web mengakses endpoint HTTP yang kontraknya dicatat dalam snapshot OpenAPI, sedangkan layanan model AI memakai protokol yang didukung integrasinya. Setiap jalur mengikuti kebutuhan pemakainya, dengan penanganan timeout dan kegagalan koneksi pada layanan yang melakukan panggilan.

Penyimpanan dan akses data#

service-platform menyimpan akun, percakapan, metadata file, tugas, dan proyek di dashboard_db. Data tersebut dikelola dalam satu proses dan satu database karena siklus pengelolaannya saling terkait, sehingga pemeriksaan kuota dan sebagian proses penghapusan data akun, misalnya, dapat ditangani melalui transaksi lokal tanpa koordinasi tambahan antarlayanan.

Setiap bagian platform menyediakan service layer untuk menjalankan aturan akses dan perubahan datanya, sementara aturan import dan pemeriksaan kode menjaga agar bagian lain selalu melewati lapisan tersebut. Pemisahan ini dilakukan pada tingkat kode karena bagian-bagian platform masih berjalan dalam proses yang sama.

service-agentic memakai agentic_db untuk konfigurasi agent, knowledge store, workflow, dan data pendukung eksekusinya. Database ini dipisahkan dari platform agar layanan agent dapat mengelola schema dan migrasinya sendiri, sementara akses ke data pengguna tetap melalui layanan platform. Pemisahan tersebut juga mencegah repository agent mengakses tabel platform secara langsung dan melewati aturan yang berlaku di sana.

Kebutuhan data lintas layanan disampaikan melalui API atau gRPC, dan layanan penerima memeriksa izin sebelum memberikan data, sehingga mengetahui identifier objek saja tidak cukup untuk membukanya. Karena operasi lintas layanan tidak tercakup dalam satu transaksi database, aplikasi juga perlu menangani keadaan ketika satu bagian berhasil dan bagian lain gagal.

Runner dan browser tidak memiliki database aplikasi sendiri. Selama agent bekerja, workspace menampung bahan, script, dan hasil sementara, sedangkan file yang selesai diterbitkan disimpan oleh platform sebagai artifact agar file yang siap diunduh terpisah dari bahan kerja dan hasil antara.

Konfigurasi saat aplikasi berjalan#

Selain memisahkan layanan dan penyimpanan, Averra mengatur sumber data, model, prompt, skills, dan flow melalui konfigurasi yang dapat diubah saat aplikasi berjalan. Skills memuat petunjuk kerja dan pengaturan tools untuk pekerjaan tertentu. Dengan pengaturan ini, sumber informasi dapat ditambahkan atau cara kerja diubah tanpa membuat percabangan kode untuk setiap bidang bisnis. Sebaliknya, jika sumber data dan perilaku khusus ditanam langsung dalam kode, setiap perubahan memerlukan rilis aplikasi dan mengikat agent pada struktur bisnis tertentu.

Misalnya, ketika menjawab pertanyaan dari database, agent menemukan sumber yang tersedia lalu membaca schema sebelum menyusun SQL. Backend kemudian memeriksa statement dan membatasi akses sesuai pengaturan sumber tersebut, sehingga perubahan sumber data tidak menghilangkan pemeriksaan yang harus dilewati setiap query.

Workflow juga disimpan sebagai data berversi. Jadwal terikat pada versi yang dipilih, sehingga mengedit draft tidak mengubah alur yang sedang dijadwalkan, dan struktur graph serta hubungan antarnode diperiksa sebelum dijalankan. Karena pengaturannya dapat berubah saat aplikasi berjalan, sistem juga membutuhkan pemeriksaan izin, validasi, dan pesan kegagalan yang jelas ketika model atau tools yang diperlukan tidak tersedia.

Pembagian layanan menentukan bagaimana permintaan diproses, data diakses, dan hasil disimpan. Kontrak komunikasi dan aturan akses menghubungkan bagian-bagian tersebut, sementara konfigurasi mengatur sumber informasi dan tools yang dapat digunakan.

Pembahasan berikutnya adalah cara Averra menjawab pertanyaan dari database, mulai dari membaca schema dan menyusun SQL hingga memeriksa dan menjalankan query.