Menggunakan Memory Bank dengan ADK

Agent Development Kit (ADK) menghubungkan agen ke Bank Memori Platform Agen melalui VertexAiMemoryBankService, yang merupakan implementasi antarmuka BaseMemoryService ADK. Dokumen ini menjelaskan cara memilih alat pengambilan dan callback memori, serta cara menghubungkan layanan memori di setiap runtime ADK.

Untuk menjalankan contoh lengkap terlebih dahulu, lihat Panduan memulai 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. 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.

  11. Menginstal ADK dan Agent Platform SDK:
    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  12. Buat instance Memory Bank di konsol Google Cloud atau dengan Agent Platform SDK. Di halaman Memory Bank, klik Link to an agent > Use with ADK untuk kode penyiapan yang telah diisi sebelumnya. Lewati langkah ini jika Agent Runtime membuat instance untuk 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.

Cara kerja komponen ADK dengan Memory Bank

Agen ADK menggunakan komponen berikut untuk membaca dan menulis memori:

Komponen Peran Wajib
Instance Memory Bank Menyimpan dan mengonsolidasikan memori. Ya
VertexAiMemoryBankService Menghubungkan agen Anda ke Memory Bank sebagai layanan memori ADK. Ya
Layanan sesi Menyimpan histori percakapan. Anda dapat menggunakan layanan sesi ADK apa pun. Ya
Alat pengambilan memori Mengambil memori untuk agen. Lihat Mengambil memori dengan alat. Untuk membaca memori
Callback pembuatan memori Mengirim peristiwa percakapan ke Memory Bank setelah agen merespons. Lihat Membuat kenangan dengan callback. Untuk menulis kenangan
ADK Runner atau AdkApp Mengorkestrasi agen, layanan, alat, dan callback. Ya

Diagram berikut menunjukkan cara komponen ini berinteraksi pada setiap giliran saat agen menggunakan PreloadMemoryTool dan callback memori:

Memory Bank mencakup setiap memori ke ID pengguna dan nama aplikasi yang menjalankan agen Anda, sebagai {"user_id": USER_ID, "app_name": APP_NAME}. Hanya permintaan dengan ID pengguna dan nama aplikasi yang sama yang dapat mengambil memori tersebut.

Membuat kenangan dengan callback

Callback pembuatan memori mengirimkan peristiwa percakapan ke Memory Bank. Memory Bank mengekstrak memori dari peristiwa tersebut dan menggabungkannya dengan memori yang ada. Pilih metode berdasarkan seberapa sering Anda memproses peristiwa:

Metode Peristiwa dikirim Kapan digunakan
callback_context.add_events_to_memory Subset peristiwa yang Anda pilih Direkomendasikan. Memproses peristiwa secara bertahap, misalnya setelah setiap giliran.
callback_context.add_session_to_memory Semua acara dalam sesi Panggil sekali di akhir sesi, sehingga peristiwa yang sama tidak diproses lebih dari sekali.

Contoh berikut mengirimkan peristiwa terbaru setelah setiap respons agen:

from google.adk.agents.callback_context import CallbackContext


async def generate_memories_callback(
    callback_context: CallbackContext,
) -> None:
    await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:]
    )
    return None

Untuk mengirim sesi lengkap, panggil await callback_context.add_session_to_memory() dalam callback di akhir sesi.

Secara default, VertexAiMemoryBankService mengirim peristiwa menggunakan penyerapan peristiwa. Untuk menunggu hingga pembuatan memori selesai dalam pengujian atau demo, teruskan custom_metadata={"wait_for_completion": True} ke add_events_to_memory.

Mengambil kenangan dengan alat

Alat pengambilan memori mengontrol kapan agen mengambil memori dan cara memori dimasukkan ke dalam perintah. Pilih salah satu alat berikut:

Alat Saat memori diambil Kapan digunakan
PreloadMemoryTool Di awal setiap giliran. Memori dimasukkan ke dalam konteks permintaan model sebelum giliran pengguna saat ini. Buat konteks dasar tentang pengguna di setiap giliran.
LoadMemoryTool Saat model memutuskan bahwa memori diperlukan untuk menjawab kueri. Biarkan model memutuskan kapan memori relevan.
FunctionTool kustom Saat model memanggil alat Anda, dipandu oleh deskripsi alat. Berikan petunjuk kepada agen tentang kapan harus mengambil memori.

Contoh berikut membuat agen yang menggunakan PreloadMemoryTool dan callback dari bagian sebelumnya:

from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool

agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction="You are a vehicle voice agent. Limit responses to 30 words.",
    tools=[PreloadMemoryTool()],
    after_agent_callback=generate_memories_callback,
)

Agar model dapat memutuskan kapan harus mengambil memori, impor LoadMemoryTool dari google.adk.tools.load_memory_tool dan teruskan LoadMemoryTool() di tools.

Untuk menulis alat pengambilan kustom, panggil tool_context.search_memory dari panggilan alat fungsi:

from typing import Any

from google import adk
from google.adk.tools import FunctionTool, ToolContext


async def search_memories(query: str, tool_context: ToolContext) -> Any:
    """Query this tool when you need information about user preferences."""
    return await tool_context.search_memory(query)


agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction=(
        "You are a vehicle voice agent. Before you change a setting, call "
        "search_memories to look up the user's preferences. Limit responses "
        "to 30 words."
    ),
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback,
)

Menghubungkan layanan memori ke runtime Anda

Cara Anda menghubungkan VertexAiMemoryBankService bergantung pada tempat agen Anda berjalan. Pilih runtime Anda:

Pelari lokal

Saat Anda menjalankan agen dengan adk.Runner, buat layanan memori dan teruskan ke runner:

import asyncio
import os

from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types

os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()

runner = adk.Runner(
    agent=agent,
    app_name="APP_NAME",
    session_service=session_service,
    memory_service=memory_service,
)

async def main() -> None:
    session = await session_service.create_session(
        app_name="APP_NAME",
        user_id="USER_ID",
    )
    message = types.Content(
        role="user", parts=[types.Part(text="Can you fix the temperature?")]
    )
    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(event.content.parts[0].text)

asyncio.run(main())

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda, misalnya my-project.
  • LOCATION: Lokasi Anda, misalnya global. Lihat lokasi yang didukung serta endpoint global dan multi-regional untuk Memory Bank.
  • MEMORY_BANK_ID: ID instance Memory Bank, misalnya 456 di projects/my-project/locations/us-central1/reasoningEngines/456.
  • APP_NAME: Nama aplikasi ADK, misalnya my_agent. Memory Bank menyertakan nama aplikasi dalam cakupan memori, sehingga memori diisolasi di seluruh aplikasi.
  • USER_ID: ID untuk pengguna Anda, misalnya user-123. Memori yang dihasilkan dari sesi ini dicakupkan ke ID ini.

Agent Runtime di Gemini Enterprise Agent Platform

Saat Anda men-deploy agen ADK ke Agent Runtime dengan template ADK (AdkApp), template tersebut akan menggunakan VertexAiMemoryBankService secara default. Anda dapat membuat instance Memory Bank dan men-deploy agen dalam satu langkah:

import asyncio

import agentplatform
from agentplatform.frameworks import AdkApp

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

adk_app = AdkApp(agent=agent)

# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

async def main() -> None:
    session = await runtime_instance.async_create_session(
        user_id="USER_ID"
    )
    async for event in runtime_instance.async_stream_query(
        user_id="USER_ID",
        session_id=session.get("id"),
        message="Can you fix the temperature?",
    ):
        print(event)

asyncio.run(main())

Untuk men-deploy agen ke resource yang ada dan mempertahankan memori yang ada pada resource, panggil client.runtimes.update:

