Build Aplikasi Agen AI E2E yang Kuat dan Berstatus di Java dengan ADK, AlloyDB & Gemini!!

Membangun Aplikasi Agen AI E2E yang Kuat dan Berstatus di Java dengan ADK, AlloyDB & Gemini!!

Tentang codelab ini

subjectTerakhir diperbarui Mei 28, 2025
account_circleDitulis oleh Author: Abirami Sukumaran

1. Ringkasan

Di berbagai industri, penelusuran kontekstual adalah fungsi penting yang menjadi inti dan pusat aplikasi mereka. Retrieval Augmented Generation telah menjadi pendorong utama evolusi teknologi penting ini sejak beberapa waktu lalu dengan mekanisme pengambilan yang didukung AI Generatif. Model generatif, dengan jendela konteks yang besar dan kualitas output yang mengesankan, mengubah AI. RAG menyediakan cara sistematis untuk memasukkan konteks ke dalam aplikasi dan agen AI, dengan mendasarkannya pada database terstruktur atau informasi dari berbagai media. Data kontekstual ini sangat penting untuk kejelasan kebenaran dan akurasi output, tetapi seberapa akurat hasil tersebut? Apakah bisnis Anda sangat bergantung pada akurasi kecocokan dan relevansi kontekstual ini? Jika demikian, project ini akan menarik bagi Anda.

Sekarang, bayangkan jika kita dapat memanfaatkan kekuatan model generatif dan membuat agen interaktif yang mampu membuat keputusan otonom yang didukung oleh informasi yang sangat penting dalam konteks tersebut dan didasarkan pada kebenaran; itulah yang akan kita buat hari ini. Kita akan membuat aplikasi agen AI menyeluruh menggunakan Agent Development Kit yang didukung oleh RAG lanjutan di AlloyDB untuk aplikasi analisis paten.

Patent Analysis Agent membantu pengguna menemukan paten yang relevan secara kontekstual dengan teks penelusuran mereka dan setelah diminta, memberikan penjelasan yang jelas dan ringkas serta detail tambahan jika diperlukan, untuk paten yang dipilih. Siap melihat cara melakukannya? Mari kita mulai.

Tujuan

Tujuannya sederhana. Izinkan pengguna menelusuri paten berdasarkan deskripsi tekstual, lalu mendapatkan penjelasan mendetail tentang paten tertentu dari hasil penelusuran, dan semua ini menggunakan agen AI yang dibuat dengan Java ADK, AlloyDB, Vector Search (dengan indeks lanjutan), Gemini, dan seluruh aplikasi yang di-deploy tanpa server di Cloud Run.

Yang akan Anda build

Sebagai bagian dari lab ini, Anda akan:

  1. Membuat instance AlloyDB dan memuat data Set Data Publik Paten
  2. Mengimplementasikan Penelusuran Vektor lanjutan di AlloyDB menggunakan fitur ScaNN & Recall eval
  3. Membuat agen menggunakan ADK Java
  4. Mengimplementasikan logika sisi server database di Cloud Functions serverless Java
  5. Men-deploy & menguji agen di Cloud Run

Diagram berikut menunjukkan alur data dan langkah-langkah yang terlibat dalam penerapan.

c22563ace65a6930.png

High level diagram representing the flow of the Patent Search Agent with AlloyDB & ADK

Persyaratan

  • Browser, seperti Chrome atau Firefox
  • Project Google Cloud yang mengaktifkan penagihan.

2. Sebelum memulai

Membuat project

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project .
  3. Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Aktifkan Cloud Shell di bagian atas konsol Google Cloud.

Gambar tombol Aktifkan Cloud Shell

  1. Setelah terhubung ke Cloud Shell, Anda akan memeriksa apakah Anda sudah diautentikasi dan project ditetapkan ke project ID Anda menggunakan perintah berikut:
gcloud auth list
  1. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.
gcloud config list project
  1. Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:
gcloud config set project <YOUR_PROJECT_ID>
  1. Mengaktifkan API yang diperlukan. Anda dapat menggunakan perintah gcloud di terminal Cloud Shell:
gcloud services enable alloydb.googleapis.com compute.googleapis.com cloudresourcemanager.googleapis.com servicenetworking.googleapis.com run.googleapis.com cloudbuild.googleapis.com cloudfunctions.googleapis.com aiplatform.googleapis.com

Alternatif untuk perintah gcloud adalah melalui konsol dengan menelusuri setiap produk atau menggunakan link ini.

Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.

3. Penyiapan database

Di lab ini, kita akan menggunakan AlloyDB sebagai database untuk data paten. Layanan ini menggunakan cluster untuk menyimpan semua resource, seperti database dan log. Setiap cluster memiliki instance utama yang menyediakan titik akses ke data. Tabel akan menyimpan data sebenarnya.

