Membangun Agen yang Dipersonalisasi dengan ADK, MCP, dan Bank Memori

1. Pengantar

Stack Agen Modern

Membangun agen AI tingkat produksi memerlukan lebih dari sekadar model bahasa besar (LLM). Meskipun LLM menyediakan kemampuan penalaran, agen yang andal perlu berinteraksi dengan dunia luar, mengelola status percakapan, dan mengingat preferensi pengguna dari waktu ke waktu.

Dalam workshop ini, Anda akan mempelajari cara merancang dan membangun sistem berbasis agen yang komprehensif menggunakan tiga teknologi dasar:

1. Konektivitas (MCP): Untuk memberi agen Anda akses ke alat dan data lokal.
2. Orkestrasi (ADK): Untuk mengelola loop dan status penalaran agen.
3. Memori (Bank Memori): Untuk memberikan konteks jangka panjang yang dipersonalisasi.

Konsep Inti

Komponen	Fungsi
Model Context Protocol (MCP)	Standar universal yang menghubungkan model AI ke sistem eksternal (database, sistem file, API) tanpa integrasi kustom.
Agent Development Kit (ADK)	Framework yang menyediakan lingkungan runtime untuk agen, mengelola loop peristiwa, transisi status, dan eksekusi alat.
Session Service	Menangani memori jangka pendek. Mempertahankan konteks percakapan langsung (misalnya, "Apa yang baru saja ditanyakan pengguna?"), tetapi dihapus saat sesi berakhir.
Vertex AI Memory Bank	Menangani memori jangka panjang. Fitur ini menyimpan fakta dan preferensi spesifik per pengguna (misalnya, "Pengguna lebih suka Python") tanpa batas waktu, sehingga memungkinkan agen mempersonalisasi interaksi di masa mendatang.
Vertex AI Agent Engine	Layanan infrastruktur terkelola yang menghosting logika agen dan komponen memori Anda dalam skala besar.

Yang Akan Anda Buat

Untuk mendemonstrasikan konsep ini, Anda akan membuat Asisten Desain Liburan. Agen ini akan mampu menerima permintaan pengguna tingkat tinggi dan mengatur alat Python lokal secara mandiri untuk membuat kode dan gambar yang dipersonalisasi.

Anda akan melalui tiga tahap:

1. Lapisan Alat: Buat server MCP untuk mengekspos fungsi Python lokal ke AI.
2. Lapisan Agen: Gunakan ADK untuk membangun agen yang merencanakan dan menjalankan alur kerja multi-langkah.
3. Lapisan Memori: Mengintegrasikan Bank Memori untuk memungkinkan agen mempelajari dan mengingat preferensi gaya pengguna.

2. Siapkan

Untuk mendukung agen AI kami, kami memerlukan dua hal: Project Google Cloud untuk menyediakan fondasi.

Bagian Satu: Aktifkan Akun Penagihan

• Untuk mengklaim akun penagihan dengan kredit 5 dolar, Anda akan memerlukannya untuk deployment. Pastikan Anda login ke akun Gmail Anda.

Tidak perlu kartu kredit atau pembayaran — Anda akan menerima kredit gratis senilai $5. Proses ini memerlukan waktu kurang dari 2 menit, cukup masukkan nama Anda dan terima kredit.

Bagian Dua: Lingkungan Terbuka

1. 👉 Klik link ini untuk langsung membuka Cloud Shell Editor
2. 👉 Jika diminta untuk memberikan otorisasi kapan saja hari ini, klik Authorize untuk melanjutkan.
3. 👉 Jika terminal tidak muncul di bagian bawah layar, buka terminal:
   • Klik Lihat
   • Klik Terminal
4. 👉💻 Di terminal, verifikasi bahwa Anda sudah diautentikasi dan project disetel ke project ID Anda menggunakan perintah berikut:

   gcloud auth list
   

5. 👉💻 Clone project bootstrap dari GitHub:

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Jalankan skrip penyiapan dari direktori project.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Catatan tentang Project ID: Skrip akan menyarankan Project ID default yang dibuat secara acak. Anda dapat menekan Enter untuk menyetujui default ini.

   Namun, jika Anda lebih suka membuat project baru tertentu, Anda dapat mengetik Project ID yang diinginkan saat diminta oleh skrip.

   Skrip akan menangani sisa proses penyiapan secara otomatis.
