Panduan memulai Agent Platform Memory Bank API

Agent Platform Memory Bank memungkinkan Anda melakukan panggilan API langsung ke Sesi dan Memory Bank menggunakan Agent Platform SDK. Gunakan Agent Platform SDK jika Anda tidak ingin framework agen mengatur panggilan untuk Anda, atau Anda ingin mengintegrasikan Sesi dan 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.

Sebelum memulai

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam tutorial ini, Anda harus terlebih dahulu mengikuti langkah-langkah di Menyiapkan Memory Bank.

Membuat memori dengan Sesi Agent Platform

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

  1. Buat sesi dengan ID pengguna buram. Memori 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 memori.

    import vertexai

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

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)

    Ganti kode berikut:

    • PROJECT_ID: Project ID Anda.

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

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

    • USER_ID: ID untuk pengguna Anda. Memori 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 memori.

  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 memori 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 memori dari histori percakapan Anda, picu permintaan pembuatan memori untuk sesi:

    client.agent_engines.memories.generate(
name=agent_engine.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 memori yang dibuat, dengan maksimum 5 pasangan nilai kunci 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 memori

Sebagai alternatif untuk membuat memori menggunakan dialog mentah, Anda dapat mengupload memori 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 memori yang dibuat, coba tulis fakta yang telah diekstrak dalam perspektif yang sama dengan yang telah Anda konfigurasi untuk cakupan yang diberikan. Secara default, memori dibuat dalam perspektif orang pertama (misalnya, I am a software engineer).

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

Ganti kode berikut:

  • FACT: Fakta yang telah diekstrak yang harus dikonsolidasikan dengan memori 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 memori yang dibuat. Misalnya, {"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.

memory = client.agent_engines.memories.create(
    name=agent_engine.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 memori

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

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

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

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 memori

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

Menghapus berdasarkan nama resource

Jika Anda tahu persis resource memori mana yang ingin dihapus, Anda dapat menghapus memori 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 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 memori. Hanya memori 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=agent_engine.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 by metadata fields di halaman Mengambil memori.
  • FILTER_GROUPS: Daftar kamus atau objek untuk memfilter metadata memori. Untuk mengetahui informasi selengkapnya tentang cara memfilter kolom metadata, lihat bagian Memfilter berdasarkan sistem kolom di halaman Mengambil memori.

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

print(operation.response.purge_count)

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

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

Menghapus berdasarkan makna semantik

Selama pembuatan memori, Memory Bank 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 dengan memori tersebut atau jika konten yang diekstrak menginstruksikan Memory Bank untuk melupakan subjek (dalam kasus EXPLICIT_INSTRUCTIONS topik memori).

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.agent_engines.memories.generate(
    name=agent_engine.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 memori apa pun yang terkait dengan instance Agent Platform.

    agent_engine.delete(force=True)

  2. Hapus file yang dibuat secara lokal.

Langkah berikutnya

Panduan memulai

Mulai menggunakan Agent Development Kit (ADK).