Membuat kenangan

Memory Bank memungkinkan Anda membuat memori jangka panjang dari percakapan antara pengguna dan agen Anda. Halaman ini menjelaskan cara kerja pembuatan kenangan, cara menyesuaikan ekstraksi kenangan, dan cara memicu pembuatan kenangan.

Memahami pembuatan memori

Memory Bank mengekstrak kenangan dari data sumber dan mengelola sendiri kenangan untuk kumpulan kenangan tertentu (ditentukan oleh scope) dengan menambahkan, memperbarui, dan menghapus kenangan seiring waktu.

Saat Anda memicu pembuatan memori, Bank Memori akan melakukan operasi berikut:

• Ekstraksi: Mengekstrak informasi tentang pengguna dari percakapan mereka dengan agen. Hanya informasi yang cocok dengan setidaknya salah satu topik memori instance Anda yang akan dipertahankan.

• Konsolidasi: Mengidentifikasi apakah kenangan yang ada dengan cakupan yang sama harus dihapus atau diperbarui berdasarkan informasi yang diekstrak. Bank Memori memeriksa bahwa kenangan baru tidak duplikat atau bertentangan sebelum menggabungkannya dengan kenangan yang ada. Jika kenangan yang ada tidak tumpang-tindih dengan informasi baru, kenangan baru akan dibuat.

Kenangan hanya dapat diekstrak dari teks, file inline, dan data file dalam konten sumber. Semua konten lainnya, termasuk panggilan dan respons fungsi, akan diabaikan saat membuat kenangan.

Kenangan dapat diekstrak dari gambar, video, dan audio yang disediakan oleh pengguna. Jika konteks yang diberikan oleh input multimodal dinilai oleh Bank Memori bermakna untuk interaksi di masa mendatang, maka memori tekstual dapat dibuat termasuk informasi yang diekstrak dari input. Misalnya, jika pengguna memberikan gambar golden retriever dengan teks "Ini saya", maka Bank Memori akan membuat memori seperti " saya adalah golden retriever".

Topik kenangan

"Topik memori" mengidentifikasi informasi yang dianggap penting oleh Bank Memori dan oleh karena itu harus dipertahankan sebagai kenangan yang dihasilkan. Bank Memori mendukung dua jenis topik memori:

• Topik terkelola: Label dan petunjuk ditentukan oleh Memory Bank. Anda hanya perlu memberikan nama topik terkelola. Contoh:

  Kamus

  memory_topic = {
      "managed_memory_topic": {
          "managed_topic_enum": "USER_PERSONAL_INFO"
      }
  }
  

  Berbasis kelas

  from vertexai.types import ManagedTopicEnum
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
  
  memory_topic = MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
      )
  )
  

• Topik kustom: Label dan petunjuk ditentukan oleh Anda saat menyiapkan instance Bank Memori. Informasi ini akan digunakan dalam perintah untuk langkah ekstraksi Bank Memori. Contoh:

  Kamus

  memory_topic = {
      "custom_memory_topic": {
          "label": "business_feedback",
          "description": """Specific user feedback about their experience at
  the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
  staff friendliness, service speed, cleanliness, and any suggestions for
  improvement."""
      }
  }
  

  Berbasis kelas

  from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
  
  memory_topic = MemoryTopic(
      custom_memory_topic=CustomMemoryTopic(
          label="business_feedback",
          description="""Specific user feedback about their experience at
  the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
  staff friendliness, service speed, cleanliness, and any suggestions for
  improvement."""
      )
  )
  

  Saat menggunakan topik kustom, sebaiknya berikan juga contoh sedikit tembakan (few-shot) untuk menunjukkan cara mengekstrak kenangan dari percakapan Anda.

Secara default, Bank Memori mempertahankan semua topik terkelola berikut:

• Informasi pribadi (USER_PERSONAL_INFO): Informasi pribadi yang signifikan tentang pengguna, seperti nama, hubungan, hobi, dan tanggal penting. Misalnya, "Saya bekerja di Google" atau "Ulang tahun pernikahan saya pada 31 Desember".
• Preferensi pengguna (USER_PREFERENCES): Suka, tidak suka, gaya, atau pola yang dinyatakan atau tersirat. Misalnya, "Saya lebih suka tempat duduk di tengah".
• Peristiwa percakapan utama dan hasil tugas (KEY_CONVERSATION_DETAILS): Pencapaian atau kesimpulan penting dalam dialog. Misalnya, "Saya memesan tiket pesawat untuk perjalanan pulang pergi antara JFK dan SFO. Saya berangkat pada 1 Juni 2025 dan kembali pada 7 Juni 2025."
• Petunjuk mengingat / melupakan secara eksplisit (EXPLICIT_INSTRUCTIONS): Informasi yang secara eksplisit diminta pengguna kepada agen untuk diingat atau dilupakan. Misalnya, jika pengguna mengatakan "Ingat bahwa saya terutama menggunakan Python", Bank Memori akan membuat memori seperti "Saya terutama menggunakan Python".