7. 👉💻 Tetapkan Project ID yang diperlukan:

   gcloud config set project $(cat ~/project_id.txt) --quiet
   

Bagian Tiga: Menyiapkan izin

1. 👉💻 Aktifkan API yang diperlukan menggunakan perintah berikut. Tindakan ini memerlukan waktu beberapa menit.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Berikan izin yang diperlukan dengan menjalankan perintah berikut di terminal:

   . ~/holiday_workshop/set_env.sh
   

Perhatikan bahwa file .env dibuat untuk Anda. Bagian ini menampilkan informasi project Anda.

3. Meningkatkan Performa dengan MCP

Momen "USB-C" untuk AI

Bayangkan jika setiap kali Anda membeli mouse baru, Anda harus menyolder mouse tersebut ke motherboard. Begitulah kondisi alat AI hingga saat ini. Developer harus menulis "kode penghubung" kustom untuk menghubungkan LLM ke database, sistem file, atau API.

Masukkan Model Context Protocol (MCP). Anggap MCP sebagai port USB-C untuk aplikasi AI. MCP menyediakan cara standar untuk menghubungkan model AI ke sumber data dan alat.

Jika Anda membangun server MCP untuk alat Anda sekali, Anda dapat memasangnya ke Gemini CLI, IDE, atau klien lain yang kompatibel dengan MCP tanpa mengubah satu baris kode pun.

Yang Akan Anda Buat

Dalam codelab ini, Anda akan membuat Asisten Desain Liburan yang:

1. Terhubung ke lingkungan lokal Anda (alat studio) menggunakan MCP.
2. Mengelola konteks percakapan secara andal menggunakan Agent Development Kit (ADK).
3. Mengingat preferensi Anda (misalnya, "Saya lebih suka kode Python") di berbagai sesi menggunakan Vertex AI Memory Bank.

Peringatan Pastikan Anda telah mengautentikasi Google Cloud CLI (gcloud auth login) sebelum menjalankan contoh kode.

Membangun Logika Server

Kita telah menyiapkan lingkungan, tetapi logika server belum selesai. Kita perlu menerapkan empat alat khusus yang pada akhirnya akan digunakan Agen untuk membuat kartu ucapan liburan.

Bagian Satu: Buka Kerangka Server

Kita akan bekerja di direktori 01-MCP-Files-Testing/01-starter.

1. Di terminal Cloud Shell, pastikan Anda berada di direktori yang benar:

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Buka file di Cloud Shell Editor dengan menjalankan:

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Anda akan melihat kode boilerplate (menyiapkan server MCP, menangani koneksi, dan menginisialisasi klien Vertex AI) sudah selesai. Namun, empat fungsi inti saat ini merupakan placeholder kosong.

Bagian Dua: Menerapkan Generator Suasana Liburan

Pertama, kita memerlukan alat yang mencatat minat pengguna (misalnya, "burung") dan mengubahnya menjadi perintah yang kaya dan mendetail yang dioptimalkan untuk pembuatan gambar.

Temukan komentar #REPLACE_GENERATE_HOLIDAY_SCENE di dalam fungsi generate_holiday_scene.

Ganti seluruh baris ini dengan kode berikut:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Bagian Tiga: Menerapkan Hasil Foto Akhir

Terakhir, kita ingin memastikan pencahayaan dan gaya terlihat fotorealistis dan meriah.

Temukan komentar #REPLACE_GENERATE_FINAL_PHOTO.

Ganti seluruh baris ini dengan kode berikut untuk melakukan transfer dan rendering gaya akhir:

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Penyiapan Lingkungan

Setelah kode ada, kita perlu memastikan dependensi kita telah diinstal. Kita akan menggunakan uv, pengelola project dan paket Python yang cepat.

👉💻 Di terminal, jalankan perintah berikut untuk menambahkan FastMCP sebagai dependensi project kita:

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

Anda akan melihat dependensi baru fastmcp>=2.13.3 ditambahkan ke file ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml Anda.

4. Menguji dengan Gemini CLI untuk Server MCP

Setelah kode server kita selesai, bagaimana cara mengujinya?

