Dari Prototipe ke Agen dengan ADK

1. Ringkasan

Di mana titik awal membangun dengan AI saat ini? Bagi sebagian besar dari kita, sering kali dimulai dengan pertanyaan sederhana, "Apakah model ini benar-benar dapat membantu memecahkan masalah yang sedang saya pikirkan?". Di sinilah Google AI Studio berperan. Ini adalah tempat di mana Anda dapat membuat prototipe apa pun dengan cepat. Saya ingin merenovasi dapur dan saya yakin Gemini dapat membantu, tetapi saya seorang insinyur, bukan kontraktor umum. Saya bahkan tidak yakin apa yang harus diminta - ada begitu banyak hal yang perlu dipertimbangkan: peraturan, perlengkapan, dll. Jadi, mari kita uraikan hal ini dan minta Gemini membuat perintah yang sangat mendetail untuk kita, lalu membuat rencana renovasi lengkap dan juga memvisualisasikan renovasi tersebut. Tapi tunggu. Bagaimana saya dapat membantu bisnis meningkatkan skala, mulai dari sini? MASUKKAN AGEN!!!

Agen adalah program otonom yang berkomunikasi dengan model AI untuk melakukan operasi berbasis tujuan menggunakan alat dan konteks yang dimilikinya serta mampu membuat keputusan otonom yang didasarkan pada kebenaran.

Agent Development Kit (ADK)

Agent Development Kit (ADK) adalah framework fleksibel dan modular untuk mengembangkan dan men-deploy agen AI. ADK mendukung pembangunan aplikasi canggih dengan menyusun beberapa instance agen yang berbeda ke dalam Sistem Multi-Agen (MAS).

Di ADK, sistem multi-agen adalah aplikasi tempat berbagai agen, yang sering kali membentuk hierarki, berkolaborasi atau berkoordinasi untuk mencapai tujuan yang lebih besar. Menyusun aplikasi dengan cara ini menawarkan keuntungan yang signifikan, termasuk modularitas, spesialisasi, kemampuan penggunaan ulang, kemudahan pemeliharaan, dan kemampuan yang ditingkatkan untuk menentukan alur kontrol terstruktur menggunakan agen alur kerja khusus.

Yang akan Anda build

Siap beralih dari PROMPT prototipe kami ke Membangun agen? Kita akan membuat agen untuk membantu membuat dokumen proposal proyek renovasi dapur. Sebagai bagian dari lab ini, Anda akan:

  1. Membangun agen sederhana untuk membuat Dokumen Proposal Renovasi dengan ADK
  2. Menyimpan Dokumen Proposal Renovasi yang dihasilkan di Bucket Cloud Storage
  3. Menguji agen di Cloud Shell dan di output web agen

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. Selain itu, jika Anda membaca artikel ini dan ingin mendapatkan beberapa kredit untuk membantu Anda memulai Google Cloud dan menggunakan ADK, gunakan link ini untuk menukarkan kredit.
  4. Anda dapat mengikuti petunjuk di sini untuk menukarkannya. Perhatikan bahwa link ini hanya valid hingga 15 Juli 2025 untuk penukaran.
  5. Aktifkan Cloud Shell dengan mengklik link ini. Anda dapat beralih antara Cloud Shell Terminal (untuk menjalankan perintah cloud) dan Editor (untuk membuat project) dengan mengklik tombol yang sesuai dari Cloud Shell.
  6. Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah 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. Pastikan Anda memiliki Python 3.9+

Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya yang lain.

3. Prototipe

Buka Google AI Studio. Mulai ketik perintah Anda. Berikut perintah saya:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

Sesuaikan & konfigurasi parameter di sisi kanan untuk mendapatkan respons yang optimal.

Berdasarkan deskripsi sederhana ini, Gemini membuatkan perintah yang sangat mendetail untuk memulai renovasi rumah saya. Dengan kata lain, kami menggunakan Gemini untuk mendapatkan respons yang lebih baik dari AI Studio dan model kami. Anda juga dapat memilih model yang berbeda untuk digunakan, berdasarkan kasus penggunaan Anda.

Kita telah memilih Gemini 2.5 Pro. Ini adalah model Pemikiran, yang berarti kita mendapatkan lebih banyak token output, dalam hal ini hingga 65 ribu token, untuk analisis bentuk panjang dan dokumen mendetail. Kotak pemikiran Gemini muncul saat Anda mengaktifkan Gemini 2.5 Pro yang memiliki kemampuan penalaran bawaan dan dapat menerima permintaan konteks panjang.

Lihat cuplikan respons di bawah:

4e4361663df80964.png

AI Studio menganalisis data saya dan menghasilkan semua hal ini seperti lemari, meja dapur, backsplash, lantai, wastafel, kohesi, palet warna, dan pemilihan material. Gemini bahkan mencantumkan sumber kutipan.