Mari kita buat cluster, instance, dan tabel AlloyDB tempat set data paten akan dimuat.

Membuat cluster dan instance

  1. Buka halaman AlloyDB di Cloud Console. Cara mudah untuk menemukan sebagian besar halaman di Konsol Cloud adalah dengan menelusurinya menggunakan kotak penelusuran konsol.
  2. Pilih BUAT CLUSTER dari halaman tersebut:

f76ff480c8c889aa.png

  1. Anda akan melihat layar seperti di bawah. Buat cluster dan instance dengan nilai berikut (Pastikan nilainya cocok jika Anda meng-clone kode aplikasi dari repo):
  • cluster id: "vector-cluster"
  • password: "alloydb"
  • PostgreSQL 15 / terbaru direkomendasikan
  • Region: "us-central1"
  • Networking: "default"

538dba58908162fb.png

  1. Saat memilih jaringan default, Anda akan melihat layar seperti di bawah ini.

Pilih SIAPAKAN KONEKSI.
7939bbb6802a91bf.png

  1. Dari sana, pilih "Gunakan rentang IP yang dialokasikan secara otomatis", lalu Lanjutkan. Setelah meninjau informasi, pilih BUAT KONEKSI. 768ff5210e79676f.png
  2. Setelah jaringan disiapkan, Anda dapat terus membuat cluster. Klik CREATE CLUSTER untuk menyelesaikan penyiapan cluster seperti yang ditunjukkan di bawah ini:

e06623e55195e16e.png

Pastikan untuk mengubah ID instance (yang dapat Anda temukan pada saat konfigurasi cluster / instance) menjadi

vector-instance. Jika Anda tidak dapat mengubahnya, jangan lupa untuk menggunakan ID instance Anda di semua referensi mendatang.

Perhatikan bahwa pembuatan Cluster akan memerlukan waktu sekitar 10 menit. Setelah berhasil, Anda akan melihat layar yang menampilkan ringkasan cluster yang baru saja Anda buat.

4. Penyerapan data

Sekarang saatnya menambahkan tabel dengan data tentang toko. Buka AlloyDB, pilih cluster utama, lalu AlloyDB Studio:

847e35f1bf8a8bd8.png

Anda mungkin perlu menunggu instance selesai dibuat. Setelah selesai, login ke AlloyDB menggunakan kredensial yang Anda buat saat membuat cluster. Gunakan data berikut untuk mengautentikasi ke PostgreSQL:

  • Nama pengguna : "postgres"
  • Database : "postgres"
  • Sandi : "alloydb"

Setelah Anda berhasil melakukan autentikasi ke AlloyDB Studio, perintah SQL akan dimasukkan di Editor. Anda dapat menambahkan beberapa jendela Editor menggunakan tanda plus di sebelah kanan jendela terakhir.

91a86d9469d499c4.png

Anda akan memasukkan perintah untuk AlloyDB di jendela editor, menggunakan opsi Run, Format, dan Clear sesuai kebutuhan.

Mengaktifkan Ekstensi

Untuk mem-build aplikasi ini, kita akan menggunakan ekstensi pgvector dan google_ml_integration. Ekstensi pgvector memungkinkan Anda menyimpan dan menelusuri embedding vektor. Ekstensi google_ml_integration menyediakan fungsi yang Anda gunakan untuk mengakses endpoint prediksi Vertex AI guna mendapatkan prediksi di SQL. Aktifkan ekstensi ini dengan menjalankan DDL berikut:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Jika Anda ingin memeriksa ekstensi yang telah diaktifkan di database, jalankan perintah SQL ini:

select extname, extversion from pg_extension;

Membuat tabel

Anda dapat membuat tabel menggunakan pernyataan DDL di bawah di AlloyDB Studio:

CREATE TABLE patents_data ( id VARCHAR(25), type VARCHAR(25), number VARCHAR(20), country VARCHAR(2), date VARCHAR(20), abstract VARCHAR(300000), title VARCHAR(100000), kind VARCHAR(5), num_claims BIGINT, filename VARCHAR(100), withdrawn BIGINT, abstract_embeddings vector(768)) ;

Kolom abstract_embeddings akan memungkinkan penyimpanan untuk nilai vektor teks.

Berikan Izin

Jalankan pernyataan di bawah untuk memberikan eksekusi pada fungsi "penyematan":

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Memberikan PERAN Pengguna Vertex AI ke akun layanan AlloyDB

Dari konsol Google Cloud IAM, berikan akses ke peran "Vertex AI User" ke akun layanan AlloyDB (yang terlihat seperti ini: service-<<PROJECT_NUMBER >>@gcp-sa-alloydb.iam.gserviceaccount.com). PROJECT_NUMBER akan memiliki nomor project Anda.

