Panduan memulai: Menambahkan memori jangka panjang ke agen ADK dengan Memory Bank

Agent Platform Memory Bank memberi agen yang Anda bangun dengan Agent Development Kit (ADK) memori jangka panjang lintas sesi. Dalam panduan memulai ini, Anda akan menjalankan agen yang mempelajari suhu pilihan pengguna dalam satu sesi dan mengingat preferensi tersebut di sesi berikutnya.

Panduan memulai ini akan memandu Anda melalui langkah-langkah berikut:

  • Menyiapkan lingkungan Anda.
  • Membuat instance Memory Bank.
  • Menjalankan agen ADK yang mendukung memori secara lokal.
  • Pastikan agen mengingat preferensi dalam sesi baru.

Untuk memanggil Memory Bank secara langsung tanpa ADK, lihat panduan memulai Memory Bank API. Untuk memilih alat memori, callback, atau runtime lainnya, lihat Menggunakan Memory Bank dengan ADK.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  10. Siapkan lingkungan pengembangan Python.
  11. Jika Anda menggunakan shell lokal, buat kredensial autentikasi lokal untuk akun pengguna Anda:

    gcloud auth application-default login

    Anda tidak perlu melakukannya jika menggunakan Cloud Shell.

    Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, pastikan Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat instance Memory Bank serta membuat dan mengambil memori, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

  • Membuat atau memperbarui instance Memory Bank: Agent Platform User (`roles/aiplatform.user`)
  • Membaca, menulis, atau membuat memori: Memory Bank User (`roles/aiplatform.memoryUser`)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menyiapkan lingkungan Anda

  1. Di terminal Anda, instal ADK dan Agent Platform SDK:

    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  2. Tetapkan variabel lingkungan yang dibaca oleh skrip dalam panduan memulai ini:

    export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=global

    Ganti PROJECT_ID dengan project ID Google Cloud Anda.

    Panduan memulai ini menggunakan endpoint global. Untuk menggunakan lokasi regional atau multi-regional, ganti global dengan salah satu lokasi yang didukung. Jika Anda memerlukan kunci enkripsi yang dikelola pelanggan (CMEK), gunakan lokasi regional atau multi-regional, karena CMEK tidak tersedia dengan endpoint global.

    Jalankan bagian selanjutnya dari panduan memulai ini di sesi terminal dan direktori yang sama agar skrip dapat membaca variabel ini.

Membuat instance Memory Bank

  1. Buat file bernama create_memory_bank.py dengan kode berikut:

    import os
    
    import agentplatform
    
    client = agentplatform.Client(
        project=os.environ["GOOGLE_CLOUD_PROJECT"],
        location=os.environ["GOOGLE_CLOUD_LOCATION"],
    )
    
    memory_bank = client.memory_banks.create(
        config={"display_name": "Memory Bank quickstart"}
    )
    
    # Print only the instance ID, for example 1234567890.
    print(memory_bank.name.split("/")[-1])
    
  2. Jalankan skrip dan simpan ID instance dalam variabel lingkungan MEMORY_BANK_ID:

    export MEMORY_BANK_ID=$(python create_memory_bank.py)

    Jika ini adalah instance Memory Bank pertama Anda, pembuatan dapat memakan waktu 1-2 menit.

  3. Pastikan variabel berisi ID instance:

    echo $MEMORY_BANK_ID

    Output-nya adalah ID seperti 1234567890. Jika output kosong atau menampilkan error 401 atau 403, periksa peran yang diperlukan dan jalankan gcloud auth application-default login. Jika instance global baru menampilkan error 403 sementara pada penggunaan pertama, tunggu 30 detik dan jalankan skrip lagi.

Menjalankan agen yang mendukung memori

Skrip di bagian ini menjalankan dua sesi untuk pengguna yang sama. Pada sesi pertama, pengguna menyatakan preferensi suhu. Pada sesi kedua, agen mengingat preferensi tersebut dari Memory Bank.