Biasanya, menguji server backend memerlukan pembuatan UI frontend atau penulisan permintaan curl yang kompleks. Namun, di sini kita dapat menggunakan Gemini CLI.

Apa itu Gemini CLI?

Gemini CLI adalah alat command line yang memungkinkan Anda melakukan percakapan langsung dengan model Gemini di terminal Anda, tetapi dengan kemampuan super: alat ini dapat otomatis menemukan dan menggunakan alat yang berjalan di server MCP lokal Anda.

Hal ini sangat berguna untuk pengembangan karena mengisolasi logika. Anda dapat memverifikasi bahwa model memahami alat Anda dan memanggilnya dengan benar sebelum Anda khawatir tentang membangun antarmuka web atau framework agen.

Menghubungkan dan Menjalankan

Kita akan memberi tahu Gemini CLI untuk mengelola server kita menggunakan perintah mcp add.

Di terminal Anda, jalankan:

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays: Kami memberi server kami nama panggilan ("liburan").
• uv run ...: Kita memberikan perintah eksplisit untuk memulai server Python yang baru saja kita ubah.

Mari Berkreasi!

Sekarang, mulai sesi chat:

gemini

Coba perintah berikut untuk menguji apakah Gemini dapat "melihat" alat baru Anda. Perhatikan bahwa Anda mungkin perlu mengizinkan Gemini CLI menggunakan alat hari libur kami.

• 👉 Pengguna:

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Pengguna:

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  Karena Anda menggunakan MCP, AI memahami dengan tepat fungsi Python mana yang harus dipanggil untuk memenuhi permintaan Anda.

Meninjau Gambar

• Akhiri Gemini CLI dengan menekan Control+C.
• Periksa gambar yang dihasilkan di folder Anda: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Tinjau foto Anda di sini:

Kesimpulan & Langkah Berikutnya

Selamat! Anda telah berhasil membangun server MCP yang berfungsi. Sekarang Anda memiliki serangkaian "alat AI" fungsional yang dapat membuat pola, menggabungkan gambar, dan menyempurnakan adegan.

Namun, apakah Anda melihat sesuatu dalam pengujian di atas? Anda harus memimpin prosesnya. Anda harus meminta adegan, lalu meminta pola, lalu meminta untuk menggabungkannya.

Meskipun Gemini pintar, untuk alur kerja produksi yang kompleks—di mana kita perlu membuat pola sebelum kita dapat meletakkannya di sweater, dan menangani error jika pembuatan gambar gagal—kita menginginkan kontrol yang lebih besar. Kami menginginkan sistem khusus yang dapat merencanakan, mengkritik karyanya sendiri, dan mengelola status kartu ucapan liburan kami tanpa kami harus membimbingnya di setiap langkah.

Di bagian berikutnya, kita akan mengatur kekacauan kreatif ini. Kita akan menerapkan Agent Development Kit (ADK) untuk membangun Agen terstruktur yang mengatur alat MCP ini ke dalam pipeline produksi yang sempurna.

5. Membuat Kode Vibe untuk Agen ADK

Kita memiliki serangkaian alat yang berfungsi (server MCP), tetapi saat ini, kita yang melakukan semua pekerjaan berat—memberi tahu Gemini alat mana yang harus dipanggil dan kapan.

Di bagian ini, kita akan membangun agen AI: sistem yang dapat berpikir, merencanakan, dan menjalankan tugas multi-langkah secara mandiri. Untuk melakukannya, kita akan menggunakan Agent Development Kit (ADK).

Apa itu Agen?

Jika alat MCP adalah "tangan" (melakukan pekerjaan), Agen adalah "otak". Agen menggunakan LLM untuk memahami niat pengguna ("Buatkan kartu ucapan liburan"), menguraikannya menjadi beberapa langkah ("Pertama, saya perlu adegan, lalu pola..."), dan memutuskan alat mana yang akan digunakan untuk mencapai tujuan.

Apa itu ADK?

Agent Development Kit (ADK) adalah framework dari Google yang memudahkan pembuatan agen ini. Framework ini menangani "mekanisme" yang kompleks, seperti mengelola histori chat, menghubungkan ke alat, dan beralih antar-model yang berbeda—sehingga Anda dapat berfokus pada kepribadian dan logika aplikasi Anda.

Vibe-Coding Berbasis Konteks