Sekarang, coba lihat ide tersebut menjadi kenyataan dengan perintah yang berbeda.

  1. Salin perintah ini dan tempelkan di editor perintah:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Lampirkan gambar dapur Anda saat ini (atau Anda dapat menggunakan contoh gambar dapur saya).
  2. Ubah model ke "Gemini 2.0 Flash Preview Image Generation" agar Anda memiliki akses untuk membuat gambar.

Saya mendapatkan output ini:

fb33e7b1f6560a0c.png

Itulah kecanggihan Gemini.

Mulai dari memahami video, hingga pembuatan gambar native, hingga merujuk informasi nyata dengan Google Penelusuran – ada hal-hal yang hanya dapat dibuat dengan Gemini.

Dari AI Studio, Anda dapat mengambil prototipe ini, mendapatkan kunci API, dan menskalakannya menjadi aplikasi agentik lengkap menggunakan kecanggihan Vertex AI ADK.

4. Penyiapan ADK

Sekarang, mari kita beralih ke Cloud Shell Terminal yang kita aktifkan di bagian "Sebelum memulai":

  1. Membuat & Mengaktifkan Lingkungan Virtual (Direkomendasikan)

Dari Terminal Cloud Shell, buat Lingkungan Virtual:

python -m venv .venv

Aktifkan Lingkungan Virtual:

source .venv/bin/activate
  1. Instal ADK
pip install google-adk

5. Struktur Project

  1. Dari Terminal Cloud Shell, buat direktori root untuk aplikasi agentik di lokasi project yang Anda inginkan:
mkdir agentic-apps
  1. Di dalam direktori utama, buat satu folder khusus untuk project saat ini:
mkdir renovation-agent
  1. Buka editor Cloud Shell dan buat struktur project berikut dengan membuat file (kosong untuk memulai):
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Kode Sumber

  1. Buka "init.py" dan perbarui dengan konten berikut:
from . import agent
  1. Buka agent.py dan perbarui file dengan konten berikut dari jalur berikut:

Di agent.py, kita mengimpor dependensi yang diperlukan, mengambil parameter konfigurasi dari file .env, dan menentukan root_agent yang membuat dokumen proposal dan menyimpannya di Bucket Cloud Storage. Untuk melakukan langkah Cloud Storage, kita menggunakan alat yang disebut store_pdf.

CATATAN: Saat ini, PDF TIDAK DIFORMAT! Berdasarkan PR dev komunitas, cuplikan berikut telah disertakan di sini [tidak diuji], silakan sesuaikan ini di dalam metode store_pdf:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"
  1. Pastikan Anda memiliki Bucket Cloud Storage

Ini untuk menyimpan dokumen proposal yang dibuat agen. Buat dan sediakan akses sehingga sistem agentic yang kita buat dengan Vertex AI dapat mengaksesnya. Berikut cara melakukannya:

https://cloud.google.com/storage/docs/creating-buckets#console

