Menyiapkan Memory Bank Platform Agen

Untuk menggunakan Bank Memori Agent Platform, Anda harus membuat dan mengonfigurasi instance Gemini Enterprise Agent Platform terlebih dahulu. Instance ini mengelola kenangan Anda dan dapat diintegrasikan dengan agen Anda di berbagai runtime.

Dokumen ini menjelaskan cara menyiapkan project Google Cloud , menginstal library yang diperlukan, dan membuat atau memperbarui instance dengan konfigurasi kustom seperti topik dan TTL.

Mulai

Sebelum menggunakan Memory Bank, Anda harus menyiapkan lingkungan Anda.

Menyiapkan project Google Cloud

Setiap project dapat diidentifikasi dengan dua cara: nomor project atau project ID. PROJECT_NUMBER dibuat secara otomatis saat Anda membuat project, sedangkan PROJECT_ID dibuat oleh Anda, atau siapa pun yang membuat project. Untuk menyiapkan project:

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Catatan: Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda tidak memiliki izin ini, minta administrator Anda untuk memberi Anda peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin).

Mendapatkan peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan Bank Memori, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

• Semua: Pengguna Platform Agen (roles/aiplatform.user)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Jika Anda membuat permintaan ke Memory Bank dari agen yang di-deploy di Google Kubernetes Engine atau Cloud Run, pastikan akun layanan Anda memiliki izin yang diperlukan. Reasoning Engine Service Agent sudah memiliki izin yang diperlukan untuk membaca dan menulis memori, sehingga permintaan keluar dari Agent Runtime sudah memiliki izin untuk mengakses Memory Bank.

Menginstal library

Bagian ini mengasumsikan bahwa Anda telah menyiapkan lingkungan pengembangan Python, atau menggunakan runtime dengan lingkungan pengembangan Python (seperti Colab).

Instal Agent Platform SDK:

pip install google-cloud-aiplatform>=1.111.0

Autentikasi

Ikuti petunjuk di Melakukan autentikasi ke Vertex AI.

Menyiapkan klien Agent Platform SDK

Jalankan kode berikut untuk menyiapkan klien Agent Platform SDK:

Agent Platform SDK

import vertexai

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

di mana

• PROJECT_ID adalah Google Cloud project ID tempat Anda mengembangkan dan men-deploy agen,
• LOCATION adalah salah satu wilayah yang didukung untuk fitur Memory Bank.

Membuat atau mengupdate instance Agent Platform

Untuk mulai menggunakan Memory Bank, Anda memerlukan instance Agent Platform terlebih dahulu. Jika belum memiliki instance, Anda dapat membuatnya menggunakan konfigurasi default:

agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Platform resource name. You will need the
# resource name to interact with your Agent Platform instance later on.
print(agent_engine.api_resource.name)

Jika Anda ingin menyesuaikan konfigurasi perilaku instance Memory Bank baru atau yang sudah ada, lihat Mengonfigurasi instance Platform Agen untuk Memory Bank. Misalnya, Anda dapat menentukan informasi yang dianggap penting oleh Memory Bank untuk dipertahankan.

Instance Agent Platform Anda mendukung Sesi dan Memory Bank secara langsung. Tidak ada agen yang di-deploy saat Anda membuat instance. Untuk menggunakan Agent Runtime, Anda harus menyediakan agen yang harus di-deploy saat membuat atau mengupdate instance Platform Agen.

Setelah memiliki instance Agent Platform, Anda dapat menggunakan nama instance untuk membaca atau menulis memori. Contoh:

# Generate memories using your Memory Bank instance.
client.agent_engines.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=agent_engine.api_resource.name,
  ...
)

Penggunaan dengan Agent Runtime

Meskipun Bank Memori dapat digunakan di runtime apa pun, Anda juga dapat menggunakan Bank Memori dengan Agent Runtime untuk membaca dan menulis memori dari agen yang di-deploy.

Untuk men-deploy agen dengan Bank Memori di Platform Agen, siapkan lingkungan Anda terlebih dahulu untuk Agent Runtime. Kemudian, siapkan agen untuk di-deploy di Agent Runtime dengan integrasi memori. Agen yang di-deploy harus melakukan panggilan untuk membaca dan menulis memori sesuai kebutuhan.

AdkApp