Pola umum untuk membuat kode adalah dengan menggunakan satu perintah besar. Namun, saat membangun aplikasi yang kompleks, sering kali lebih baik memperlakukan AI sebagai partner yang mempertahankan konteks dari waktu ke waktu.

Kita akan menggunakan fitur Memory Gemini CLI untuk menyiapkan tahap sebelum menulis satu baris kode.

1. Siapkan Lingkungan

Buka terminal Anda dan buka direktori starter:

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Mulai Gemini CLI:

gemini

2. Mengelola Konteks dan Memori

Saat melakukan pengodean nuansa, AI perlu mengetahui siapa dirinya dan apa yang diketahuinya. Gemini CLI memungkinkan kita mengelola hal ini secara eksplisit.

• /memory show: Ketik ini untuk melihat apa yang saat ini diketahui AI tentang project dan sesi Anda.
• /memory add: Gunakan ini untuk menyuntikkan pengetahuan dasar yang harus diingat AI selama percakapan.

Mari kita mulai dengan menentukan persona partner coding kita. Jalankan perintah berikut di dalam Gemini CLI:

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Gemini kini memahami perannya. Konteks ini akan memengaruhi setiap respons berikutnya, sehingga memastikan kode yang sesuai dengan ADK dan berkualitas tinggi.

3. Langkah 1: Vibe-Coding Agen Dasar

Daripada mencoba membuat seluruh sistem sekaligus, mari kita mulai dengan kerangkanya. Kita akan membuat struktur file dan kepribadian dasar agen.

Masukkan perintah berikut ke Gemini CLI:

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini akan membuat struktur file dan kode Python awal. Tinjau untuk memastikan tampilannya sudah benar, lalu terapkan/terima perubahan.

4. Langkah 2: Menambahkan Server MCP (Alat)

Sekarang setelah memiliki agen dasar, kita perlu memberinya "tangan". Kita perlu menghubungkan agen ke server MCP yang kita buat di lab sebelumnya.

Masukkan perintah berikut ke Gemini CLI:

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Gemini kini akan memfaktorkan ulang agent.py yang ada untuk menyertakan definisi alat dan logika koneksi.

Catatan: Jika Anda ingin memeriksa pekerjaan Anda atau jika kode yang dihasilkan tidak berfungsi seperti yang diharapkan, Anda dapat membandingkan file Anda dengan solusi referensi yang ada di: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Menjalankan Antarmuka Web Agen

ADK dilengkapi dengan antarmuka pengujian bawaan yang disebut adk web. Tindakan ini akan meluncurkan UI chat ringan sehingga kita dapat langsung berbicara dengan agen.

1. Jika Anda masih membuka GeminiCLI, tekan control+C untuk menutupnya. Sekarang di terminal Anda(berada di folder solution, Anda dapat membuka starter untuk menguji kode dengan menjalankan uv run adk web di folder starter), jalankan:

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. Cloud Shell akan memberi tahu Anda bahwa layanan sedang berjalan di port 8000. Klik "Web Preview" -> "Preview on port 8000".

Menguji Agen

Sekarang Anda akan melihat antarmuka chat. Mari kita lihat apakah Agen kita mengikuti petunjuk barunya dan mengakses alat MCP dengan benar.

Coba perintah ini:

• "Halo! Siapa kamu?"
  • (Harapkan respons yang meriah dan antusias).
• "Saya perlu latar belakang untuk kartu ucapan selamat liburan saya. Buat menjadi desa bersalju."
  • (Agen harus memanggil generate_holiday_scene. Perhatikan bagaimana gaya "imut/kartun" yang ditentukan dalam petunjuk sistem diterapkan secara otomatis).
• "Buat pola sweter dengan irisan kecil pizza di atasnya."
  • (Agen harus menelepon generate_sweater_pattern).

Anda dapat melihat gambar yang dibuat di sini:

Tekan Control+C untuk keluar jika Anda selesai melakukan pengujian.

Kesimpulan & Langkah Berikutnya

Anda kini telah berhasil "Mengodekan Suasana" Agen ADK Google menggunakan pendekatan yang sadar konteks.

• Kami menetapkan Konteks: Kami menggunakan /memory add untuk menentukan persona pakar.
• Kami membangunnya secara Iteratif: Kami membuat kerangkanya terlebih dahulu, lalu menambahkan koneksi alat.