Atau, Anda dapat menjalankan perintah di bawah dari Terminal Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Memuat data paten ke dalam database

Set Data Publik Paten Google di BigQuery akan digunakan sebagai set data kami. Kita akan menggunakan AlloyDB Studio untuk menjalankan kueri. Data diambil dari file insert_scripts.sql ini dan kita akan menjalankannya untuk memuat data paten.

  1. Di konsol Google Cloud, buka halaman AlloyDB.
  2. Pilih cluster yang baru dibuat, lalu klik instance.
  3. Di menu Navigasi AlloyDB, klik AlloyDB Studio. Login dengan kredensial Anda.
  4. Buka tab baru dengan mengklik ikon Tab baru di sebelah kanan.
  5. Salin pernyataan kueri insert dari skrip insert_scripts.sql yang disebutkan di atas ke editor. Anda dapat menyalin 10-50 pernyataan penyisipan untuk demo singkat kasus penggunaan ini.
  6. Klik Run. Hasil kueri Anda akan muncul di tabel Results.

5. Membuat Embedding untuk data paten

Pertama, mari kita uji fungsi penyematan, dengan menjalankan contoh kueri berikut:

SELECT embedding('text-embedding-005', 'AlloyDB is a managed, cloud-hosted SQL database service.');

Tindakan ini akan menampilkan vektor penyematan, yang terlihat seperti array float, untuk teks contoh dalam kueri. Tampilannya seperti ini:

25a1d7ef0e49e91e.png

Memperbarui kolom Vektor abstract_embeddings

Jalankan DML di bawah untuk memperbarui abstrak paten dalam tabel dengan penyematan yang sesuai:

UPDATE patents_data set abstract_embeddings = embedding( 'text-embedding-005', abstract);

6. Melakukan penelusuran Vektor

Setelah tabel, data, dan penyematan siap, mari kita lakukan Penelusuran Vektor real-time untuk teks penelusuran pengguna. Anda dapat mengujinya dengan menjalankan kueri di bawah:

SELECT id || ' - ' || title as title FROM patents_data ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

Dalam kueri ini,

  1. Teks yang ditelusuri pengguna adalah: "Sentiment Analysis".
  2. Kita mengonversinya menjadi embedding dalam metode embedding() menggunakan model: text-embedding-005.
  3. "<=>" mewakili penggunaan metode jarak COSINE SIMILARITY.
  4. Kita mengonversi hasil metode penyematan ke jenis vektor agar kompatibel dengan vektor yang disimpan dalam database.
  5. LIMIT 10 menunjukkan bahwa kita memilih 10 kecocokan terdekat dari teks penelusuran.

AlloyDB membawa RAG Penelusuran Vektor ke tingkat berikutnya:

Ada banyak hal yang diperkenalkan. Dua dari fitur yang berfokus pada developer adalah:

  1. Pemfilteran Inline
  2. Evaluator Recall

Pemfilteran Inline

Sebelumnya, sebagai developer, Anda harus melakukan kueri Penelusuran Vektor dan harus menangani pemfilteran dan recall. Pengoptimal Kueri AlloyDB membuat pilihan tentang cara menjalankan kueri dengan filter. Pemfilteran inline adalah teknik pengoptimalan kueri baru yang memungkinkan pengoptimal kueri AlloyDB mengevaluasi kondisi pemfilteran metadata dan penelusuran vektor secara bersamaan, dengan memanfaatkan indeks vektor dan indeks pada kolom metadata. Hal ini telah meningkatkan performa recall, sehingga developer dapat memanfaatkan apa yang ditawarkan AlloyDB secara langsung.

Pemfilteran inline paling cocok untuk kasus dengan selektifitas sedang. Saat menelusuri indeks vektor, AlloyDB hanya menghitung jarak untuk vektor yang cocok dengan kondisi pemfilteran metadata (filter fungsional Anda dalam kueri biasanya ditangani dalam klausa WHERE). Hal ini sangat meningkatkan performa untuk kueri ini yang melengkapi keunggulan pasca-filter atau pra-filter.

  1. Menginstal atau mengupdate ekstensi pgvector
CREATE EXTENSION IF NOT EXISTS vector WITH VERSION '0.8.0.google-3';

Jika ekstensi pgvector sudah diinstal, upgrade ekstensi vektor ke versi 0.8.0.google-3 atau yang lebih baru untuk mendapatkan kemampuan evaluator recall.

ALTER EXTENSION vector UPDATE TO '0.8.0.google-3';

Langkah ini hanya perlu dijalankan jika ekstensi vektor Anda <0.8.0.google-3.

