Panduan memulai Memory Bank dengan ADK

Agent Platform Memory Bank memungkinkan agen Anda mengelola memori jangka panjang di seluruh sesi. Jika digunakan dengan Agent Development Kit (ADK), agen Anda dapat secara otomatis mengatur panggilan ke Memory Bank untuk menyimpan dan mengambil memori berdasarkan interaksi pengguna.

Dokumen ini menjelaskan cara membuat agen ADK, mengonfigurasinya untuk menggunakan Memory Bank, dan berinteraksi dengannya untuk membuat dan mengakses memori.

Untuk mengetahui informasi tentang cara melakukan panggilan langsung ke API tanpa ADK, lihat Panduan memulai Memory Bank API.

Penting: ADK terutama menggunakan fungsi asinkron. Jika menjalankan kode di notebook seperti Colaboratory, Anda dapat langsung memanggil fungsi asinkron await karena loop peristiwa sudah berjalan. Jika menjalankan kode ini sebagai skrip Python standar, Anda harus membungkus panggilan fungsi asinkron dengan asyncio.run() untuk membuat dan mengelola loop peristiwa guna menjalankan fungsi asinkron. Jika tidak, Anda mungkin akan mendapatkan error seperti 'await' outside function.

Untuk melihat contoh penggunaan Memory Bank dengan ADK, jalankan notebook "Mulai menggunakan Memory Bank di ADK" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Agent Platform Workbench | Lihat di GitHub

Mengelola memori dengan layanan memori ADK dan Memory Bank

VertexAiMemoryBankService adalah wrapper ADK di sekitar Memory Bank yang ditentukan oleh BaseMemoryService ADK. Anda dapat menentukan callback dan alat yang berinteraksi dengan layanan memori untuk membaca dan menulis memori.

Antarmuka VertexAiMemoryBankService mencakup:

• memory_service.add_session_to_memory memicu permintaan GenerateMemories ke Memory Bank menggunakan semua peristiwa dalam adk.Session yang diberikan sebagai konten sumber. Anda dapat mengatur panggilan ke metode ini menggunakan callback_context.add_session_to_memory di callback Anda.

  from google.adk.agents.callback_context import CallbackContext
  
  async def add_session_to_memory_callback(callback_context: CallbackContext):
      await callback_context.add_session_to_memory()
      return None
  

• memory_service.add_events_to_memory yang memicu permintaan GenerateMemories ke Memory Bank menggunakan subset peristiwa. Anda dapat mengatur panggilan ke metode ini menggunakan callback_context.add_events_to_memory dalam callback Anda.

  from google.adk.agents.callback_context import CallbackContext
  
  async def add_events_to_memory_callback(callback_context: CallbackContext):
      await callback_context.add_events_to_memory(events=callback_context.session.events[-5:-1])
      return None
  

• memory_service.search_memory memicu permintaan RetrieveMemories ke Memory Bank untuk mengambil memori yang relevan untuk user_id dan app_name saat ini. Anda dapat mengatur panggilan ke metode ini menggunakan alat memori bawaan (LoadMemoryTool atau PreloadMemoryTool) atau alat kustom yang memanggil tool_context.search_memory.

Sebelum memulai

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam tutorial ini, Anda harus mengikuti langkah-langkah di bagian memulai di halaman Menyiapkan Bank Memori terlebih dahulu.

Menetapkan variabel lingkungan

Untuk menggunakan ADK, tetapkan variabel lingkungan Anda:

import os

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

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat region yang didukung untuk Memory Bank.

Membuat agen ADK Anda

Untuk membuat agen yang mendukung memori, siapkan alat dan callback yang mengatur panggilan ke layanan memori Anda.

Menentukan callback pembuatan memori

Untuk mengatur panggilan pembuatan memori, buat fungsi callback yang memicu pembuatan memori. Anda dapat mengirim subset peristiwa (dengan callback_context.add_events_to_memory) atau semua peristiwa dalam sesi (dengan callback_context.add_session_to_memory) untuk diproses di latar belakang:

from google.adk.agents.callback_context import CallbackContext

async def generate_memories_callback(callback_context: CallbackContext):
    # Option 1 (Recommended): Send events to Memory Bank for memory generation,
    # which is ideal for incremental processing of events.
    await callback_context.add_events_to_memory(
      events=callback_context.session.events[-5:-1])

    # Option 2: Send the full session to Memory Bank for memory generation.
    # It's recommended to only call this at the end of a session to minimize
    # how many times a single event is re-processed.
    await callback_context.add_session_to_memory()

    return None

Menentukan alat pengambilan memori

Saat mengembangkan agen ADK, sertakan alat memori yang mengontrol kapan agen mengambil memori dan cara memori disertakan dalam perintah.