Hal ini setara dengan menggunakan serangkaian topik memori terkelola berikut:

  memory_topics = [
      {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
      {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
      {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
      {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
  ]

from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topics = [
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]

Jika Anda ingin menyesuaikan topik yang dipertahankan oleh Bank Memori, tetapkan topik memori dalam konfigurasi penyesuaian saat menyiapkan Bank Memori.

Membuat Kenangan

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

Anda dapat memicu pembuatan memori menggunakan GenerateMemories di akhir sesi atau secara berkala dalam sesi. Pembuatan memori mengekstrak konteks utama dari percakapan sumber dan menggabungkannya dengan memori yang ada untuk cakupan yang sama. Misalnya, Anda dapat membuat kenangan tingkat sesi dengan menggunakan cakupan seperti {"user_id": "123", "session_id": "456"}. Kenangan dengan cakupan yang sama dapat digabungkan dan diambil bersama.

Saat memanggil GenerateMemories, Anda harus memberikan percakapan sumber melalui Sesi Agent Engine atau langsung melalui format JSON:

client.agent_engines.generate_memories(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]

client.agent_engines.generate_memories(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

GenerateMemories adalah operasi yang berjalan lama. Setelah operasi selesai, AgentEngineGenerateMemoriesOperation akan berisi daftar kenangan yang dibuat, jika ada:

AgentEngineGenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

Setiap memori yang dihasilkan mencakup action yang dilakukan pada memori tersebut:

• CREATED: Menunjukkan bahwa kenangan baru telah ditambahkan, yang merepresentasikan konsep baru yang tidak tercakup oleh kenangan yang ada.
• UPDATED: Menunjukkan bahwa memori yang ada telah diperbarui, yang terjadi jika memori mencakup konsep yang serupa dengan informasi yang baru diekstrak. Fakta memori dapat diperbarui dengan informasi baru atau tetap sama.
• DELETED: Menunjukkan bahwa memori yang ada telah dihapus, karena informasinya bertentangan dengan informasi baru yang diekstrak dari percakapan.

Untuk kenangan CREATED atau UPDATED, Anda dapat menggunakan GetMemories untuk mengambil konten lengkap kenangan. Pengambilan memori DELETED akan menghasilkan error 404.

Membuat kenangan di latar belakang

GenerateMemories adalah operasi yang berjalan lama. Secara default, client.agent_engines.generate_memories adalah fungsi pemblokiran dan akan terus melakukan polling operasi hingga selesai. Mengeksekusi pembuatan kenangan sebagai operasi pemblokiran berguna saat Anda ingin memeriksa kenangan yang dibuat secara manual atau saat Anda ingin memberi tahu pengguna akhir tentang kenangan yang dibuat.

Namun, untuk agen produksi, Anda umumnya ingin menjalankan pembuatan memori di latar belakang sebagai proses asinkron. Dalam sebagian besar kasus, klien tidak perlu menggunakan output untuk proses saat ini, sehingga tidak perlu menimbulkan latensi tambahan saat menunggu respons. Jika Anda ingin pembuatan memori dijalankan di latar belakang, tetapkan wait_for_completion ke False:

client.agent_engines.generate_memories(
    ...,
    config={
        "wait_for_completion": False
    }
)

Menggabungkan kenangan yang telah diekstrak sebelumnya

Sebagai alternatif untuk menggunakan proses ekstraksi otomatis Bank Memori, Anda dapat langsung memberikan kenangan yang telah diekstrak sebelumnya. Kenangan sumber langsung akan digabungkan dengan kenangan yang ada untuk cakupan yang sama. Hal ini dapat berguna saat Anda ingin agen atau manusia dalam loop bertanggung jawab untuk mengekstrak memori, tetapi Anda tetap ingin memanfaatkan konsolidasi Bank Memori untuk memastikan tidak ada memori duplikat atau yang bertentangan.

client.agent_engines.generate_memories(
    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 mewakili cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Langkah berikutnya

• Mengambil kenangan yang dibuat
• Menyesuaikan perilaku ekstraksi memori