Jika Anda menggunakan template Agent Development Kit Platform Agen, agen akan menggunakan VertexAiMemoryBankService secara default saat di-deploy ke Platform Agen. Artinya, alat Memori ADK membaca memori dari Memory Bank.

from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

Ganti kode berikut:

• STAGING_BUCKET: Bucket Cloud Storage yang akan digunakan untuk menyiapkan Agent Runtime Anda.

Untuk mengetahui informasi selengkapnya tentang penggunaan Memory Bank dengan ADK, lihat Panduan memulai dengan Agent Development Kit.

Agen kustom

Anda dapat menggunakan Bank Memori dengan agen kustom yang di-deploy di Agent Runtime. Dalam hal ini, agen Anda harus mengoordinasikan panggilan ke Memory Bank untuk memicu pembuatan memori dan panggilan pengambilan memori.

Aplikasi Anda yang di-deploy ke Agent Runtime dapat membaca variabel lingkungan GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID untuk menyimpulkan nama Agent Runtime dari lingkungan:

project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

Jika Anda menggunakan agen layanan default untuk agen Anda di Agent Runtime, agen Anda sudah memiliki izin untuk membaca dan menulis memori. Jika Anda menggunakan akun layanan pelanggan, Anda perlu memberikan izin ke akun layanan Anda untuk membaca dan menulis kenangan. Izin yang diperlukan bergantung pada operasi yang harus dapat dilakukan oleh agen Anda. Jika Anda hanya ingin agen Anda mengambil dan membuat kenangan, aiplatform.memories.generate dan aiplatform.memories.retrieve sudah cukup.

Penggunaan di semua runtime lainnya

Untuk melihat contoh penggunaan Memory Bank dengan Cloud Run, jalankan notebook "Get started with Sessions and Memory Bank for ADK agents in Cloud Run" di salah satu lingkungan berikut:

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

Untuk melihat contoh penggunaan Memory Bank dengan Google Kubernetes Engine, jalankan notebook "Get started with Sessions and Memory Bank for ADK agents in Google Kubernetes Engine" di salah satu lingkungan berikut:

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

Jika Anda ingin menggunakan Memory Bank di lingkungan yang berbeda, seperti Cloud Run atau Colab, buat Agent Runtime tanpa memberikan agen. Jika Anda tidak memberikan konfigurasi, Memory Bank akan dibuat dengan setelan default untuk mengelola pembuatan dan pengambilan memori.

agent_engine = client.agent_engines.create()

Jika Anda pernah menggunakan Platform Agen sebelumnya, pembuatan instance Platform Agen baru tanpa runtime hanya memerlukan waktu beberapa detik. Jika ini pertama kalinya Anda menggunakan Platform Agen, prosesnya mungkin memerlukan waktu lebih lama (1-2 menit).

Jika Anda ingin mengonfigurasi perilaku, berikan konfigurasi Memory Bank:

Buat

agent_engine = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Perbarui

Jika ingin mengubah konfigurasi Bank Memori, Anda dapat memperbarui instance Platform Agen.