Pratinjau web ADK bawaan sangat bagus untuk pengujian, tetapi untuk produk akhir, kami menginginkan pengalaman bermerek yang kustom. Di bagian berikutnya, kita akan mengintegrasikan Agen ini ke frontend web kustom.

Jika Anda mengalami Unexpected response from metadata server: service account info is missing 'email' field kapan saja selama workshop, berarti Anda perlu memuat ulang cloudshell dan menjalankan kembali gcloud config set project $(cat ~/project_id.txt) --quiet untuk menyetel project id sebelum melanjutkan

7. Menghubungkan ADK dengan UI

Setelah memiliki definisi Agen, kita perlu menjalankannya. Di sinilah Runner dan Session Service berperan.

Penerapan

1. 👉 Ketik perintah berikut:

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   Tindakan ini akan membuka ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py di editor Anda.
2. Ganti # TODO: Create Session Service dengan yang berikut:

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   Layanan Sesi adalah "Memori Kerja" agen Anda.

   • Peran: Menyimpan histori langsung yang tidak teratur dari percakapan saat ini (misalnya, "Apa yang baru saja saya tanyakan?").
   • Dua Rasa:
   • InMemorySessionService: Cepat, mudah, tetapi amnesik. Jika Anda memulai ulang server, agen akan melupakan semuanya. Bagus untuk pengujian.
   • VertexAiSessionService: Tangguh, didukung database. Hal ini menyimpan status ke Google Cloud, sehingga percakapan dapat dilanjutkan beberapa minggu kemudian atau saat server dimulai ulang.
3. Ganti # TODO: Initialize Runner dengan yang berikut:

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Runner Jika Agen adalah "Otak", Runner adalah "Jantung". Ini membuat darah tetap mengalir. Runner bertanggung jawab untuk:

• Mengikat Agen ke Pengguna dan Sesi.
• Mengeksekusi Event Loop.
• Mengelola transisi status.

4. Tinjau baris 158 di ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(tidak perlu tindakan): Jika Anda bertanya-tanya bagaimana aplikasi mendapatkan respons akhir? Berikut adalah loop peristiwa yang didukung oleh runner:

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

Agen ADK Event Loop tidak hanya "membalas". Mereka berpikir dalam lingkaran. Saat Anda menelepon runner.run_async():

1. Input Pengguna memasuki loop.
2. Rencana: Agen mempertimbangkan alat dan tujuannya.
3. Bertindak (Act): Jika sesuai, ia memanggil alat (misalnya, list_files).
4. Amati: Membaca output alat.
5. Refleksi (Reflect): Memutuskan apakah perlu lebih banyak info atau dapat menjawab.
6. Loop: Mengulangi langkah 2-5 hingga selesai.
7. Respons: Memberikan jawaban akhir kepada pengguna.

Pembahasan Mendalam: Arsitektur & Deployment

Kita menggunakan FastAPI untuk melayani agen ini.

• Mengapa FastAPI?: Agen sering kali terikat I/O (menunggu LLM). Sifat asinkron FastAPI menangani hal ini dengan sempurna.
• Tanpa status (Statelessness): Perhatikan bahwa endpoint API kita tanpa status. Kita tidak menyimpan variabel dalam cakupan global. Kami mengandalkan session_id dan SessionService untuk merekonstruksi status setiap permintaan. Artinya, Anda dapat men-deploynya ke Cloud Run (Serverless) dan menskalakan ke nol.

8. Coba aplikasi dengan keajaiban agen

1. 👉💻 Ketik perintah berikut:

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   Tindakan ini akan membuka ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py di editor Anda.
2. Anda akan melihat hasil seperti di bawah:👉👉 Pastikan Anda mengklik http://localhost:5173/, atau membuka jendela baru dan mengetik http://localhost:5173/.

   Perhatikan bahwa ini BUKAN link server backend: Uvicorn running on http://0.0.0.0:8000

3. Kemudian Anda akan melihat situs dengan antarmuka chat:
4. Uji dengan mengupload satu gambar(bisa berupa diri Anda sendiri, atau hewan peliharaan Anda)
5. 👉 Kemudian, tanyakan

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   Anda akan melihat gambar yang dibuat di sini:
6. 👉💻 Setelah selesai menguji, tekan control+C di terminal untuk mengakhiri proses.