Beri nama bucket Anda "next-demo-store". Jika Anda memberi nama lain, jangan lupa untuk memperbarui nilai STORAGE_BUCKET dalam file .env (di langkah Penyiapan Variabel ENV).

  1. Untuk menyiapkan akses ke bucket, buka konsol Cloud Storage dan Bucket Penyimpanan Anda (dalam kasus ini, nama bucket-nya adalah "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage.

Buka Permissions -> View Principals -> Grant Access. Pilih Principal sebagai "allUsers" dan Peran sebagai "Storage Object User".

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
  1. Membuat daftar dependensi

Mencantumkan semua dependensi di requirements.txt. Anda dapat menyalinnya dari repo.

Penjelasan Kode Sumber Sistem Agen Tunggal

File agent.py menentukan struktur dan perilaku sistem multi-agen renovasi dapur kita menggunakan Agent Development Kit (ADK). Mari kita uraikan komponen utamanya:

Definisi Agen

Root Agent (Orchestrator): proposal_agent

root_agent bertindak sebagai orkestrator sistem agen tunggal ini. Agen menerima permintaan renovasi awal dan menentukan alat yang akan dipanggil berdasarkan kebutuhan permintaan.

Kemudian, root_agent mengumpulkan respons dari alat dan menggabungkannya untuk memberikan respons yang komprehensif kepada pengguna. Dalam hal ini, kita hanya memiliki satu alat "store_pdf".

7. Alur Data & Konsep Utama

Pengguna memulai permintaan melalui antarmuka ADK (baik terminal maupun UI web).

  1. Permintaan diterima oleh root_agent.
  2. root_agent menganalisis permintaan dan merutekannya ke alat sesuai kebutuhan.
  3. Alat "store_pdf" dirancang untuk menulis konten teks yang telah diperbarui ke file PDF, lalu menguploadnya ke Google Cloud Storage.
  4. Kemudian, respons ini akan ditampilkan ke root_agent.
  5. root_agent menggabungkan respons dan memberikan output akhir kepada pengguna.

LLM (Model Bahasa Besar)

Agen sangat mengandalkan LLM untuk menghasilkan teks, menjawab pertanyaan, dan melakukan tugas penalaran. LLM adalah "otak" di balik kemampuan agen untuk memahami dan merespons permintaan pengguna. Kami menggunakan Gemini 2.5 dalam aplikasi ini.

Google Cloud Storage

Digunakan untuk menyimpan dokumen proposal renovasi yang dibuat. Anda perlu membuat bucket dan memberikan izin yang diperlukan agar agen dapat mengaksesnya.

Cloud Run (Opsional)

OrderingAgent menggunakan fungsi Cloud Run untuk berinteraksi dengan AlloyDB. Cloud Run menyediakan lingkungan serverless untuk mengeksekusi kode sebagai respons terhadap permintaan HTTP.

AlloyDB

Jika menggunakan OrderingAgent, Anda harus menyiapkan database AlloyDB untuk menyimpan informasi pesanan.

file.env

File .env menyimpan informasi sensitif seperti kunci API, kredensial database, dan nama bucket. Penting untuk menjaga keamanan file ini dan tidak melakukan commit ke repositori Anda. Selain itu, file ini juga menyimpan setelan konfigurasi untuk agen dan project Google Cloud Anda. Fungsi root_agent atau pendukung biasanya akan membaca nilai dari file ini. Pastikan semua variabel yang diperlukan disetel dengan benar dalam file .env. Hal ini mencakup nama bucket Cloud Storage

8. Penyiapan Model

Kemampuan agen Anda untuk memahami permintaan pengguna dan menghasilkan respons didukung oleh Model Bahasa Besar (LLM). Agen Anda perlu melakukan panggilan yang aman ke layanan LLM eksternal ini, yang memerlukan kredensial autentikasi. Tanpa autentikasi yang valid, layanan LLM akan menolak permintaan agen, dan agen tidak akan dapat berfungsi.

  1. Dapatkan kunci API dari Google AI Studio.
  2. Pada langkah berikutnya saat Anda menyiapkan file .env, ganti <<your API KEY>> dengan nilai KUNCI API Anda yang sebenarnya.

9. Penyiapan Variabel ENV

  1. Siapkan nilai untuk parameter di file .env template di repo ini. Dalam kasus saya, .env memiliki variabel berikut:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Ganti placeholder dengan nilai Anda.

10. Menjalankan Agen Anda

  1. Menggunakan terminal, buka direktori induk project agen Anda:
cd agentic-apps/renovation-agent
  1. Instal semua dependensi
pip install -r requirements.txt
  1. Anda dapat menjalankan perintah berikut di terminal Cloud Shell untuk menjalankan agen:
adk run .
  1. Anda dapat menjalankan perintah berikut untuk menjalankannya di UI web yang disediakan ADK:

Catatan: Anda harus menjalankan perintah ini dari LUAR folder project agen, keluar satu langkah dari folder tersebut, lalu jalankan perintah:

adk web
  1. Uji dengan perintah berikut:
user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Hasil

Untuk perintah adk run . hasilnya adalah sebagai berikut"

2703603a907329ae.png

ae56b38cc6da9afe.png

...

91452a4de933a75b.png

Anda dapat memvalidasi apakah dokumen Proposal Renovasi dibuat di Bucket Cloud Storage.

12. Men-deploy ke Cloud Run

  1. Buat file bernama Dockerfile di dalam folder root project:
cd agentic-apps/renovation-agent
  1. Salin konten dari repo github
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

ke dalam file Dockerfile ini.

  1. Deploy di Cloud Run menggunakan perintah berikut:
adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

Selesai. Setelah di-deploy, Anda akan melihat endpoint di terminal yang siap digunakan.

13. Pembersihan

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

  1. Di konsol Google Cloud, buka halaman Manage resources.
  2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
  3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

14. Selamat

Selamat! Anda telah berhasil membuat dan berinteraksi dengan aplikasi multi-agen menggunakan ADK. Sistem multi-agen ini dirancang untuk menyederhanakan proses renovasi dapur dengan mengotomatiskan tugas seperti pembuatan proposal, pemeriksaan izin, dan pelacakan status pesanan. Setiap agen memiliki peran tertentu, dan root_agent mengoordinasikan aktivitas mereka untuk memberikan solusi yang komprehensif. Sistem ini memanfaatkan LLM, layanan Google Cloud, dan berpotensi API eksternal untuk menghadirkan fungsinya. Berikut adalah link ke dokumentasi produk.