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 mengatur 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 kenangan menggunakan panggilan API.

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

Untuk melihat contoh penggunaan dengan SDK, jalankan notebook "Mulai menggunakan 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 "Mulai menggunakan - 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 terlebih dahulu mengikuti langkah-langkah di Menyiapkan Memory Bank. Sebelum memulai panduan memulai ini, pastikan Anda telah membuat instance Memory Bank dan instance Sesi, seperti yang ditunjukkan dalam contoh berikut:

import vertexai

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

memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()

Membuat kenangan 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 kenangan dari percakapan pengguna dengan agen sehingga kenangan 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. Buat sesi dengan ID pengguna buram. Kenangan apa pun yang dibuat dari sesi ini akan otomatis diberi kunci berdasarkan cakupan {"user_id": "USER_ID"} kecuali jika Anda secara eksplisit memberikan cakupan saat membuat kenangan.

   import vertexai
   
   client = vertexai.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.agent_engines.sessions.create(
     # The name can be fetched using `sessions.api_resource.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 Sesi yang Anda buat atau instance Sesi yang ada. Nama harus dalam format berikut: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

   • USER_ID: ID untuk pengguna Anda. Kenangan apa pun yang dibuat dari sesi ini akan otomatis diberi kunci berdasarkan cakupan {"user_id": "USER_ID"} kecuali jika Anda secara eksplisit memberikan cakupan saat membuat kenangan.

2. Upload peristiwa ke sesi Anda secara berulang. 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 sumber untuk membuat kenangan bagi pengguna tertentu.

   import datetime
   
   client.agent_engines.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 kenangan dari histori percakapan Anda, picu permintaan pembuatan kenangan untuk sesi:

   client.agent_engines.memories.generate(
     name=memory_bank.api_resource.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 kenangan yang dibuat, dengan maksimum 5 pasangan nilai kunci dan tanpa karakter *. Misalnya, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk konsolidasi. Jika tidak diberikan, {"user_id": session.user_id} akan digunakan.

Mengupload kenangan

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

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

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

Ganti kode berikut:

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

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

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

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

Perhatian: Kenangan yang diupload menggunakan CreateMemory tidak akan dikonsolidasikan dengan kenangan yang ada, sehingga Anda dapat memiliki kenangan duplikat untuk cakupan yang sama. Kenangan yang dibuat tersedia untuk penelusuran kesamaan dan dapat dikonsolidasikan untuk permintaan mendatang saat membuat kenangan.

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

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  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 kenangan

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

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

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=memory_bank.api_resource.name,
        scope={"user_id": "123"}
    )
)

Anda dapat menggunakan jinja untuk mengonversi kenangan 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 kenangan dari instance Memory Bank, bergantung pada cara Anda memilih kenangan yang akan dihapus.

Menghapus berdasarkan nama resource

Jika Anda tahu persis resource kenangan mana yang ingin dihapus, Anda dapat menghapus kenangan tertentu menggunakan nama resourcenya:

client.agent_engines.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 Kenangan 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 Kenangan dengan mengambil kenangan.

Menghapus berdasarkan kriteria

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

operation = client.agent_engines.memories.purge(
    name=memory_bank.api_resource.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 EBNF untuk memfilter kolom sistem. Kolom sistem mencakup create_time, update_time, fact, dan topics. Untuk mengetahui informasi selengkapnya tentang cara memfilter kolom sistem, lihat bagian Filter menurut metadata kolom di halaman Mengambil kenangan.
• FILTER_GROUPS: Daftar kamus atau objek untuk memfilter metadata kenangan. Untuk mengetahui informasi selengkapnya tentang cara memfilter kolom metadata, lihat bagian Memfilter menurut sistem kolom di halaman Mengambil kenangan.

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

print(operation.response.purge_count)

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

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

Menghapus berdasarkan makna semantik

Catatan: Perilaku yang diharapkan dapat bervariasi bergantung pada topik kenangan dan contoh beberapa kali yang telah Anda konfigurasi.

Selama pembuatan kenangan, Memory Bank akan memutuskan apakah akan membuat, memperbarui, atau menghapus kenangan berdasarkan konten informasi yang baru diekstrak dan kenangan yang ada. Kenangan dapat dihapus jika informasi baru bertentangan dengan kenangan tersebut atau jika konten yang diekstrak menginstruksikan Memory Bank untuk melupakan subjek (dalam kasus topik kenangan EXPLICIT_INSTRUCTIONS).

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

from google import genai

client.agent_engines.memories.generate(
    name=memory_bank.api_resource.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 Google Cloud project yang digunakan untuk panduan memulai.

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

1. Gunakan contoh kode berikut untuk menghapus instance Agent Platform, yang juga menghapus sesi atau kenangan apa pun yang terkait dengan instance Agent Platform.

   agent_engine.delete(force=True)
   

2. Hapus file yang dibuat secara lokal.

Langkah berikutnya

Panduan memulai

Panduan memulai dengan Agent Development Kit

Mulai menggunakan Agent Development Kit (ADK).