Jika Anda tidak melihat semuanya berfungsi seperti yang diharapkan, Anda dapat membuka ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution, menjalankan ./start_app.sh, lalu melakukan langkah-langkah yang sama seperti di atas.

9. Vertex AI Memory Bank

Memori Jangka Pendek vs. Jangka Panjang

• Konteks Jangka Pendek: "Apa yang baru saja saya katakan?" (Histori sesi). Hal ini akan hilang saat jendela chat ditutup.
• Memori Jangka Panjang: "Apa bahasa pemrograman favorit saya?" (Preferensi pengguna). Hal ini harus tetap ada selamanya.

Vertex AI Memory Bank menyediakan penyimpanan jangka panjang ini. Hal ini memungkinkan agen menyimpan dan mengambil informasi pribadi tentang pengguna.

Sesi vs. Memory Bank

• Sesi (VertexAiSessionService): Ini adalah Log. Fungsi ini menyimpan urutan mentah dan kronologis setiap pesan, panggilan alat, dan peristiwa (AppendEvent, ListEvents). Fungsi ini memberikan kebenaran dasar untuk apa yang terjadi.
• Bank Memori (VertexAiMemoryBankService): Ini adalah Pengetahuan. Fungsi ini menyimpan fakta jangka panjang yang disintesis (GenerateMemories, RetrieveMemories). Fungsi ini dicakup ke user_id tertentu, sehingga memastikan privasi dan isolasi.

1. 👉💻 Ketik perintah berikut:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   Tindakan ini akan membuka ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py di editor Anda.
2. Temukan # TODO: Create Vertex AI Session Service & Memory Bank Service, ganti seluruh baris dengan kode berikut:

       session_service = VertexAiSessionService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
       memory_service = VertexAiMemoryBankService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
   
   

3. 👉💻 Ketik perintah berikut:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   Tindakan ini akan membuka ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py di editor Anda.
4. Ganti # TODO: Set Up Configuration dengan yang berikut:

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Fitur inti

Vertex AI Memory Bank bukan hanya database; ini adalah layanan kognitif aktif.

• Ekstraksi Memori: Sistem menggunakan LLM untuk membaca percakapan dan mengekstrak fakta yang bermakna berdasarkan skema CustomMemoryTopic yang kami tentukan (misalnya, "Sweater Preferences"). Aplikasi ini mengabaikan percakapan ringan dan menyimpan sinyal.
• Konsolidasi Memori (Memory Consolidation): Secara otomatis menggabungkan fakta baru dengan fakta lama. Jika pengguna mengatakan "Saya suka warna merah", lalu "Sebenarnya, saya lebih suka warna biru", Bank Memori akan mengubah catatan memori, bukan membuat duplikat yang bertentangan.
• Pembuatan Asinkron: Kenangan dibuat di latar belakang. Agen Anda tidak akan terhenti saat Bank Memori "memikirkan" percakapan.

5. 👉 Di file yang sama: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Cari # TODO: Set up topic, ganti seluruh baris dengan kode berikut:

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 Di file yang sama: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Cari # TODO: Create Agent Engine , ganti seluruh baris dengan kode berikut:

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Agent Engine

Agent Engine adalah "Hardware Otak" di Cloud. API ini mengelola:

• Vector Database: Untuk menyimpan kenangan.
• Pengindeksan: Agar kenangan dapat ditelusuri.
• API: Untuk mengizinkan agen mengkuerinya. Saat menjalankan deploy_agent.py, pada dasarnya Anda sedang menyediakan hardware ini.

Mengapa tidak menggunakan saja Prompt?

Anda mungkin bertanya, "Mengapa kita tidak menempelkan saja histori pengguna ke dalam perintah?"

• Batas Ukuran: Jendela konteks berukuran besar, tetapi tidak tak terbatas. Anda tidak dapat menyesuaikan histori 5 tahun.
• Biaya: Memproses 1 juta token untuk setiap "Hello" sangat mahal.
• Fokus: Bank Memori berfungsi sebagai Mesin Telusur untuk agen Anda. Model ini hanya mengambil fakta yang relevan.