runtime_instance = client.runtimes.update(
    name="RUNTIME_NAME",
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

Saat Anda menjalankan AdkApp secara lokal, akan menggunakan InMemoryMemoryService secara default. Untuk menggunakan Memory Bank secara lokal, ganti layanan memori:

from google.adk.memory import VertexAiMemoryBankService

def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="MEMORY_BANK_ID",
    )

adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda, misalnya my-project.
  • LOCATION: Region atau multi-region Agent Runtime Anda, misalnya us-central1. Hanya instance VertexAiMemoryBankService mandiri yang mendukung global, bukan client.runtimes.create. Lihat lokasi yang didukung.
  • STAGING_BUCKET: URI bucket Cloud Storage untuk melakukan staging Runtime Agen Anda, misalnya gs://my-staging-bucket.
  • USER_ID: ID untuk pengguna Anda, misalnya user-123.
  • RUNTIME_NAME: Nama resource Agent Runtime yang ada, dalam format projects/.../locations/.../reasoningEngines/....
  • MEMORY_BANK_ID: ID instance Memory Bank, misalnya 456 di projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Untuk men-deploy agen ke Cloud Run, ikuti dokumentasi ADK dan teruskan instance Memory Bank Anda sebagai layanan memori:

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

Ganti MEMORY_BANK_ID dengan ID instance Memory Bank Anda, misalnya 456. Untuk menguji agen yang di-deploy, lihat dokumentasi deployment Cloud Run ADK.

Google Kubernetes Engine (GKE)

Untuk men-deploy agen ke GKE, ikuti dokumentasi ADK dan teruskan instance Memory Bank Anda sebagai layanan memori:

adk deploy gke \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

Ganti MEMORY_BANK_ID dengan ID instance Memory Bank Anda, misalnya 456. Untuk menguji agen yang di-deploy, lihat bagian Menguji agen dalam dokumentasi deployment GKE ADK.

ADK Web

ADK Web adalah antarmuka browser lokal untuk menguji dan memeriksa agen Anda selama pengembangan.

ADK Web membaca project dan lokasi Anda dari variabel lingkungan. Jalankan perintah berikut di terminal Anda, dari direktori yang berisi folder agen:

export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

Ganti kode berikut:

Kemudian, buka http://localhost:8000 di browser Anda. Secara default, ADK Web menetapkan ID pengguna ke user. Untuk menggunakan ID pengguna yang berbeda, tambahkan parameter kueri userId, misalnya http://localhost:8000?userId=USER_ID.

Menggunakan Memory Bank multi-regional dengan runtime regional

Secara default, saat Anda menggunakan Runtime dengan Memory Bank bawaan, agen dan Memory Bank Anda di-deploy di region yang sama. Untuk mempertahankan satu Bank Memori pusat di seluruh deployment regional, Anda dapat menyambungkan Bank Memori multi-regional (seperti us) dengan runtime regional (seperti us-central1).

Untuk menggunakan Memory Bank multi-regional, ganti builder layanan memori ADK default agar mengarah ke lokasi dan ID instance multi-region:

import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService

# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
    project="PROJECT_ID",
    location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]


# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id,
    )


adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
    project="PROJECT_ID",
    location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda, misalnya my-project.
  • STAGING_BUCKET: URI bucket Cloud Storage untuk melakukan staging Runtime Agen Anda, misalnya gs://my-staging-bucket.

Untuk menghapus resource ini, hapus runtime dan instance multi-regional. Jika Anda menghapus instance tepat setelah percakapan, permintaan dapat gagal dengan error FAILED_PRECONDITION saat pembuatan memori selesai. Jika hal itu terjadi, tunggu sebentar dan jalankan penghapusan lagi.

client_runtime.runtimes.delete(
    name=runtime_instance.api_resource.name,
    force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)

Langkah berikutnya

Panduan memulai

Membangun agen ADK yang mengingat preferensi pengguna.

Panduan

Pelajari cara membuat memori di Memory Bank.

Panduan

Pelajari cara menyiapkan Memory Bank.