Catatan penting: Jika jumlah baris kurang dari 100, Anda tidak perlu membuat indeks ScaNN karena indeks ini tidak akan berlaku untuk baris yang lebih sedikit. Dalam hal ini, lewati langkah-langkah berikut.

  1. Untuk membuat indeks ScaNN, instal ekstensi alloydb_scann.
CREATE EXTENSION IF NOT EXISTS alloydb_scann;
  1. Pertama, jalankan Kueri Penelusuran Vektor tanpa indeks dan tanpa mengaktifkan Filter Inline:
SELECT id || ' - ' || title as title FROM patents_data 
WHERE num_claims >= 15 
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

Hasilnya akan terlihat seperti:

6989de0fc3f0f753.png

  1. Jalankan Explain Analyze di dalamnya: (tanpa indeks atau Pemfilteran Inline)

908dcf87c7f00ed4.png

Waktu eksekusi adalah 2,4 md

  1. Mari kita buat indeks reguler pada kolom num_claims agar kita dapat memfilter berdasarkan kolom tersebut:
CREATE INDEX idx_patents_data_num_claims ON patents_data (num_claims);
  1. Mari kita buat indeks ScaNN untuk aplikasi Penelusuran Paten. Jalankan kode berikut dari AlloyDB Studio:
CREATE INDEX patent_index ON patents_data 
USING scann (abstract_embeddings cosine)
WITH (num_leaves=32);

Catatan penting: (num_leaves=32) berlaku untuk total set data kami dengan lebih dari 1.000 baris. Jika jumlah baris kurang dari 100, Anda tidak perlu membuat indeks karena indeks tidak akan berlaku untuk baris yang lebih sedikit.

  1. Tetapkan Pemfilteran Inline yang diaktifkan di Indeks ScaNN:
SET scann.enable_inline_filtering = on
  1. Sekarang, mari kita jalankan kueri yang sama dengan filter dan Penelusuran Vektor di dalamnya:
SELECT id || ' - ' || title as title FROM patents_data 
WHERE num_claims >= 15 
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

aa54cba2b2ada2cb.png

Seperti yang dapat Anda lihat, waktu eksekusi berkurang secara signifikan untuk Penelusuran Vektor yang sama. Pemfilteran Inline yang diinfusi dengan indeks ScaNN di Penelusuran Vektor telah memungkinkan hal ini.

Selanjutnya, mari kita evaluasi recall untuk Vector Search yang diaktifkan ScaNN ini.

Evaluator Recall

Perolehan dalam penelusuran kemiripan adalah persentase instance relevan yang diambil dari penelusuran, yaitu jumlah positif benar. Ini adalah metrik yang paling umum digunakan untuk mengukur kualitas penelusuran. Salah satu sumber penurunan recall berasal dari perbedaan antara penelusuran perkiraan tetangga terdekat, atau aNN, dan penelusuran tetangga terdekat k (persis), atau kNN. Indeks vektor seperti ScaNN AlloyDB menerapkan algoritma aNN, sehingga Anda dapat mempercepat penelusuran vektor pada set data besar dengan mengorbankan sedikit recall. Sekarang, AlloyDB memberi Anda kemampuan untuk mengukur kompromi ini secara langsung di database untuk setiap kueri dan memastikannya stabil dari waktu ke waktu. Anda dapat memperbarui parameter kueri dan indeks sebagai respons terhadap informasi ini untuk mendapatkan hasil dan performa yang lebih baik.

Anda dapat menemukan recall untuk kueri vektor pada indeks vektor untuk konfigurasi tertentu menggunakan fungsi evaluate_query_recall. Fungsi ini memungkinkan Anda menyesuaikan parameter untuk mencapai hasil recall kueri vektor yang Anda inginkan. Recall adalah metrik yang digunakan untuk kualitas penelusuran, dan didefinisikan sebagai persentase hasil yang ditampilkan yang secara objektif paling dekat dengan vektor kueri. Fungsi evaluate_query_recall diaktifkan secara default.

Catatan Penting:

Jika Anda mengalami error izin ditolak pada indeks HNSW dalam langkah-langkah berikut, lewati seluruh bagian evaluasi recall ini untuk saat ini. Hal ini mungkin terkait dengan batasan akses pada saat ini karena baru dirilis pada saat codelab ini didokumentasikan.

  1. Tetapkan flag Enable Index Scan di indeks ScaNN & indeks HNSW:
SET scann.enable_indexscan = on
SET hnsw.enable_index_scan = on
  1. Jalankan kueri berikut di AlloyDB Studio:
SELECT
  *