7. 👉💻 Ketik perintah berikut:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   Tindakan ini akan membuka ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py di editor Anda.
8. Dalam file: ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyGanti # TODO: Add PreloadMemoryTool dengan yang berikut:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool & add_session_to_memory

Di agent.py, Anda akan melihat dua komponen utama:

• PreloadMemoryTool: Ini adalah alat yang memungkinkan agen "menelusuri Google sendiri". Jika pengguna menanyakan sesuatu yang tidak jelas seperti "Ambilkan kopi biasa saya", agen dapat menggunakan alat ini untuk mengkueri Bank Memori terkait "preferensi kopi" sebelum menjawab.
• add_session_to_memory: Ini adalah callback latar belakang.
  • Mengapa Asinkron? Menyimpan memori memerlukan waktu (meringkas percakapan, mengekstrak fakta). Kita tidak ingin pengguna menunggu hal ini. Kita menjalankannya di latar belakang (add_session_to_memory) menggunakan after_agent_callback.

10. Memory Bank Beraksi

1. 👉💻 Ketik perintah berikut:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Anda akan melihat hasilnya seperti di bawah ini:

   Skrip use_memory_bank.sh ini pertama-tama menggunakan file 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py untuk melampirkan agent engine ke agen Anda sehingga agen Anda dapat menggunakan vertex ai memory bank. Kemudian, file .env akan diperbarui sehingga ID mesin agen disimpan sebagai environmental variable.

   Periksa file ~/holiday_workshop/.env Anda, Anda akan melihat (tidak perlu tindakan)

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Uji memori dengan UI aplikasi. Ketik perintah berikut:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   Pastikan Anda mengklik http://localhost:5173/, atau membuka jendela baru dan mengetik http://localhost:5173/. Perhatikan bahwa Uvicorn running on http://0.0.0.0:8000 hanyalah server backend, bukan link sebenarnya yang ingin kita klik. Sekarang, antarmuka chat di situs telah menjadi agen pribadi Anda.
3. 👉Uji memori. Jika Anda mengetik di UI:

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

Agen akan mengidentifikasi ini sebagai preferensi dan menyimpannya di Bank Memori.

Minggu depan(atau kapan pun Anda memulai ulang aplikasi dengan Control+C dan ./start_app.sh), jika Anda bertanya:

what is my preference on sweater pattern?

Agen akan membuat kueri Bank Memori, melihat preferensi Anda, dan membuat pola sweter tanpa diminta.

Personalisasi Hal ini penting untuk membangun agen yang berguna. Dengan mengingat preferensi pengguna (pola sweter, konteks pribadi), agen menjadi lebih efisien dan bermanfaat seiring waktu.

4. Verifikasi di Vertex AI Agent Engine, dengan membuka Google Cloud Console Agent Engine
   • Pastikan Anda memilih project dari pemilih project di kiri atas:
   • Verifikasi mesin agen yang baru saja Anda deploy dari perintah sebelumnya use_memory_bank.shKlik mesin agen yang baru saja Anda buat.
5. Klik Tab Memories di agen yang di-deploy ini, Anda dapat melihat semua memori di sini.

Selamat! Anda baru saja melampirkan bank memori ke agen Anda.

11. Kesimpulan

Ringkasan

Anda telah berhasil merancang dan membangun sistem agentik yang lengkap.

• Konektivitas: Anda menggunakan MCP untuk menstandardisasi cara agen Anda mengakses alat lokal.
• Orkestrasi: Anda menggunakan ADK untuk mengelola loop penalaran kompleks yang diperlukan untuk tugas multi-langkah.
• Personalisasi: Anda menggunakan Memory Bank untuk membuat lapisan pembelajaran persisten yang mengingat konteks pengguna.

Langkah Berikutnya

• Membangun Server MCP Anda Sendiri: Buat server untuk API atau database internal Anda.
• Mengeksplorasi Pola ADK: Pelajari "Reasoning Loops" dan "Orchestration" dalam dokumentasi ADK.
• Deploy: Pindahkan agen Anda dari skrip lokal ke layanan produksi di Cloud Run.

Terus Membangun Kombinasi MCP untuk konektivitas dan Memory Bank untuk personalisasi menciptakan fondasi bagi aplikasi cerdas generasi berikutnya.