Selesaikan langkah-langkah berikut:

  1. Buat direktori bernama memory_agent:

    mkdir memory_agent
  2. Buat file bernama memory_agent/agent.py dengan kode berikut. Kode ini membaca project, lokasi, dan ID instance Anda dari variabel yang Anda tetapkan di Menyiapkan lingkungan Anda dan Membuat instance Memory Bank. Anda tidak perlu mengedit kode.

    import asyncio
    import os
    
    import agentplatform
    from google import adk
    from google.adk.agents.callback_context import CallbackContext
    from google.adk.memory import VertexAiMemoryBankService
    from google.adk.sessions import InMemorySessionService
    from google.adk.tools.preload_memory_tool import PreloadMemoryTool
    from google.genai import types
    
    PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
    LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
    MEMORY_BANK_ID = os.environ["MEMORY_BANK_ID"]
    # Memory Bank scopes memories to this app name and user ID.
    APP_NAME = "memory_agent"
    USER_ID = "quickstart_user"
    
    async def generate_memories_callback(
        callback_context: CallbackContext,
    ) -> None:
        # Send the latest turn to Memory Bank and wait until memory generation
        # finishes, so that the next session can retrieve the new memory.
        await callback_context.add_events_to_memory(
            events=callback_context.session.events[-5:],
            custom_metadata={"wait_for_completion": True},
        )
        return None
    
    root_agent = adk.Agent(
        model="gemini-3.5-flash",
        name="memory_agent",
        instruction=(
            "You are a vehicle voice agent that controls in-vehicle settings. "
            "Use what you know about the user's preferences. "
            "If you don't know the user's preferred temperature, ask for it. "
            "Limit responses to under 30 words."
        ),
        tools=[PreloadMemoryTool()],
        after_agent_callback=generate_memories_callback,
    )
    
    memory_service = VertexAiMemoryBankService(
        project=PROJECT_ID,
        location=LOCATION,
        agent_engine_id=MEMORY_BANK_ID,
    )
    session_service = InMemorySessionService()
    runner = adk.Runner(
        agent=root_agent,
        app_name=APP_NAME,
        session_service=session_service,
        memory_service=memory_service,
    )
    
    async def send_message(session_id: str, text: str) -> None:
        print(f"User: {text}")
        message = types.Content(role="user", parts=[types.Part(text=text)])
        async for event in runner.run_async(
            user_id=USER_ID, session_id=session_id, new_message=message
        ):
            if event.is_final_response() and event.content:
                print(f"Agent: {event.content.parts[0].text}")
    
    async def main() -> None:
        print("--- Session 1: share a preference ---")
        session = await session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID
        )
        await send_message(session.id, "Can you fix the temperature?")
        await send_message(session.id, "I'm comfortable at 71 degrees.")
    
        print("--- Session 2: recall the preference ---")
        session = await session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID
        )
        await send_message(session.id, "Fix the temperature.")
    
        print("--- Memories stored in Memory Bank ---")
        client = agentplatform.Client(project=PROJECT_ID, location=LOCATION)
        memory_bank_name = (
            f"projects/{PROJECT_ID}/locations/{LOCATION}"
            f"/reasoningEngines/{MEMORY_BANK_ID}"
        )
        results = client.memory_banks.memories.retrieve(
            name=memory_bank_name,
            scope={"app_name": APP_NAME, "user_id": USER_ID},
        )
        for retrieved_memory in results.page:
            print(f"* {retrieved_memory.memory.fact}")
    
    if __name__ == "__main__":
        asyncio.run(main())
    
  3. Jalankan skrip:

    python memory_agent/agent.py

    Callback menunggu pembuatan memori selesai setelah setiap giliran, sehingga memori tersedia saat sesi kedua dimulai.

Memastikan agen mengingat

Setelah selesai, skrip akan mencetak kedua percakapan dan memori yang disimpan ke terminal Anda. Bandingkan output tersebut dengan contoh berikut untuk mengonfirmasi bahwa agen mengingat preferensi dalam sesi baru.

Pada sesi pertama, agen tidak memiliki memori apa pun untuk pengguna, sehingga agen meminta suhu:

--- Session 1: share a preference ---
User: Can you fix the temperature?
Agent: Sure. What temperature would you like?
User: I'm comfortable at 71 degrees.
Agent: Okay, I've set the temperature to 71 degrees.

Pada sesi kedua, agen mengambil memori dari Memory Bank dan menyetel suhu ke 71 derajat tanpa bertanya. Memori yang disimpan akan muncul di akhir output:

--- Session 2: recall the preference ---
User: Fix the temperature.
Agent: Okay, I've set the temperature to 71 degrees, as you prefer.
--- Memories stored in Memory Bank ---
* I like the temperature to be 71 degrees.

Kata-kata dalam respons dan memori agen bervariasi bergantung pada model yang digunakan agen dan Memory Bank.

Opsional: Melakukan chat dengan agen Anda di ADK Web

ADK Web adalah antarmuka berbasis browser untuk menguji agen selama pengembangan.

  1. Dalam sesi terminal yang sama, dari direktori yang berisi direktori memory_agent, jalankan perintah berikut:

    adk web --memory_service_uri=agentengine://$MEMORY_BANK_ID memory_agent
  2. Di browser, buka http://localhost:8000?userId=quickstart_user.

    Parameter kueri userId cocok dengan ID pengguna dalam skrip, sehingga agen dapat mengambil memori yang dibuat skrip.

  3. Kirim pesan Fix the temperature. dan konfirmasi bahwa agen menyetel suhu ke 71 derajat tanpa bertanya. Agen menggunakan preferensi yang disimpan skrip di Menjalankan agen yang mendukung memori.

  4. Untuk menghentikan ADK Web, tekan Control+C di terminal.

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan di halaman ini, Anda dapat menghapus project Google Cloud. Jika tidak, hapus resource satu per satu:

  1. Buat file bernama clean_up.py dengan kode berikut:

    import os
    
    import agentplatform
    
    project = os.environ["GOOGLE_CLOUD_PROJECT"]
    location = os.environ["GOOGLE_CLOUD_LOCATION"]
    memory_bank_id = os.environ["MEMORY_BANK_ID"]
    
    client = agentplatform.Client(project=project, location=location)
    client.memory_banks.delete(
        name=f"projects/{project}/locations/{location}/reasoningEngines/{memory_bank_id}",
        force=True,
    )
    
  2. Jalankan skrip untuk menghapus instance Memory Bank:

    python clean_up.py
  3. Hapus file lokal yang Anda buat:

    rm -r memory_agent create_memory_bank.py clean_up.py

Langkah berikutnya

Panduan memulai

Mulai gunakan Memory Bank API untuk mengelola memori jangka panjang.

Panduan

Memilih callback, alat, dan runtime untuk ADK.

Panduan

Pelajari cara membuat memori di Memory Bank.

Panduan

Pelajari cara menyiapkan Memory Bank.