agent_engine = client.agent_engines.update(
  # You can access the name using `agent_engine.api_resource.name` for an AgentEngine object.
  name="AGENT_ENGINE_NAME",
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Ganti kode berikut:

• RUNTIME_NAME: Nama Agent Runtime. Harus dalam format projects/.../locations/.../reasoningEngines/.... Lihat region yang didukung untuk Memory Bank.

Anda dapat menggunakan Memory Bank di lingkungan mana pun yang memiliki izin untuk membaca dan menulis kenangan. Misalnya, untuk menggunakan Memory Bank dengan Cloud Run, berikan izin ke identitas layanan Cloud Run untuk membaca dan menulis memori. Izin yang diperlukan bergantung pada operasi yang harus dapat dilakukan oleh agen Anda. Jika Anda hanya ingin agen Anda mengambil dan membuat memori, aiplatform.memories.generate dan aiplatform.memories.retrieve sudah cukup.

Mengonfigurasi instance Agent Platform untuk Memory Bank

Anda dapat mengonfigurasi Bank Memori untuk menyesuaikan cara pembuatan dan pengelolaan kenangan. Jika Anda tidak memberikan konfigurasi, Bank Memori akan menggunakan setelan default untuk setiap jenis konfigurasi.

Anda dapat mengonfigurasi setelan Bank Memori berikut untuk instance Anda:

• Konfigurasi penyesuaian: Mengonfigurasi cara kenangan diekstrak dari data sumber dan digabungkan dengan kenangan yang ada.
• Konfigurasi penelusuran kemiripan: Menentukan model embedding yang digunakan Memory Bank untuk penelusuran kemiripan. Nilai defaultnya adalah text-embedding-005.
• Konfigurasi pembuatan: Mengonfigurasi LLM mana yang digunakan Bank Memori untuk pembuatan memori. Nilai defaultnya adalah gemini-2.5-flash.
• Konfigurasi TTL: Mengonfigurasi cara TTL ditetapkan secara otomatis untuk kenangan yang dibuat atau diperbarui. Defaultnya adalah tanpa TTL.

Contoh berikut menunjukkan Bank Memori default:

Kamus

memory_bank_config = {
  "generation_config": {
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  },
  "similarity_search_config": {
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    "embedding_model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  },
  "ttl_config": {
    # Default TTL for memory revisions is 365 days.
    "memory_revision_default_ttl": f"{365 * 24 * 60 * 60}s"
  },
  "customization_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": "USER_PERSONAL_INFO"},
        {"managed_memory_topic": "USER_PREFERENCES"},
        {"managed_memory_topic": "KEY_CONVERSATION_DETAILS"},
        {"managed_memory_topic": "EXPLICIT_INSTRUCTIONS"}
      ],
      "consolidation_config": {
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        "revisions_per_candidate_count": 1
      },
      # Only use the pre-defined set of examples.
      "generate_memories_examples": [],
      # Generate memories in the first person.
      "enable_third_person_memories": False
    }
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  "disable_memory_revisions": False
}

Berbasis kelas

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  ),
  similarity_search_config=SimilaritySearchConfig(
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    embedding_model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  ),
  ttl_config=TtlConfig(
    # Default TTL for memory revisions is 365 days.
    memory_revision_default_ttl=f"{365 * 24 * 60 * 60}s"
  ),
  customization_configs=[
    CustomizationConfig(
      # Extract personal information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      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))
      ],
      # Only use the pre-defined set of examples.
      generate_memories_examples=[],
      consolidation_config=ConsolidationConfig(
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        revisions_per_candidate_count=1
      ),
      # Generate memories in the first person.
      enable_third_person_memories=False,
    )
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  disable_memory_revisions=False
)

Anda dapat menyesuaikan konfigurasi Bank Memori saat membuat atau memperbarui instance Platform Agen. Contoh berikut menunjukkan cara membuat atau mengupdate instance dengan konfigurasi Bank Memori tertentu.

client.agent_engines.create(
      ...,
      config={
            "context_spec": {
                  "memory_bank_config": memory_bank_config
            }
      }
)

# Alternatively, update an existing Agent Platform instance's Memory Bank config.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      config={
          "context_spec": {
                "memory_bank_config": memory_bank_config
          }
      }
)

Konfigurasi penyesuaian memori bahasa alami

Untuk menyesuaikan cara Memory Bank mengekstrak kenangan bahasa alami, konfigurasi perilaku ekstraksi saat Anda menyiapkan instance. Gunakan opsi berikut untuk menyesuaikan perilaku:

• Mengonfigurasi topik memori: Tentukan jenis informasi yang harus dianggap penting oleh Bank Memori untuk dipertahankan. Hanya informasi yang sesuai dengan salah satu topik memori ini yang akan dipertahankan oleh Bank Memori.
• Memberikan contoh few-shot: Tunjukkan perilaku yang diharapkan untuk ekstraksi memori ke Memory Bank.
• Mengonfigurasi perspektif kenangan: Konfigurasi apakah kenangan harus dibuat dalam sudut pandang orang pertama (default) atau orang ketiga.
• Mengonfigurasi konsolidasi: Konfigurasi jumlah revisi memori yang dipertimbangkan Bank Memori saat mengonsolidasi setiap kandidat memori.

Anda dapat menyesuaikan perilaku ekstraksi Memory Bank dalam dua langkah: Memberi tahu dan Menunjukkan. Topik Memori memberi tahu Memory Bank informasi apa yang harus dipertahankan. Beberapa contoh menunjukkan kepada Bank Memori jenis informasi yang harus menghasilkan memori tertentu, sehingga membantunya mempelajari pola, nuansa, dan susunan kata yang Anda harapkan untuk dipahaminya.