FROM
  evaluate_query_recall($$
  SELECT
    id || ' - ' || title AS title,
    abstract
  FROM
    patents_data
    where num_claims >= 15
  ORDER BY
    abstract_embeddings <=> embedding('text-embedding-005',
      'sentiment analysis')::vector
  LIMIT 25 $$,
    '{"scann.num_leaves_to_search":1, "scann.pre_reordering_num_neighbors":10}',
    ARRAY['scann']);

Fungsi evaluate_query_recall mengambil kueri sebagai parameter dan menampilkan recall-nya. Saya menggunakan kueri yang sama dengan yang digunakan untuk memeriksa performa sebagai kueri input fungsi. Saya telah menambahkan SCaNN sebagai metode indeks. Untuk opsi parameter lainnya, lihat dokumentasi.

Recall untuk kueri Penelusuran Vektor ini yang telah kita gunakan:

c98f38fbe6a0b6c5.png

Saya melihat bahwa RECALL adalah 70%. Sekarang saya dapat menggunakan informasi ini untuk mengubah parameter indeks, metode, dan parameter kueri serta meningkatkan recall untuk Penelusuran Vektor ini.

Saya telah mengubah jumlah baris dalam set hasil menjadi 7 (dari 10 sebelumnya) dan saya melihat RECALL yang sedikit meningkat, yaitu 86%.

c12f7b92b8481ceb.png

Artinya, secara real time, saya dapat memvariasikan jumlah kecocokan yang dapat dilihat pengguna untuk meningkatkan relevansi kecocokan sesuai dengan konteks penelusuran pengguna.

Oke sekarang! Saatnya men-deploy logika database dan beralih ke agen.

7. Mentransfer logika database ke web secara serverless

Siap membawa aplikasi ini ke web? Ikuti langkah-langkah di bawah ini:

  1. Buka Fungsi Cloud Run di Google Cloud Console untuk MEMBUAT Fungsi Cloud Run baru atau gunakan link: https://console.cloud.google.com/functions/add.
  2. Pilih Lingkungan sebagai "Cloud Run function". Berikan Nama Fungsi "patent-search" dan pilih Region sebagai "us-central1". Tetapkan Autentikasi ke "Izinkan pemanggilan yang tidak diautentikasi", lalu klik BERIKUTNYA. Pilih Java 17 sebagai runtime dan Editor Inline untuk kode sumber.
  3. Secara default, titik entri akan ditetapkan ke "gcfv2.HelloHttpFunction". Ganti kode placeholder di HelloHttpFunction.java dan pom.xml Fungsi Cloud Run Anda dengan kode dari " PatentSearch.java" dan " pom.xml". Ubah nama file class menjadi PatentSearch.java.
  4. Jangan lupa untuk mengubah placeholder ************* dan kredensial koneksi AlloyDB dengan nilai Anda di file Java. Kredensial AlloyDB adalah kredensial yang telah kita gunakan di awal codelab ini. Jika Anda telah menggunakan nilai yang berbeda, ubah nilai yang sama dalam file Java.
  5. Klik Deploy.

LANGKAH PENTING:

Setelah di-deploy, agar Cloud Function dapat mengakses instance database AlloyDB, kita akan membuat konektor VPC.

Setelah siap untuk deployment, Anda akan dapat melihat fungsi di konsol Google Cloud Run Functions. Telusuri fungsi yang baru dibuat (patent-search), klik fungsi tersebut, lalu klik EDIT AND DEPLOY NEW REVISIONS (diidentifikasi dengan ikon EDIT (pena) di bagian atas konsol Cloud Run Functions) dan ubah hal berikut:

  1. Buka tab Networking:

828cd861864d99ea.png

  1. Pilih "Hubungkan ke VPC untuk traffic keluar", lalu pilih "Gunakan konektor Akses VPC Serverless"
  2. Di bagian dropdown Jaringan, klik dropdown Jaringan dan pilih opsi "Tambahkan Konektor VPC Baru" (jika Anda belum mengonfigurasi konektor default) dan ikuti petunjuk yang Anda lihat di kotak dialog yang muncul:

6559ccfd10e597f2.png

  1. Berikan nama untuk Konektor VPC dan pastikan region-nya sama dengan instance Anda. Biarkan nilai Jaringan sebagai default dan tetapkan Subnet sebagai Rentang IP Kustom dengan rentang IP 10.8.0.0 atau yang serupa yang tersedia.
  2. Luaskan SETELAN PENSCALAAN TAMPILAN dan pastikan Anda telah menetapkan konfigurasi ke hal berikut:

199b0ccd80215004.png

  1. Klik CREATE dan konektor ini akan tercantum di setelan egress sekarang.
  2. Pilih konektor yang baru dibuat.
  3. Pilih agar semua traffic dirutekan melalui konektor VPC ini.
  4. Klik BERIKUTNYA, lalu DEPLOY.
  5. Setelah Cloud Function yang diperbarui di-deploy, Anda akan melihat endpoint yang dihasilkan. Salin dan ganti di perintah berikut:
PROJECT_ID=$(gcloud config get-value project)

curl -X POST <<YOUR_ENDPOINT>> \
  -H 'Content-Type: application/json' \
  -d '{"search":"Sentiment Analysis"}'

Selesai. Begitulah mudahnya melakukan Penelusuran Vektor Kemiripan Kontekstual lanjutan menggunakan model Embedding pada data AlloyDB.

8. Mari kita build agen dengan ADK Java

Pertama, mari kita mulai project Java di editor.

  1. Buka Terminal Cloud Shell

https://shell.cloud.google.com/?fromcloudshell=true&show=ide%2Cterminal

  1. Beri otorisasi saat diminta
  2. Beralih ke Cloud Shell Editor dengan mengklik ikon editor dari bagian atas konsol Cloud Shell

f913b886324e5196.png

  1. Di konsol Cloud Shell Editor landing, buat folder baru dan beri nama "adk-agents"

Klik buat folder baru di direktori root cloud shell Anda seperti yang ditunjukkan di bawah ini:

94c9804697614a94.png

Beri nama "adk-agents":

37445dc1fe08f74c.png

  1. Buat struktur folder berikut dan file kosong dengan nama file yang sesuai dalam struktur di bawah:
adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java
  1. Buka repositori github di tab terpisah dan salin kode sumber untuk file App.java dan pom.xml.
  2. Jika telah membuka editor di tab baru menggunakan ikon "Buka di tab baru" di pojok kanan atas, Anda dapat membuka terminal di bagian bawah halaman. Anda dapat membuka editor dan terminal secara paralel sehingga Anda dapat beroperasi dengan bebas.
  3. Setelah di-clone, alihkan kembali ke konsol Cloud Shell Editor
  4. Karena kita telah membuat Fungsi Cloud Run, Anda tidak perlu menyalin file fungsi Cloud Run dari folder repo.

Memulai ADK Java SDK

Caranya cukup mudah. Anda harus memastikan hal-hal berikut tercakup dalam langkah cloning:

  1. Menambahkan Dependensi:

Sertakan artefak google-adk dan google-adk-dev (untuk UI Web) di pom.xml Anda.

<!-- The ADK core dependency -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk</artifactId>
            <version>0.1.0</version>
        </dependency>
        <!-- The ADK dev web UI to debug your agent -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk-dev</artifactId>
            <version>0.1.0</version>
        </dependency>

Pastikan untuk mereferensikan pom.xml dari repositori sumber karena ada dependensi dan konfigurasi lain yang diperlukan agar aplikasi dapat berjalan.

  1. Mengonfigurasi Project:

Pastikan versi Java (17+ direkomendasikan) dan setelan compiler Maven Anda dikonfigurasi dengan benar di pom.xml. Anda dapat mengonfigurasi project untuk mengikuti struktur di bawah:

adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java
  1. Menentukan Agen dan Alatnya (App.java):

Di sinilah keajaiban ADK Java SDK bersinar. Kita menentukan agen, kemampuannya (petunjuk), dan alat yang dapat digunakannya.

Temukan versi sederhana dari beberapa cuplikan kode class agen utama di sini. Untuk project lengkap, lihat repo project di sini.

// App.java (Simplified Snippets)
package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.InvocationContext;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
// ... other imports

public class App {

    static FunctionTool searchTool = FunctionTool.create(App.class, "getPatents");
    static FunctionTool explainTool = FunctionTool.create(App.class, "explainPatent");

    public static BaseAgent ROOT_AGENT = initAgent();

    public static BaseAgent initAgent() {
        return LlmAgent.builder()
            .name("patent-search-agent")
            .description("Patent Search agent")
            .model("gemini-2.0-flash-001") // Specify your desired Gemini model
            .instruction(
                """
                You are a helpful patent search assistant capable of 2 things:
                // ... complete instructions ...
                """)
            .tools(searchTool, explainTool)
            .outputKey("patents") // Key to store tool output in session state
            .build();
    }

    // --- Tool: Get Patents ---
    public static Map<String, String> getPatents(
        @Schema(name="searchText",description = "The search text for which the user wants to find matching patents")
        String searchText) {
        try {
            String patentsJson = vectorSearch(searchText); // Calls our Cloud Run Function
            return Map.of("status", "success", "report", patentsJson);
        } catch (Exception e) {
            // Log error
            return Map.of("status", "error", "report", "Error fetching patents.");
        }
    }