Jika Anda menggunakan PreloadMemoryTool, agen Anda akan mengambil memori di awal setiap giliran dan menyertakan memori yang diambil dalam petunjuk sistem, yang baik untuk menetapkan konteks dasar tentang pengguna. Jika Anda menggunakan LoadMemoryTool, model akan memanggil alat ini saat memutuskan bahwa memori diperlukan untuk menjawab kueri pengguna.

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

memory_retrieval_tools = [
  # Option 1: Retrieve memories at the start of every turn.
  PreloadMemoryTool(),
  # Option 2: Retrieve memories via tool calls. The model will only call this tool
  # when it decides that memories are necessary to respond to the user query.
  LoadMemoryTool()
]

agent = adk.Agent(
    model="gemini-3.5-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=memory_retrieval_tools,
    after_agent_callback=generate_memories_callback
)

Atau, Anda dapat membuat alat kustom sendiri untuk mengambil kenangan, yang berguna saat Anda ingin memberikan petunjuk kepada agen Anda tentang kapan harus mengambil kenangan:

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

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

agent = adk.Agent(
    model="gemini-3.5-flash",
    name='stateful_agent',
    instruction="""...""",
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback
)

Menentukan layanan memori ADK Memory Bank dan instance Memory Bank

Setelah membuat agen yang mendukung memori, Anda harus menautkannya ke layanan memori. Proses mengonfigurasi layanan memori ADK bergantung pada tempat ADK agent Anda berjalan. Runtime mengorkestrasi eksekusi agen, alat, dan callback Anda.

Buat instance Memory Bank

Catatan: Lewati bagian ini jika Anda sudah memiliki instance Memory Bank.

Pertama, Anda perlu membuat instance Memory Bank. Langkah ini bersifat opsional jika Anda menggunakan Agent Runtime untuk men-deploy agen. Untuk mengetahui informasi selengkapnya tentang cara menyesuaikan perilaku Bank Memori, lihat bagian Mengonfigurasi instance Bank Memori di halaman Menyiapkan Bank Memori.

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have a Memory Bank instance already, create a
# Memory Bank instance using the default configuration.
memory_bank = client.agent_engines.create()

# Optionally, print out the resource name. You will need the
# resource name if you want to interact with your Memory Bank instance later on.
print(memory_bank.api_resource.name)

agent_engine_id = memory_bank.api_resource.name.split("/")[-1]

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk Memory Bank.

Membuat runtime ADK

Teruskan ID instance Memory Bank ke skrip runtime atau deployment agar agen Anda menggunakan Memory Bank sebagai layanan memori ADK.

Pelari lokal

adk.Runner umumnya digunakan di lingkungan lokal, seperti Colab. Dalam kasus ini, Anda perlu membuat layanan dan pelaksana memori secara langsung.

import asyncio

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

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

# You can use any ADK session service. This example uses Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="SESSIONS_ID",
)

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

async def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run_async(
    user_id=user_id, session_id=session, new_message=content)

  async for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat wilayah yang didukung untuk Memory Bank.
• APP_NAME: Nama aplikasi ADK. Nama aplikasi akan disertakan dalam kamus scope kenangan yang dihasilkan sehingga kenangan diisolasi di seluruh pengguna dan aplikasi.
• MEMORY_BANK_ID: ID instance Memory Bank. Misalnya, 456 di projects/my-project/locations/us-central1/reasoningEngines/456.
• SESSIONS_ID: ID instance Sesi Agent Platform. Misalnya, 789 di projects/my-project/locations/us-central1/reasoningEngines/789.

Agent Runtime di Gemini Enterprise Agent Platform

Template ADK Agent Runtime (AdkApp) dapat digunakan secara lokal dan untuk men-deploy agen ADK ke Agent Runtime. Saat di-deploy di Agent Platform, template ADK Memory Bank menggunakan VertexAiMemoryBankService sebagai layanan memori default. Jadi, Anda dapat membuat instance Memory Bank dan men-deploy ke runtime dalam satu langkah.

Lihat Mengonfigurasi Bank Memori untuk mengetahui detail selengkapnya tentang cara menyiapkan instance Bank Memori, termasuk cara menyesuaikan perilaku Bank Memori.

Gunakan kode berikut untuk men-deploy agen ADK yang mendukung memori ke Agent Runtime:

import asyncio

import vertexai
from vertexai.agent_engines import AdkApp

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

adk_app = AdkApp(agent=agent)

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

# Alternatively, update an existing resource to deploy your agent to Agent Platform.
# Your agent will have access to the Runtime instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat region yang didukung untuk Memory Bank.
• STAGING_BUCKET: Bucket Cloud Storage yang akan digunakan untuk penyiapan Agent Runtime Anda.