Secara opsional, Anda dapat mengonfigurasi perilaku yang berbeda untuk tingkat cakupan yang berbeda. Misalnya, topik yang bermakna untuk kenangan tingkat sesi mungkin tidak bermakna untuk kenangan tingkat pengguna (di beberapa sesi). Untuk mengonfigurasi perilaku untuk subset kenangan tertentu, tetapkan kunci cakupan konfigurasi penyesuaian. Hanya permintaan GenerateMemories yang menyertakan kunci cakupan tersebut yang akan menggunakan konfigurasi tersebut. Anda juga dapat mengonfigurasi perilaku default (berlaku untuk semua set kunci cakupan) dengan menghilangkan kolom scope_key. Konfigurasi ini akan berlaku untuk semua permintaan yang tidak memiliki konfigurasi yang cocok persis dengan kunci cakupan untuk konfigurasi penyesuaian lainnya.

Misalnya, user_level_config hanya akan berlaku untuk permintaan GenerateMemories yang menggunakan kunci cakupan user_id secara persis (yaitu scope={"user_id": "123"} tanpa kunci tambahan). default_config akan berlaku untuk permintaan lainnya:

Kamus

user_level_config = {
  "scope_keys": ["user_id"],
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

default_config = {
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

memory_bank_config = {
  "customization_configs": [
    user_level_config,
    default_config
  ]
}

Berbasis kelas

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

user_level_config = CustomizationConfig(
  scope_keys=["user_id"],
  memory_topics=[...],
  generate_memories_examples=[...]
)

Mengonfigurasi topik memori

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

• Topik terkelola: Label dan petunjuk ditentukan oleh Bank Memori. Anda hanya perlu memberikan nama topik terkelola. Misalnya,

  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 terkelola berikut didukung oleh Memory Bank:

  • Informasi pengguna (USER_PERSONAL_INFO): Informasi penting 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".
  • Hasil tugas dan peristiwa percakapan utama (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 ingat / lupa 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".

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

  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 yang menunjukkan cara mengekstrak kenangan dari percakapan Anda.

Dengan penyesuaian, Anda dapat menggunakan kombinasi topik memori apa pun. Misalnya, Anda dapat menggunakan subset topik memori terkelola yang tersedia:

Kamus

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

Berbasis kelas

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

customization_config = CustomizationConfig(
  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)
      ),
  ]
)

Anda juga dapat menggunakan kombinasi topik terkelola dan kustom (atau hanya menggunakan topik kustom):

Kamus

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    {
      "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 MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      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."""
          )
    )
  ]
)

Contoh few-shot

Contoh few-shot memungkinkan Anda menunjukkan perilaku ekstraksi memori yang diharapkan ke Memory Bank. Misalnya, Anda dapat memberikan contoh percakapan input dan memori yang diharapkan diekstrak dari percakapan tersebut.

Sebaiknya selalu gunakan contoh sedikit dengan topik kustom agar Bank Memori dapat mempelajari perilaku yang diinginkan. Beberapa contoh bersifat opsional saat menggunakan topik terkelola karena Bank Memori menentukan contoh untuk setiap topik. Menunjukkan percakapan yang tidak diharapkan menghasilkan kenangan dengan memberikan daftar generated_memories kosong.

Misalnya, Anda dapat memberikan contoh sedikit tembakan yang menunjukkan cara mengekstrak masukan tentang bisnis Anda dari pesan pelanggan:

Kamus

example = {
    "conversationSource": {
      "events": [
        {
          "content": {
            "role": "model",
            "parts": [{ "text": "Welcome back to The Daily Grind! We'd love to hear your feedback on your visit." }] }
        },
        {
          "content": {
            "role": "user",
            "parts": [{ "text": "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend." }] }
        }
      ]
    },
    "generatedMemories": [
      {
        "fact": "The user reported that the drip coffee was lukewarm."
      },
      {
        "fact": "The user felt the music in the shop was too loud."
      }
    ]
}

Berbasis kelas

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory as ExampleGeneratedMemory

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend.")]
                )
            )
        ]
    ),
    generated_memories=[
        ExampleGeneratedMemory(
            fact="The user reported that the drip coffee was lukewarm."
        ),
        ExampleGeneratedMemory(
            fact="The user felt the music in the shop was too loud."
        )
    ]
)