    // --- Tool: Explain Patent (Leveraging InvocationContext) ---
    public static Map<String, String> explainPatent(
        @Schema(name="patentId",description = "The patent id for which the user wants to get more explanation for, from the database") 
    String patentId, 
    @Schema(name="ctx",description = "The list of patent abstracts from the database from which the user can pick the one to get more explanation for") 
    InvocationContext ctx) { // Note the InvocationContext
        try {
            // Retrieve previous patent search results from session state
            String previousResults = (String) ctx.session().state().get("patents");
            if (previousResults != null && !previousResults.isEmpty()) {
// Logic to find the specific patent abstract from 'previousResults' by 'patentId'
                String[] patentEntries = previousResults.split("\n\n\n\n"); 
                for (String entry : patentEntries) {
                    if (entry.contains(patentId)) { // Simplified check
       // The agent will then use its instructions to summarize this 'report'
                        return Map.of("status", "success", "report", entry);
                    }
                }
            }
            return Map.of("status", "error", "report", "Patent ID not found in previous search.");
        } catch (Exception e) {
            // Log error
            return Map.of("status", "error", "report", "Error explaining patent.");
        }
    }

    public static void main(String[] args) throws Exception {
        InMemoryRunner runner = new InMemoryRunner(ROOT_AGENT);
        // ... (Session creation and main input loop - shown in your source)
    }
}

Komponen Utama Kode Java ADK Disorot:

  1. LlmAgent.builder(): Fluent API untuk mengonfigurasi agen Anda.
  2. .instruction(...): Memberikan perintah dan panduan inti untuk LLM, termasuk kapan harus menggunakan alat mana.
  3. FunctionTool.create(App.class, "methodName"): Mendaftarkan metode Java Anda dengan mudah sebagai alat yang dapat dipanggil agen. String nama metode harus cocok dengan metode statis publik yang sebenarnya.
  4. @Schema(description = ...): Menambahkan anotasi pada parameter alat, yang membantu LLM memahami input yang diharapkan setiap alat. Deskripsi ini sangat penting untuk pemilihan alat dan pengisian parameter yang akurat.
  5. InvocationContext ctx: Dilewati secara otomatis ke metode alat, yang memberikan akses ke status sesi (ctx.session().state()), informasi pengguna, dan lainnya.
  6. .outputKey("patents"): Saat alat menampilkan data, ADK dapat menyimpannya secara otomatis dalam status sesi berdasarkan kunci ini. Ini adalah cara explainPatent dapat mengakses hasil dari getPatents.
  7. VECTOR_SEARCH_ENDPOINT: Ini adalah variabel yang menyimpan logika fungsi inti untuk Tanya Jawab kontekstual bagi pengguna dalam kasus penggunaan penelusuran paten.
  8. Item Tindakan di sini: Anda perlu menetapkan nilai endpoint yang di-deploy dan diperbarui setelah menerapkan langkah Fungsi Java Cloud Run dari bagian sebelumnya.
  9. searchTool: Ini berinteraksi dengan pengguna untuk menemukan pencocokan paten yang relevan secara kontekstual dari database paten untuk teks penelusuran pengguna.
  10. explainTool: Ini meminta pengguna untuk memilih paten tertentu yang akan dipelajari lebih lanjut. Kemudian, sistem ini akan meringkas abstrak paten dan dapat menjawab lebih banyak pertanyaan dari pengguna berdasarkan detail paten yang dimilikinya.

Catatan Penting: Pastikan untuk mengganti variabel VECTOR_SEARCH_ENDPOINT dengan endpoint CRF yang di-deploy.

Memanfaatkan InvocationContext untuk Interaksi Berstatus

Salah satu fitur penting untuk membuat agen yang berguna adalah mengelola status di beberapa giliran percakapan. InvocationContext ADK mempermudah hal ini.

Di App.java:

  1. Saat initAgent() ditentukan, kita menggunakan .outputKey("patents"). Hal ini memberi tahu ADK bahwa saat alat (seperti getPatents) menampilkan data di kolom laporannya, data tersebut harus disimpan dalam status sesi di bagian kunci "patents".
  2. Dalam metode alat explainPatent, kita memasukkan InvocationContext ctx:
public static Map<String, String> explainPatent(
    @Schema(description = "...") String patentId, InvocationContext ctx) {
    String previousResults = (String) ctx.session().state().get("patents");
    // ... use previousResults ...
}

Hal ini memungkinkan alat explainPatent mengakses daftar paten yang diambil oleh alat getPatents pada giliran sebelumnya, sehingga percakapan menjadi stateful dan koheren.

9. Pengujian CLI Lokal

Menentukan variabel lingkungan

Anda harus mengekspor dua variabel lingkungan:

  1. Kunci Gemini yang dapat Anda peroleh dari AI Studio:

Untuk melakukannya, buka https://aistudio.google.com/apikey dan dapatkan Kunci API untuk Project Google Cloud aktif tempat Anda menerapkan aplikasi ini dan simpan kunci di suatu tempat:

