Mengambil kenangan

Agent Platform Memory Bank memungkinkan Anda mengambil memori yang disimpan menggunakan berbagai operasi, bergantung pada kebutuhan Anda. Anda dapat mengambil satu memori, membuat daftar dan memfilter memori, atau melakukan pengambilan berbasis cakupan dengan penelusuran kemiripan.

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:

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):

  1. Buka instance Anda di konsol Google Cloud :

    • Instance Memory Bank mandiri: Buka halaman Memory Bank Agent Platform dan klik instance Anda.

      Buka Memory Bank

    • Agen yang di-deploy di Agent Runtime: Buka halaman Deployments Agent Platform, lalu klik agen Anda.

      Buka Deployment

  2. Buka tab Kenangan. Secara default, tampilan Tidak terstruktur menampilkan tabel memori (Cakupan, Nama Resource, Fakta, Dibuat, dan Diperbarui).

  3. Opsional: Filter atau kelola kenangan:

    • Filter menurut cakupan: Ketik pasangan key:value (seperti user_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.

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_groups untuk pengambilan berbasis cakupan.

  • Kolom sistem yang menggunakan filter. Kolom sistem mencakup topics, create_time, update_time, dan fact memori.

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 AND dan OR.
  • 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}
)