Anda juga dapat memberikan contoh percakapan yang tidak boleh menghasilkan kenangan yang dibuat dengan memberikan daftar kosong untuk output yang diharapkan (generated_memories):

Kamus

example = {
    "conversationSource": {
        "events": [
          {
              "content": {
                  "role": "model",
                  "parts": [{ "text": "Good morning! What can I get for you at The Daily Grind?" }] }
          },
          {
              "content": {
                  "role": "user",
                  "parts": [{ "text": "Thanks for the coffee." }] }
          }
        ]
    },
    "generatedMemories": []
}

Berbasis kelas

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Thanks for the coffee!")]
                )
            )
        ]
    ),
    generated_memories=[]
)

Perspektif memori

Secara default, kenangan dibuat dalam sudut pandang orang pertama (misalnya, "Saya menggunakan Bank Memori untuk pengelolaan memori"). Anda dapat mengonfigurasi Memory Bank untuk membuat teks dalam sudut pandang orang ketiga (misalnya, "Pengguna menggunakan Memory Bank untuk pengelolaan memori") menggunakan parameter enable_third_person_memories.

Kamus

customization_config = {
  "enable_third_person_memories": True
}

Berbasis kelas

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Catatan: Jika Anda memberikan contoh few-shot, pastikan perspektifnya konsisten dengan perspektif yang dikonfigurasi untuk instance Anda.

Penyesuaian konsolidasi

Selama konsolidasi, Bank Memori akan menentukan cara mengintegrasikan informasi yang baru diperoleh ke dalam set memori yang ada. Bank Memori mengevaluasi apakah akan MENAMBAHKAN kenangan baru, MEMPERBARUI kenangan yang ada dengan konteks tambahan, atau MENGHAPUS kenangan yang sudah tidak relevan.

Untuk memastikan kualitas tinggi dan kenangan yang terkonfirmasi, Memory Bank dapat secara opsional menganalisis histori kenangan untuk membedakan tren jangka panjang dari pencilan satu kali.

Secara default, Bank Memori hanya membandingkan informasi baru dengan snapshot terbaru dari memori kandidat ("revisi memori"). Untuk meningkatkan kedalaman analisis ini, konfigurasikan parameter revisions_per_candidate_count. Parameter ini menentukan berapa banyak revisi sebelumnya dari setiap "memori kandidat" (catatan spesifik yang dievaluasi untuk update) yang dipertimbangkan Bank Memori selama penggabungan.

Kamus

customization_config = {
  "consolidation_customization": {
    "revisions_per_candidate_count": 10
  }
}

Berbasis kelas

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig

customization_config = CustomizationConfig(
    consolidation_customization=ConsolidationConfig(
      revisions_per_candidate_count=10
    )
)

Meningkatkan revisions_per_candidate_count akan menghasilkan memori yang lebih konsisten dan terkonfirmasi dengan memperhitungkan pengulangan informasi yang diserap. Namun, jumlah yang lebih tinggi akan meningkatkan konsumsi token selama proses penggabungan.

Konfigurasi penelusuran kemiripan

Konfigurasi penelusuran kesamaan mengontrol model embedding yang digunakan oleh instance Anda untuk penelusuran kesamaan. Penelusuran kesamaan digunakan untuk mengidentifikasi memori mana yang harus menjadi kandidat untuk penggabungan dan untuk pengambilan memori berbasis penelusuran kesamaan. Jika konfigurasi ini tidak diberikan, Bank Memori akan menggunakan text-embedding-005 sebagai model default.

Jika Anda memperkirakan percakapan pengguna akan menggunakan bahasa selain bahasa Inggris, gunakan model yang mendukung beberapa bahasa, seperti gemini-embedding-001 atau text-multilingual-embedding-002, untuk meningkatkan kualitas pengambilan.

Kamus

memory_bank_config = {
    "similarity_search_config": {
        "embedding_model": "EMBEDDING_MODEL",
    }
}

Berbasis kelas

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig

memory_bank_config = MemoryBankConfig(
    similarity_search_config=SimilaritySearchConfig(
        embedding_model="EMBEDDING_MODEL"
    )
)

Ganti kode berikut:

• EMBEDDING_MODEL: Model embedding teks Google yang akan digunakan untuk penelusuran kesamaan, dalam format projects/{project}/locations/{location}/publishers/google/models/{model}.

Konfigurasi pembuatan

Konfigurasi pembuatan mengontrol LLM mana yang digunakan untuk membuat kenangan, termasuk mengekstraksi kenangan dan menggabungkan kenangan baru dengan kenangan yang ada.

Memory Bank menggunakan gemini-2.5-flash sebagai model default. Untuk wilayah yang tidak memiliki ketersediaan Gemini regional, endpoint global akan digunakan.

Kamus

memory_bank_config = {
  "generation_config": {
    "model": "LLM_MODEL",
  }
}

Berbasis kelas

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    model="LLM_MODEL"
  )
)

Ganti kode berikut:

• LLM_MODEL: Model LLM Google yang akan digunakan untuk mengekstrak dan menggabungkan memori, dalam format projects/{project}/locations/{location}/publishers/google/models/{model}.

Konfigurasi time to live (TTL)

Konfigurasi TTL mengontrol cara Memory Bank menetapkan waktu habis masa berlaku memori secara dinamis. Setelah waktu habis masa berlakunya, kenangan tidak akan tersedia untuk diambil dan akan dihapus.

Jika konfigurasi tidak diberikan, waktu habis masa berlaku tidak akan ditetapkan secara dinamis untuk kenangan yang dibuat atau diperbarui, sehingga masa berlaku kenangan tidak akan habis kecuali waktu habis masa berlakunya ditetapkan secara manual.

Ada dua opsi untuk konfigurasi TTL:

• TTL Default: TTL akan diterapkan ke semua operasi yang membuat atau memperbarui memori, termasuk UpdateMemory, CreateMemory, dan GenerateMemories.

  Kamus

  memory_bank_config = {
    "ttl_config": {
        "default_ttl": f"TTLs"
    }
  }
  

  Berbasis kelas

  from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
  from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
  
  memory_bank_config = MemoryBankConfig(
    ttl_config=TtlConfig(
        default_ttl=f"TTLs"
    )
  )
  

  Ganti kode berikut:

  • TTL: Durasi dalam detik untuk TTL. Untuk kenangan yang diperbarui, waktu habis masa berlaku yang baru dihitung (sekarang + TTL) akan menggantikan waktu habis masa berlaku Kenangan sebelumnya.

• TTL terperinci (per operasi): TTL dihitung berdasarkan operasi yang membuat atau memperbarui Memori. Jika tidak ditetapkan untuk operasi tertentu, maka operasi tidak akan memperbarui waktu habis masa berlaku Memori.

  Kamus

  memory_bank_config = {
    "ttl_config": {
        "granular_ttl": {
            "create_ttl": f"CREATE_TTLs",
            "generate_created_ttl": f"GENERATE_CREATED_TTLs",
            "generate_updated_ttl": f"GENERATE_UPDATED_TTLs"
        }
    }
  }
  

  Berbasis kelas

  from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
  from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
  from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfigGranularTtlConfig as GranularTtlConfig
  
  memory_bank_config = MemoryBankConfig(
    ttl_config=TtlConfig(
        granular_ttl_config=GranularTtlConfig(
            create_ttl=f"CREATE_TTLs",
            generate_created_ttl=f"GENERATE_CREATED_TTLs",
            generate_updated_ttl=f"GENERATE_UPDATED_TTLs",
        )
    )
  )
  

  Ganti kode berikut:

  • CREATE_TTL: Durasi dalam detik untuk TTL kenangan yang dibuat menggunakan CreateMemory.
  • GENERATE_CREATED_TTL: Durasi dalam detik untuk TTL kenangan yang dibuat menggunakan GenerateMemories.
  • GENERATE_UPDATED_TTL: Durasi dalam detik untuk TTL kenangan yang diperbarui menggunakan GenerateMemories. Waktu habis masa berlaku yang baru dihitung (sekarang + TTL) akan menggantikan waktu habis masa berlaku Memori sebelumnya.

Langkah berikutnya

Panduan memulai

Panduan memulai Memory Bank API

Mulai menggunakan Memory Bank API untuk mengelola memori jangka panjang.

Panduan memulai

Mulai Cepat dengan Agent Development Kit

Mulai menggunakan Agent Development Kit (ADK).