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 Bank Memori 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.

Sebelum memulai

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

Menghasilkan kenangan dengan Sesi Platform Agen

Setelah menyiapkan Sesi Platform Agen dan Bank Memori, 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 kenangan dan Mengambil kenangan.

Buat sesi dengan ID pengguna yang tidak transparan. Semua kenangan 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"
)

# 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. Semua kenangan yang dibuat dari sesi ini otomatis diberi kunci berdasarkan cakupan {"user_id": "USER_ID"}, kecuali jika Anda secara eksplisit memberikan cakupan saat membuat kenangan.

Upload acara secara berulang ke sesi Anda. Peristiwa dapat mencakup interaksi apa pun antara pengguna, agen, dan alat Anda. Daftar acara yang diurutkan mewakili histori percakapan sesi Anda. Histori percakapan ini digunakan sebagai materi sumber untuk membuat kenangan bagi pengguna tersebut.

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"}]
  }
}
)

Untuk membuat kenangan dari histori percakapan Anda, picu permintaan pembuatan kenangan 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 merepresentasikan cakupan memori yang dihasilkan, dengan maksimum 5 key-value pair dan tanpa karakter *. Misalnya, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan. 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 sebelumnya. 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 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.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 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 merepresentasikan cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Atau, Anda dapat menggunakan CreateMemory untuk mengupload kenangan tanpa menggunakan Bank Memori untuk ekstraksi atau penggabungan kenangan.

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 kenangan

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

Untuk mengetahui informasi selengkapnya tentang 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=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

Anda dapat menggunakan jinja untuk mengonversi kenangan terstruktur Anda 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 Bank Memori Anda, bergantung pada cara Anda ingin memilih kenangan yang harus dihapus.

Menghapus berdasarkan nama resource

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

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

Menghapus menurut 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 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 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 Ambil kenangan.
FILTER_GROUPS: Daftar kamus atau objek untuk memfilter terhadap metadata memori. Untuk mengetahui informasi selengkapnya tentang pemfilteran terhadap kolom metadata, lihat bagian Memfilter menurut kolom sistem di halaman Ambil 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=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

Menghapus berdasarkan makna semantik

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

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

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 Anda gunakan untuk panduan memulai.

Atau, Anda dapat menghapus setiap resource yang dibuat dalam tutorial ini, seperti berikut:

Gunakan contoh kode berikut untuk menghapus instance Agent Platform, yang juga menghapus sesi atau memori yang terkait dengan instance Agent Platform.
```
agent_engine.delete(force=True)
```
Hapus semua file yang dibuat secara lokal.

Langkah berikutnya

Panduan memulai

Mulai Cepat dengan Agent Development Kit

Mulai menggunakan Agent Development Kit (ADK).

Panduan memulai Agent Platform Memory Bank API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Menghasilkan kenangan dengan Sesi Platform Agen

Mengupload kenangan

Mengambil dan menggunakan kenangan

Menghapus kenangan

Menghapus berdasarkan nama resource

Menghapus menurut kriteria

Menghapus berdasarkan makna semantik

Pembersihan

Langkah berikutnya

Mulai Cepat dengan Agent Development Kit

Panduan memulai Agent Platform Memory Bank API