Dokumen ini menjelaskan cara mengambil dan memeriksa memori di konsol Google Cloud atau dengan Agent Platform SDK.
Jika Anda menggunakan Agent Development Kit (ADK), agen Anda dapat otomatis mengorkestrasi panggilan ini untuk Anda. Lihat Panduan memulai dengan ADK.
Sebelum memulai
Untuk menyelesaikan langkah-langkah di halaman ini, Anda harus menyelesaikan langkah-langkah di Menyiapkan Memory Bank terlebih dahulu.
Operasi pengambilan
Anda memiliki opsi berikut untuk mengambil kenangan yang dihasilkan:
Mendapatkan memori: Dapatkan konten lengkap dari satu memori menggunakan Agent Platform SDK.
Mengambil memori: Menggunakan Agent Platform SDK, ambil memori menggunakan pengambilan memori berbasis cakupan. Mengambil memori menggunakan penelusuran kesamaan atau semua memori dalam cakupan.
Mencantumkan memori: Mencantumkan dan memfilter memori di konsolGoogle Cloud atau dengan Agent Platform SDK.
Mendapatkan memori
Gunakan GetMemories untuk mendapatkan konten lengkap dari satu memori:
memory = client.memory_banks.memories.get(
name="MEMORY_NAME")
Ganti kode berikut:
MEMORY_NAME: Nama memori yang sepenuhnya memenuhi syarat dalam format "projects/.../locations/.../reasoningEngines/.../memories...".
Mengambil memori menggunakan pengambilan berbasis cakupan
Anda dapat menggunakan RetrieveMemories untuk mengambil memori untuk cakupan tertentu. Hanya
memori yang memiliki cakupan yang sama persis (terlepas dari urutan) dengan permintaan
pengambilan yang ditampilkan. Misalnya, Anda dapat mengambil semua memori yang dicakupkan
ke pengguna tertentu menggunakan {"user_id": "123"}. Jika tidak ada memori yang ditampilkan,
Memory Bank tidak memiliki memori untuk cakupan yang diberikan.
Cakupan memori ditentukan saat memori dibuat atau dihasilkan dan tidak dapat diubah.
Anda dapat menggunakan RetrieveMemories untuk melakukan operasi berikut untuk cakupan tertentu:
Mengambil memori menggunakan penelusuran kemiripan
Jika Anda memiliki banyak memori untuk cakupan tertentu, Anda dapat menggunakan penelusuran kemiripan untuk mengambil hanya memori yang paling mirip dengan memberikan parameter penelusuran kemiripan. Memory Bank hanya mempertimbangkan memori yang memiliki cakupan yang sama persis dengan permintaan saat melakukan penelusuran kemiripan. Penelusuran kemiripan membandingkan vektor embedding antara fakta memori dan kueri penelusuran permintaan.
Memori yang ditampilkan diurutkan dari yang paling mirip (jarak Euclidean terpendek) hingga yang paling tidak mirip (jarak Euclidean terbesar):
results = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope=SCOPE,
similarity_search_params={
"search_query": "QUERY",
# Optional. Defaults to 3.
"top_k": 3
}
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.
results.page
"""
Returns:
[
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is a fact."
},
distance=0.5
),
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is another fact."
},
distance=0.7
),
]
"""
Ganti kode berikut:
QUERY: Kueri yang akan digunakan untuk melakukan penelusuran kemiripan. Misalnya, Anda dapat menggunakan giliran pengguna terakhir dalam percakapan sebagai kueri.SCOPE: Kamus, yang mewakili cakupan untuk penelusuran kemiripan. Contoh,{"user_id": "123"}. Hanya memori dengan cakupan yang sama dengan permintaan yang dipertimbangkan.
Mengambil semua kenangan
Jika tidak ada parameter penelusuran kesamaan yang diberikan, RetrieveMemories akan menampilkan semua
memori yang memiliki cakupan yang diberikan, terlepas dari kesamaannya dengan
percakapan saat ini.
results = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.
results.page
"""
Returns:
[
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is a fact."
}
),
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is another fact."
}
),
]
"""
Ganti kode berikut:
SCOPE: Kamus yang mewakili cakupan untuk pengambilan. Contoh,{"user_id": "123"}. Hanya memori dengan cakupan yang sama dengan permintaan yang akan ditampilkan.
Mencantumkan memori
Anda dapat mencantumkan dan memeriksa memori di konsol Google Cloud atau dengan Agent Platform SDK.
Konsol
Untuk melihat dan memfilter memori di konsol Google Cloud (memerlukan
aiplatform.memories.list, yang disertakan dalam roles/aiplatform.memoryViewer dan
roles/aiplatform.memoryUser):
Buka instance Anda di konsol Google Cloud :
Instance Memory Bank mandiri: Buka halaman Memory Bank Agent Platform dan klik instance Anda.
Agen yang di-deploy di Agent Runtime: Buka halaman Deployments Agent Platform, lalu klik agen Anda.
Buka tab Kenangan. Secara default, tampilan Tidak terstruktur menampilkan tabel memori (Cakupan, Nama Resource, Fakta, Dibuat, dan Diperbarui).
Opsional: Filter atau kelola kenangan:
- Filter menurut cakupan: Ketik pasangan
key:value(sepertiuser_id:123) di panel filter, atau klik chip cakupan di baris mana pun. - Melihat profil terstruktur: Beralih ke Terstruktur dan pilih cakupan lengkap, atau terapkan filter cakupan di Tidak terstruktur dan klik Telusuri memori terstruktur. Untuk mengetahui detailnya, lihat Profil Memori.
- Mengedit, memeriksa revisi, atau menghapus: Klik menu tindakan lainnya () pada baris memori dan pilih Edit, Lihat revisi, atau Hapus.
- Filter menurut cakupan: Ketik pasangan
Agent Platform SDK
Gunakan ListMemories untuk mencantumkan memori dari Bank Memori Anda tanpa pemfilteran berbasis cakupan. Untuk pengambilan berbasis cakupan, gunakan
RetrieveMemories. ListMemories tidak direkomendasikan
untuk pengambilan latensi rendah.
pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
print(page)
Memfilter kenangan
Bagian ini menjelaskan cara menggunakan filter untuk membatasi memori yang diambil. Anda dapat memfilter:
Metadata yang menggunakan atribut
filter_groupsuntuk pengambilan berbasis cakupan.Kolom sistem yang menggunakan
filter. Kolom sistem mencakuptopics,create_time,update_time, danfactmemori.
Pemfilteran kolom sistem dan metadata dapat digunakan dalam permintaan yang sama.
Memfilter menurut metadata
Saat membuat, memperbarui, atau membuat memori, Anda dapat menerapkan metadata terstruktur ke memori yang disimpan:
import datetime
from agentplatform import types
metadata = {
"my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
"my_double_key": types.MemoryMetadataValue(double_value=123.456),
"my_boolean_key": types.MemoryMetadataValue(bool_value=True),
"my_timestamp_key": types.MemoryMetadataValue(
timestamp_value=datetime.datetime(
2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
)
),
}
client.memory_banks.memories.create(
...,
config={"metadata": metadata}
)
client.memory_banks.memories.update(
...,
config={"metadata": metadata}
)
client.memory_banks.memories.generate(
...,
config={"metadata": metadata}
)
Anda dapat memfilter metadata ini saat mengambil memori menggunakan atribut filter_groups. Filter metadata ditentukan dalam bentuk normal disjungtif (DNF), yang merupakan ekspresi logis OR dari AND.
Misalnya, permintaan berikut akan mengambil memori yang menyertakan
metadata ({"my_string_key": {"string_value": "my_value"}} DAN
{"my_double_key": {"double": 1.23}}) ATAU {"my_string_key": {"string_value":
"other"}}.
Kamus
results = client.memory_banks.memories.retrieve(
...,
config={
# Each element of `filter_groups` is combined using OR logic.
"filter_groups": [
{
# Each element of `filters` is combined using AND logic.
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "my_value"}
},
{
"key": "my_double_key",
"value": {"double_value": 1.23}
}
]
},
{
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "other"}
}
]
}
]
}
)
Berbasis kelas
from agentplatform import types
results = client.memory_banks.memories.retrieve(
...,
config=types.RetrieveMemoriesConfig(
# Each element of `filter_groups` is combined using OR logic.
filter_groups=[
types.MemoryConjunctionFilter(
# Each element of `filters` is combined using AND logic.
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="my_value")
),
types.MemoryFilter(
key="my_double_key",
value=types.MemoryMetadataValue(double_value=1.23)
)
]
),
types.MemoryConjunctionFilter(
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="other")
)
]
)
]
)
)
Memfilter menurut kolom sistem
Anda dapat memfilter kolom sistem menggunakan atribut filter, yang mengharapkan nilai string menggunakan sintaksis EBNF. Kolom sistem mencakup create_time, update_time, fact, dan
topics.
Sintaksis EBNF memiliki persyaratan berikut saat membuat string filter:
- Untuk menggabungkan filter, gunakan
ANDdanOR. - String harus menggunakan tanda kutip ganda
". - Kolom tanggal dan waktu (seperti
create_time) menggunakan string yang diapit tanda petik ganda yang mewakili tanggal dan waktu ISO 8601 atau kolom numerik yang mewakili mikrodetik dari epoch unix.
Misalnya, filter berikut dapat digunakan untuk mengambil memori yang fact-nya
menyertakan substring "alergi" dan update_time-nya setelah 1 Januari 2026.
filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'
client.memory_banks.memories.retrieve(
...,
config={"filter": filter_string}
)
client.memory_banks.memories.list(
...,
config={"filter": filter_string}
)
Filter menurut topik
Memori yang dihasilkan akan otomatis diberi label dengan topik memori yang relevan.
Untuk memfilter topik terkelola, gunakan topics.managed_memory_topic sebagai nama kolom
dan ManagedTopicEnum yang diharapkan sebagai nilai, seperti
topics.managed_memory_topic: USER_PREFERENCES.
Untuk memfilter topik kustom, gunakan topics.custom_memory_topic_label sebagai nama kolom dan label topik yang diharapkan sebagai nilai, seperti topics.custom_memory_topic_label: custom-label.
filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"
client.memory_banks.memories.retrieve(
...,
config={"filter": filter_string}
)
client.memory_banks.memories.list(
...,
config={"filter": filter_string}
)