ae2db169e6a94e4a.png

  1. Setelah Anda mendapatkan kunci, buka Terminal Cloud Shell dan beralih ke direktori baru yang baru saja kita buat, adk-agents, dengan menjalankan perintah berikut:
cd adk-agents
  1. Variabel untuk menentukan bahwa kita tidak menggunakan Vertex AI kali ini.
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY=AIzaSyDF...
  1. Menjalankan agen pertama Anda di CLI

Untuk meluncurkan agen pertama ini, gunakan perintah Maven berikut di terminal Anda:

mvn compile exec:java -DmainClass="agents.App"

Anda akan melihat respons interaktif dari agen di terminal.

10. Men-deploy ke Cloud Run

Men-deploy agen Java ADK ke Cloud Run mirip dengan men-deploy aplikasi Java lainnya:

  1. Dockerfile: Membuat Dockerfile untuk memaketkan aplikasi Java Anda.
  2. Build & Push Docker Image: Gunakan Google Cloud Build dan Artifact Registry.
  3. Anda dapat melakukan langkah di atas & men-deploy ke Cloud Run hanya dengan satu perintah:
gcloud run deploy --source . --set-env-vars GOOGLE_API_KEY=<<Your_Gemini_Key>>

Demikian pula, Anda akan men-deploy Fungsi Cloud Run Java (gcfv2.PatentSearch). Atau, Anda dapat membuat dan men-deploy Fungsi Cloud Run Java untuk logika database langsung dari konsol Fungsi Cloud Run.

11. Menguji dengan UI Web

ADK dilengkapi dengan UI Web yang praktis untuk pengujian dan proses debug lokal agen Anda. Saat Anda menjalankan App.java secara lokal (misalnya, mvn exec:java -Dexec.mainClass="agents.App" jika dikonfigurasi, atau hanya menjalankan metode utama), ADK biasanya memulai server web lokal.

UI Web ADK memungkinkan Anda untuk:

  1. Kirim pesan ke agen Anda.
  2. Lihat peristiwa (pesan pengguna, panggilan alat, respons alat, respons LLM).
  3. Periksa status sesi.
  4. Melihat log dan rekaman aktivitas.

Hal ini sangat berharga selama pengembangan untuk memahami cara agen memproses permintaan dan menggunakan alat-alatnya. Hal ini mengasumsikan bahwa mainClass Anda di pom.xml ditetapkan ke com.google.adk.web.AdkWebServer dan agen Anda terdaftar dengan agen tersebut, atau Anda menjalankan runner pengujian lokal yang mengeksposnya.

Saat menjalankan App.java dengan InMemoryRunner dan Scanner untuk input konsol, Anda menguji logika agen inti. UI Web adalah komponen terpisah untuk pengalaman proses debug yang lebih visual, yang sering digunakan saat ADK menayangkan agen Anda melalui HTTP.

Anda dapat menggunakan perintah Maven berikut dari direktori root untuk meluncurkan server lokal SpringBoot:

mvn compile exec:java -Dexec.args="--adk.agents.source-dir=src/main/java/ --logging.level.com.google.adk.dev=TRACE --logging.level.com.google.adk.demo.agents=TRACE"

Antarmuka ini sering kali dapat diakses di URL yang dihasilkan perintah di atas. Jika Cloud Run di-deploy, Anda akan dapat mengaksesnya dari link Cloud Run yang di-deploy.

Anda akan dapat melihat hasilnya di antarmuka interaktif.

Tonton video di bawah untuk Agen Paten yang di-deploy:

Demo Agen Paten yang Dikontrol Kualitasnya dengan Evaluasi Recall & Penelusuran Inline AlloyDB.

ca7b0fc4fe571dd6.png

12. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam postingan ini, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud, buka https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog
  2. Halaman https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog.
  3. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
  4. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

13. Selamat

Selamat! Anda telah berhasil membuat Agen Analisis Paten di Java dengan menggabungkan kemampuan ADK, https://cloud.google.com/alloydb/docs?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog, Vertex AI, dan Vector Search. Selain itu, kami telah melakukan lompatan besar dalam membuat penelusuran kemiripan kontekstual menjadi sangat transformatif, efisien, dan benar-benar berbasis makna.

Mulai Sekarang.

Dokumentasi ADK: [Link to Official ADK Java Docs]

Kode Sumber Agen Analisis Paten: [Link ke Repo GitHub Anda (sekarang publik)]

Agen Contoh Java: [link to the adk-samples repo]

Bergabunglah dengan Komunitas ADK: https://www.reddit.com/r/agentdevelopmentkit/

Selamat membuat agen.

bug_report Laporkan kesalahan