Panduan memulai Agent Platform Memory Bank API

Anda dapat menggunakan Agent Platform SDK untuk melakukan panggilan API langsung ke Memory Bank. Gunakan Agent Platform SDK jika Anda tidak ingin framework agen mengorkestrasi panggilan untuk Anda, atau Anda ingin mengintegrasikan Memory Bank dengan framework agen selain Agent Development Kit (ADK).

Dokumen ini menunjukkan cara membuat, mengupload, mengambil, dan menghapus memori menggunakan panggilan API.

Untuk panduan memulai menggunakan ADK, lihat Panduan memulai Memory Bank dengan ADK.

Untuk melihat contoh penggunaan dengan SDK, jalankan notebook "Get started with Memory Bank" di salah satu lingkungan berikut:

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

Untuk melihat contoh penggunaan dengan LangGraph, jalankan notebook "Get started with - LangGraph" di salah satu lingkungan berikut:

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

Sebelum memulai

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam tutorial ini, Anda harus mengikuti langkah-langkah dalam Menyiapkan Memory Bank terlebih dahulu. Sebelum memulai panduan memulai ini, pastikan Anda telah membuat instance Memory Bank dan instance Sessions, seperti yang ditunjukkan dalam contoh berikut:

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

Membuat memori dengan Sesi Agent Platform

Setelah menyiapkan Sesi Agent Platform, Anda dapat membuat sesi dan menambahkan peristiwa ke sesi tersebut. Kemudian, Anda dapat menggunakan Memory Bank untuk membuat memori dari percakapan pengguna dengan agen, sehingga memori tersebut tersedia untuk interaksi pengguna di masa mendatang. Untuk mengetahui informasi selengkapnya, lihat Membuat kenangan dan Mengambil kenangan.

Catatan: Anda juga dapat memberikan histori percakapan langsung di payload GenerateMemories menggunakan sumber konten langsung.

1. Membuat sesi dengan ID pengguna buram. Setiap memori yang dihasilkan dari sesi ini akan otomatis diberi kunci oleh cakupan {"user_id": "USER_ID"}, kecuali jika Anda secara eksplisit memberikan cakupan saat membuat memori.

   import agentplatform
   
   client = agentplatform.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.sessions.create(
     # The name can be fetched using `sessions.name`.
     name="SESSIONS_NAME",
     user_id="USER_ID"
   )
   

   Ganti kode berikut:

   • PROJECT_ID: Project ID Anda.

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

   • SESSIONS_NAME: Nama instance Sessions yang Anda buat atau instance Sessions yang sudah ada. Nama harus dalam format berikut: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

   • USER_ID: ID untuk pengguna Anda. Setiap memori yang dihasilkan dari sesi ini akan otomatis diberi kunci oleh cakupan {"user_id": "USER_ID"}, kecuali jika Anda secara eksplisit memberikan cakupan saat membuat memori.

2. Upload peristiwa secara berulang ke sesi Anda. Peristiwa dapat mencakup interaksi apa pun antara pengguna, agen, dan alat Anda. Daftar peristiwa yang diurutkan mewakili histori percakapan sesi Anda. Histori percakapan ini digunakan sebagai materi referensi untuk membuat memori bagi pengguna tertentu.

   import datetime
   
   client.sessions.events.append(
     name=session.response.name,
     author="user",  # Required by Sessions.
     invocation_id="1",  # Required by Sessions.
     timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
     config={
       "content": {
         "role": "user",
         "parts": [{"text": "hello"}]
       }
     }
   )
   

3. Untuk membuat memori dari histori percakapan Anda, picu permintaan pembuatan memori untuk sesi tersebut:

   client.memory_banks.memories.generate(
     name=memory_bank.name,
     vertex_session_source={
       # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
       "session": session.response.name
     },
     # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
     scope=SCOPE
   )
   

Ganti kode berikut:

• (Opsional) SCOPE: Kamus yang mewakili cakupan memori yang dihasilkan, dengan maksimum 5 key-value pair dan tanpa karakter *. Misalnya, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi. Jika tidak diberikan, {"user_id": session.user_id} akan digunakan.

Mengupload kenangan

Sebagai alternatif untuk membuat memori menggunakan dialog mentah, Anda dapat mengupload memori atau meminta agen menambahkannya secara langsung menggunakan GenerateMemories dengan fakta yang telah diekstrak sebelumnya. Alih-alih Memory Bank mengekstrak informasi dari konten Anda, Anda memberikan fakta yang harus disimpan tentang pengguna Anda secara langsung.

Untuk memastikan konsistensi dengan memori yang dihasilkan, coba tulis fakta yang telah diekstrak sebelumnya dalam perspektif yang sama dengan yang telah Anda konfigurasi untuk cakupan tertentu. Secara default, kenangan dibuat dalam perspektif orang pertama (misalnya, I am a software engineer).

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Ganti kode berikut:

• FACT: Fakta yang telah diekstrak sebelumnya yang harus digabungkan dengan memori yang ada. Anda dapat memberikan hingga 5 fakta yang telah diekstrak sebelumnya dalam daftar seperti berikut:

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE: Kamus, yang mewakili cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya memori dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi.

Atau, Anda dapat menggunakan CreateMemory untuk mengupload memori tanpa menggunakan Memory Bank untuk ekstraksi atau konsolidasi memori.

Perhatian: Memori yang diupload menggunakan CreateMemory tidak akan digabungkan dengan memori yang ada, sehingga Anda dapat memiliki memori duplikat untuk cakupan yang sama. Memori yang dibuat tersedia untuk penelusuran kemiripan dan dapat digabungkan untuk permintaan mendatang saat membuat memori.

memory = client.memory_banks.memories.create(
    name=memory_bank.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns a MemoryOperation containing the created Memory like:

MemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

Mengambil dan menggunakan memori

Anda dapat mengambil memori untuk pengguna dan menyertakannya dalam petunjuk sistem untuk memberi LLM akses ke konteks yang dipersonalisasi.

Untuk mengetahui informasi selengkapnya tentang cara mengambil memori menggunakan metode berbasis cakupan, lihat Mengambil memori.

# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

Anda dapat menggunakan jinja untuk mengonversi memori terstruktur menjadi perintah:

from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

Menghapus kenangan

Ada beberapa cara untuk menghapus memori dari instance Memory Bank Anda, bergantung pada cara Anda ingin memilih memori yang harus dihapus.

Menghapus menurut nama resource

Jika tahu persis resource memori yang ingin dihapus, Anda dapat menghapus memori tertentu menggunakan nama resource-nya:

client.memory_banks.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

Ganti kode berikut:

• MEMORY_NAME: Nama Memori yang akan dihapus. Nama harus dalam format berikut: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Anda dapat menemukan nama Memori dengan mengambil memori.

Menghapus berdasarkan kriteria

Anda dapat menggunakan penghapusan berbasis kriteria untuk menghapus satu atau beberapa kenangan. Hanya kenangan yang cocok dengan filter yang disediakan yang akan dihapus. Anda harus menentukan setidaknya salah satu dari filter (diterapkan ke kolom sistem) atau filter_groups (diterapkan ke kolom metadata).

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    # Specify at least one of `filter` or `filter_groups`.
    filter="FILTER_STRING",
    filter_groups=FILTER_GROUPS,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

Ganti kode berikut:

• FILTER_STRING: String yang menggunakan sintaksis EBNF untuk memfilter kolom sistem. Kolom sistem mencakup create_time, update_time, fact, dan topics. Untuk mengetahui informasi selengkapnya tentang pemfilteran terhadap kolom sistem, lihat bagian Memfilter menurut kolom metadata di halaman Mengambil memori.
• FILTER_GROUPS: Daftar kamus atau objek untuk memfilter metadata memori. Untuk mengetahui informasi selengkapnya tentang pemfilteran terhadap kolom metadata, lihat bagian Memfilter menurut kolom sistem di halaman Mengambil memori.

Operasi ini akan menampilkan jumlah memori yang dihapus permanen (jika force=True) atau akan dihapus permanen jika operasi dijalankan (jika force=False).

print(operation.response.purge_count)

Misalnya, Anda dapat menghapus permanen semua memori yang termasuk dalam cakupan untuk user_id "123":

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

Menghapus berdasarkan makna semantik

Catatan: Perilaku yang diharapkan dapat bervariasi bergantung pada topik memori dan contoh few-shot yang telah Anda konfigurasi.

Selama pembuatan memori, Bank Memori akan memutuskan apakah akan membuat, memperbarui, atau menghapus memori berdasarkan konten informasi yang baru diekstrak dan memori yang ada. Memori dapat dihapus jika informasi baru bertentangan dengannya atau jika konten yang diekstrak menginstruksikan Bank Memori untuk melupakan suatu subjek (dalam kasus topik memori EXPLICIT_INSTRUCTIONS).

Misalnya, permintaan berikut akan menghapus memori yang ada yang berisi informasi tentang preferensi diet, jika ada untuk scope yang diberikan:

from google import genai

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

Pembersihan

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

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

1. Gunakan contoh kode berikut untuk menghapus instance Agent Platform Memory Bank dan Agent Runtime di Gemini Enterprise Agent Platform:

   client.memory_banks.delete(name=memory_bank.name, force=True)
   client.runtimes.delete(name=sessions.name, force=True)
   

2. Hapus semua file yang dibuat secara lokal.

Langkah berikutnya

Panduan memulai

Panduan memulai dengan Agent Development Kit

Membangun agen ADK yang mengingat preferensi pengguna.