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
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
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.
- Menginstal ADK dan Agent Platform SDK:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- 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
456diprojects/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 instanceVertexAiMemoryBankServicemandiri yang mendukungglobal, bukanclient.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
456diprojects/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_IDGanti 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.
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 dengan Agent Development Kit
Membangun agen ADK yang mengingat preferensi pengguna.