Saat dijalankan secara lokal, template ADK menggunakan InMemoryMemoryService sebagai layanan memori default. Namun, Anda dapat mengganti layanan memori default untuk menggunakan VertexAiMemoryBankService:

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

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Runtime instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat region yang didukung untuk Memory Bank.
• MEMORY_BANK_ID: ID instance Memory Bank yang akan digunakan untuk Memory Bank. Misalnya, 456 di projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Untuk melihat contoh penggunaan Memory Bank dengan Cloud Run, jalankan notebook "Get started with Sessions and Memory Bank for ADK agents in Cloud Run" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Agent Platform Workbench | Lihat di GitHub

Untuk men-deploy agen ke Cloud Run, lihat petunjuk di dokumentasi ADK untuk mempelajari cara menentukan agen yang akan di-deploy ke Cloud Run.

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

Google Kubernetes Engine (GKE)

Untuk melihat contoh penggunaan Memory Bank dengan Google Kubernetes Engine, jalankan notebook "Get started with Sessions and Memory Bank for ADK agents in Google Kubernetes Engine" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Agent Platform Workbench | Lihat di GitHub

Untuk men-deploy agen ke GKE, lihat petunjuk di dokumentasi ADK untuk mempelajari cara menentukan agen yang akan di-deploy ke GKE.

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

ADK Web

Penting: ADK Web tidak dimaksudkan untuk digunakan dalam deployment produksi. Anda harus menggunakan ADK Web hanya untuk tujuan pengembangan dan proses debug.

Antarmuka web ADK memungkinkan Anda menguji agen secara langsung di browser.

export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="LOCATION"

adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region Anda. Lihat region yang didukung untuk Memory Bank.
• MEMORY_BANK_ID: ID instance Memory Bank. Misalnya, 456 di projects/my-project/locations/us-central1/reasoningEngines/456.

Berinteraksi dengan agen Anda

Setelah menentukan agen dan menyiapkan Bank Memori, Anda dapat berinteraksi dengan agen. Jika Anda memberikan callback untuk memicu pembuatan memori saat menginisialisasi agen, pembuatan memori akan dipicu setiap kali agen dipanggil.

Memori akan disimpan menggunakan cakupan {"user_id": USER_ID, "app_name": APP_NAME} yang sesuai dengan ID pengguna dan nama aplikasi yang digunakan untuk menjalankan agen Anda.

Metode berinteraksi dengan agen Anda bergantung pada lingkungan eksekusinya:

Pelari lokal

# Use `asyncio.run(session_service.create(...))` if you're running this
# code as a standard Python script.
session = await session_service.create_session(
    app_name="APP_NAME",
    user_id="USER_ID"
)

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.id,
    "USER_ID"
)

Ganti kode berikut:

• APP_NAME: Nama aplikasi untuk pelari Anda.
• USER_ID: ID untuk pengguna Anda. Kenangan yang dihasilkan dari sesi ini diberi kunci oleh ID buram ini. Cakupan kenangan yang dihasilkan disimpan sebagai {"user_id": "USER_ID"}.

Agent Runtime

Saat menggunakan template ADK, Anda dapat memanggil Agent Runtime untuk berinteraksi dengan memori dan sesi.

# Use `asyncio.run(agent_engine.async_create_session(...))` if you're
# running this code as a standard Python script.
session = await agent_engine.async_create_session(user_id="USER_ID")

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.get("id"),
    "USER_ID"
)

Ganti kode berikut:

• USER_ID: ID untuk pengguna Anda. Kenangan yang dihasilkan dari sesi ini diberi kunci oleh ID buram ini. Cakupan kenangan yang dihasilkan disimpan sebagai {"user_id": "USER_ID"}.

Cloud Run

Lihat bagian Menguji agen Anda di dokumentasi deployment ADK Cloud Run.

GKE

Lihat bagian Menguji agen Anda dalam dokumentasi deployment ADK GKE.

ADK Web

Untuk menggunakan ADK Web, buka server lokal di http://localhost:8000.

Secara default, ADK Web akan menyetel ID pengguna ke user. Untuk mengganti ID pengguna default, sertakan userId dalam parameter kueri, seperti http://localhost:8000?userId=YOUR_USER_ID.

Untuk mengetahui informasi selengkapnya, lihat halaman ADK Web dalam dokumentasi ADK.

Contoh interaksi

Sesi pertama

Jika Anda menggunakan PreloadMemoryTool, agen akan mencoba mengambil memori di awal setiap giliran untuk mengakses preferensi yang sebelumnya dikomunikasikan pengguna kepada agen. Selama interaksi pertama agen dengan pengguna, tidak ada memori yang tersedia untuk diambil. Jadi, agen tidak mengetahui preferensi pengguna, seperti suhu yang diinginkan, seperti yang ditunjukkan dalam contoh berikut:

1. Giliran pertama:

   • Pengguna: "Bisakah Anda menyesuaikan suhu?"

   • (Panggilan Alat): ADK mencoba mengambil memori; tidak ada memori yang tersedia.

   • Model: "Berapa suhu yang Anda inginkan?"

   • (Callback): ADK memicu pembuatan memori. Tidak ada memori yang diekstrak.

2. Giliran kedua:

   • Pengguna: Saya merasa nyaman pada suhu 22 derajat Celcius.

   • (Panggilan Alat): ADK mencoba mengambil memori; tidak ada memori yang tersedia.

   • Model: Oke, saya telah memperbarui suhu menjadi 71 derajat.

   • (Callback): ADK memicu pembuatan memori. Memori "Saya suka suhu 71 derajat" dibuat.

Sesi kedua

Memori yang diekstrak akan tersedia untuk sesi berikutnya dengan nama aplikasi dan ID pengguna yang sama. Jika pengguna memberikan informasi yang serupa atau bertentangan dengan kenangan yang ada, informasi baru akan digabungkan dengan kenangan yang ada.

1. Giliran pertama

   • Pengguna: Atur suhu. Sangat tidak nyaman!

   • (Panggilan Alat): ADK mencoba mengambil memori. Memori "Saya suka suhu 71 derajat" diambil.

   • Model: Oke, saya telah memperbarui suhu menjadi 71 derajat.

   • (Callback): ADK memicu pembuatan memori. Tidak ada kenangan yang diekstrak, karena pengguna tidak membagikan apa pun yang bermakna untuk dipertahankan.

2. Giliran kedua

   • Pengguna: Sebenarnya, saya lebih suka suhu yang lebih hangat di pagi hari.

   • (Panggilan Alat): ADK mencoba mengambil memori. Memori "Saya suka suhu 71 derajat" diambil.

   • Model: Oke, saya sudah menaikkan suhu.

   • (Callback): ADK memicu pembuatan memori. Memori yang ada "Saya suka suhu 71 derajat" diperbarui menjadi "Saya biasanya suka suhu 71 derajat, tetapi saya suka suhu yang lebih hangat di pagi hari".

Catatan: Mungkin ada beberapa perbedaan dalam respons agen dan Bank Memori, bergantung pada model yang digunakan.

Menggunakan Bank Memori multi-regional dengan runtime regional

Saat menggunakan Runtime dengan Memory Bank bawaan, agen dan Memory Bank Anda di-deploy di region yang sama secara default. Namun, Anda dapat memisahkan keduanya untuk menggunakan Bank Memori multi-regional (misalnya, us) dengan runtime regional (misalnya, us-central1). Konfigurasi ini memungkinkan Anda mempertahankan Bank Memori pusat di berbagai deployment regional.

Untuk menggunakan Memory Bank multi-regional, Anda harus mengganti builder layanan memori ADK default agar mengarah ke lokasi multi-region dan ID Memory Bank yang sesuai.

import vertexai
from google.adk.memory import VertexAiMemoryBankService
from vertexai.agent_engines import AdkApp

# Create the Memory Bank instance in a multi-region location (for example, 'us')
client_mb = vertexai.Client(project="PROJECT_ID", location="us")
memory_bank = client_mb.agent_engines.create()
memory_bank_id = memory_bank.api_resource.name.split(\"/\")[-1]


# Point your memory service to the 'us' location, 'us' Memory Bank
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id
    )

# Create the AdkApp with the overridden builder
adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder
)

# Deploy the runtime to a specific region (for example, 'us-central1')
client_runtime = vertexai.Client(project="PROJECT_ID", location="us-central1")
agent_engine = client_runtime.agent_engines.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
    }
)

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• STAGING_BUCKET: Bucket Cloud Storage Anda untuk digunakan dalam menyiapkan Agent Runtime.

Pembersihan

Untuk membersihkan semua resource yang digunakan dalam project ini, Anda dapat menghapus Google Cloud project yang Anda gunakan untuk panduan memulai.

Atau, Anda dapat menghapus setiap resource yang dibuat dalam tutorial ini, sebagai berikut:

1. Gunakan contoh kode berikut untuk menghapus instance Agent Runtime, yang juga menghapus sesi atau memori apa pun yang dimiliki runtime tersebut.

   agent_engine.delete(force=True)
   

2. Hapus semua file yang dibuat secara lokal.

Langkah berikutnya

Panduan memulai

Panduan memulai Memory Bank API

Mulai menggunakan Memory Bank API untuk mengelola memori jangka panjang.