הגדרת Memory Bank

כדי להשתמש ב-Agent Platform Memory Bank, קודם צריך ליצור ולהגדיר מופע של Memory Bank. המופע הזה מנהל את הזיכרונות שלכם, ואפשר לשלב אותו עם הסוכנים שלכם בסביבות זמן ריצה שונות.

במסמך הזה מוסבר איך להגדיר את הפרויקט, להתקין את הספריות הנדרשות וליצור או לעדכן מכונה עם הגדרות מותאמות אישית כמו נושאים ו-TTL. Google Cloud

קדימה, מתחילים

לפני שמתחילים לעבוד עם Memory Bank, צריך להגדיר את הסביבה.

הגדרה של Google Cloud הפרויקט

כל פרויקט יכול להיות מזוהה בשתי דרכים: מספר הפרויקט או מזהה הפרויקט. ‫PROJECT_NUMBER נוצר באופן אוטומטי כשיוצרים את הפרויקט, ואילו PROJECT_ID נוצר על ידיכם או על ידי מי שיצר את הפרויקט. כדי להגדיר פרויקט:

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

קבלת התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לשימוש ב-Memory Bank, צריך לבקש מהאדמין להקצות לכם בפרויקט את תפקידי ה-IAM הבאים:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

אם אתם שולחים בקשות ל-Memory Bank מסוכן שהופעל ב-Google Kubernetes Engine‏ (GKE) או ב-Cloud Run, ודאו שלחשבון השירות שלכם יש את ההרשאות הנדרשות. ל-Reasoning Engine Service Agent כבר יש את ההרשאות הנדרשות לקריאה ולכתיבה של זיכרונות, כך שלבקשות יוצאות מ-Agent Runtime כבר צריכה להיות הרשאה לגשת ל-Memory Bank.

התקנת ספריות

בקטע הזה מניחים שהגדרתם סביבת פיתוח בשפת Python, או שאתם משתמשים בסביבת זמן ריצה עם סביבת פיתוח בשפת Python (כמו Colaboratory).

מתקינים את Agent Platform SDK:

pip install google-cloud-aiplatform>=1.111.0

אימות

פועלים לפי ההוראות במאמר אימות ל-Vertex AI.

הגדרת לקוח של Agent Platform SDK

מריצים את הקוד הבא כדי להגדיר לקוח של Agent Platform SDK:

Agent Platform SDK 

import vertexai

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

איפה

נקודות קצה גלובליות ונקודות קצה עם מספר אזורים

‫Memory Bank תומך בנקודות קצה גלובליות ורב-אזוריות:

  • במקרים גלובליים, מגדירים את המיקום ל-global.
  • במקרים של מופעים במספר אזורים, צריך להגדיר את המיקום ל-us או ל-eu.

יצירה או עדכון של מופע של Memory Bank

כדי להתחיל להשתמש ב-Memory Bank, קודם צריך ליצור מופע של Memory Bank. אם עדיין אין לכם מופע, אתם יכולים ליצור אחד באמצעות הגדרת ברירת המחדל ושם לתצוגה לפי בחירתכם.

# create the resource
memory_bank = client.agent_engines.create(
    config={
        "display_name": "My Memory Bank",
    }
)

# Optionally, print out the Memory Bank resource name. You will need the
# resource name to interact with your Memory Bank instance later on.
print(memory_bank.api_resource.name)

אם רוצים להתאים אישית את ההגדרה של מופע חדש או קיים של Memory Bank, אפשר לעיין במאמר בנושא הגדרת מופע Memory Bank. לדוגמה, אתם יכולים לציין איזה מידע Memory Bank מחשיב כמשמעותי לשמירה.

אחרי שיש לכם מופע של Memory Bank, אתם יכולים להשתמש בשם של המופע כדי לקרוא או לכתוב זיכרונות. לדוגמה:

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

שימוש עם Agent Runtime

אפשר להשתמש ב-Memory Bank בכל זמן ריצה, אבל אפשר גם להשתמש ב-Memory Bank עם Agent Runtime כדי לקרוא ולכתוב זיכרונות מהסוכן שפרסתם.

כדי לפרוס סוכן ב-Agent Runtime עם Memory Bank מובנה, קודם צריך להגדיר את הסביבה ל-Agent Runtime. לאחר מכן, מכינים את הסוכן לפריסה ב-Agent Runtime עם שילוב של זיכרון. הסוכן שפרסתם צריך להתקשר כדי לקרוא ולכתוב זיכרונות לפי הצורך.

AdkApp

אם אתם משתמשים בתבנית של הערכה לפיתוח סוכנים (ADK) בפלטפורמת הסוכנים, הסוכן משתמש ב-VertexAiMemoryBankService כברירת מחדל כשהוא נפרס ב-Agent Runtime. המשמעות היא שכלי הזיכרון של ADK קוראים זיכרונות מ-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.
runtime = 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.
runtime = client.agent_engines.update(
      name=runtime.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

מחליפים את מה שכתוב בשדות הבאים:

  • ‫STAGING_BUCKET: הקטגוריה של Cloud Storage שבה רוצים להשתמש כדי להכין את Agent Runtime.

מידע נוסף על השימוש ב-Memory Bank עם ADK זמין במדריך למתחילים לשימוש ב-ADK.

סוכן מותאם אישית

אתם יכולים להשתמש ב-Memory Bank עם סוכן בהתאמה אישית שפרוס ב-Agent Runtime. במקרה כזה, הסוכן צריך לתזמן שיחות עם Memory Bank כדי להפעיל יצירת זיכרון ושיחות של שליפת זיכרון.

האפליקציה שנפרסה ב-Agent Runtime יכולה לקרוא את משתני הסביבה GOOGLE_CLOUD_PROJECT,‏ GOOGLE_CLOUD_LOCATION ו-GOOGLE_CLOUD_AGENT_ENGINE_ID כדי להסיק את השם של Agent Runtime מהסביבה:

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

אם אתם משתמשים בסוכן השירות שמוגדר כברירת מחדל עבור הסוכן שלכם ב-Agent Runtime, לסוכן שלכם כבר יש הרשאה לקרוא ולכתוב זיכרונות. אם אתם משתמשים בחשבון שירות לקוחות, אתם צריכים להעניק לחשבון השירות שלכם הרשאות לקריאה ולכתיבה של זיכרונות. ההרשאות הנדרשות תלויות בפעולות שהסוכן צריך להיות מסוגל לבצע. אם רוצים שהסוכן רק יאחזר ויצור זיכרונות, aiplatform.memories.generate ו- aiplatform.memories.retrieve מספיקים.

שימוש בכל סביבות זמן הריצה האחרות

אם רוצים להשתמש ב-Memory Bank בסביבה אחרת, כמו Cloud Run או Colab, צריך ליצור Memory Bank. אם לא תספקו הגדרה, ייווצר Memory Bank עם הגדרות ברירת המחדל לניהול תהליך יצירת זיכרון ואחזור.

memory_bank = client.agent_engines.create()

אם השתמשתם בעבר ב-Memory Bank, יצירת מופע חדש של Memory Bank אמורה להימשך כמה שניות בלבד. אם זו הפעם הראשונה שאתם משתמשים ב-Memory Bank, יכול להיות שייקח יותר זמן (דקה עד שתיים).

אם רוצים להגדיר את ההתנהגות, צריך לספק הגדרות של Memory Bank:

יצירה

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

עדכון

אם רוצים לשנות את ההגדרה של Memory Bank, אפשר לעדכן את המופע של Memory Bank.

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

מחליפים את מה שכתוב בשדות הבאים:

אתם יכולים להשתמש ב-Memory Bank בכל סביבה שיש לה הרשאה לקרוא ולכתוב זיכרונות. לדוגמה, כדי להשתמש ב-Memory Bank עם Cloud Run, צריך להעניק הרשאות לזהות שירות Cloud Run לקריאה ולכתיבה של זיכרונות. ההרשאות הנדרשות תלויות בפעולות שהסוכן צריך לבצע. אם רוצים שהסוכן יאחזר ויצור רק זיכרונות, מספיק להשתמש ב-aiplatform.memories.generate וב-aiplatform.memories.retrieve.

הגדרת מופע Memory Bank

אתם יכולים להגדיר את Memory Bank כדי להתאים אישית את האופן שבו הזיכרונות נוצרים ומנוהלים. אם לא תספקו את ההגדרה, Memory Bank ישתמש בהגדרות ברירת המחדל לכל סוג של הגדרה.

אפשר להגדיר את ההגדרות הבאות של Memory Bank עבור המופע:

  • הגדרת התאמה אישית: הגדרה של אופן החילוץ של זיכרונות מנתוני המקור ואיחוד שלהם עם זיכרונות קיימים.
  • הגדרת חיפוש דמיון: מציינת את מודל ההטמעה שבו Memory Bank משתמש לחיפוש דמיון. ברירת המחדל היא text-embedding-005.
  • הגדרת יצירה: הגדרה של LLM ש-Memory Bank משתמש בו לתהליך יצירת זיכרון. ברירת המחדל היא gemini-3.5-flash.
  • הגדרת TTL: הגדרה של אופן ההגדרה האוטומטית של TTL לזיכרונות שנוצרו או עודכנו. ברירת המחדל היא ללא TTL.

הדוגמה הבאה מציגה את Memory Bank שמוגדר כברירת מחדל:

מילון

memory_bank_config = {
  "generation_config": {
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.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
}

מבוסס על כיתה

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-3.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-3.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
)

אפשר לשנות את ההגדרות של Memory Bank כשיוצרים או מעדכנים את המכונה. בדוגמה הבאה מוסבר איך ליצור או לעדכן מכונה עם הגדרה ספציפית של Memory Bank.

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

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

הגדרת התאמה אישית של הזיכרון בשפה טבעית

כדי לשנות את האופן שבו Memory Bank מחלץ זיכרונות בשפה טבעית, צריך להגדיר את אופן החילוץ כשמגדירים את המופע. אפשר להשתמש באפשרויות הבאות כדי להתאים אישית את ההתנהגות:

אפשר לחשוב על התאמה אישית של אופן החילוץ של Memory Bank בשני שלבים: הסבר והדגמה. נושאי הזיכרון אומרים ל-Memory Bank איזה מידע לשמור. דוגמאות מעטות מראות ל-Memory Bank איזה סוג מידע צריך להוביל לזיכרון ספציפי, ועוזרות לו ללמוד את הדפוסים, הניואנסים והניסוחים שאתם מצפים שהוא יבין.

אפשר גם להגדיר התנהגות שונה לרמות שונות של היקף. לדוגמה, יכול להיות שנושאים שחשובים לזיכרונות ברמת הסשן לא יהיו חשובים לזיכרונות ברמת המשתמש (במהלך כמה סשנים). כדי להגדיר התנהגות עבור קבוצת משנה מסוימת של זיכרונות, צריך להגדיר את מפתחות ההיקף של הגדרת ההתאמה האישית. רק בקשות GenerateMemories שכוללות את מפתחות ההיקף האלה ישתמשו בתצורה הזו. אפשר גם להגדיר התנהגות ברירת מחדל (שתחול על כל קבוצות מפתחות ההיקף) על ידי השמטת השדה scope_key. התצורה הזו תחול על כל הבקשות שלא מוגדרת להן תצורה שתואמת בדיוק למפתחות ההיקף של תצורת התאמה אישית אחרת.

לדוגמה, user_level_config יחול רק על בקשות GenerateMemories שמשתמשות בדיוק במפתח ההיקף user_id (כלומר scope={"user_id": "123"} ללא מפתחות נוספים). ההסכמה שניתנה ל-default_config תחול גם על בקשות אחרות:

מילון 


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

מבוסס על כיתה 

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

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

הגדרת נושאים בזיכרון

'נושאי זיכרון' מזהים איזה מידע ב-Memory Bank נחשב משמעותי ולכן צריך לשמור אותו כזיכרונות שנוצרו. ב-Memory Bank יש תמיכה בשני סוגים של נושאי זיכרון:

  • נושאים מנוהלים: התווית וההוראות מוגדרות על ידי Memory Bank. צריך לציין רק את השם של הנושא המנוהל. לדוגמה,

    מילון

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

    מבוסס על כיתה

    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
    )
)

    ב-Memory Bank יש תמיכה בנושאים המנוהלים הבאים:

    • פרטי משתמש (USER_PERSONAL_INFO): מידע חשוב על המשתמש, כמו שמות, קשרים, תחביבים ותאריכים חשובים. לדוגמה, "אני עובד ב-Google" או "יום הנישואים שלי הוא ב-31 בדצמבר".
    • העדפות משתמש (USER_PREFERENCES): העדפות מוצהרות או משתמעות לגבי לייקים, דיסלייקים, סגנונות או דוגמאות עיצוב. לדוגמה, "אני מעדיף את המושב האמצעי".
    • אירועים מרכזיים בשיחה ותוצאות של משימות (KEY_CONVERSATION_DETAILS): אבני דרך או מסקנות חשובות בדיאלוג. לדוגמה, "הזמנתי כרטיסי טיסה הלוך ושוב בין JFK ל-SFO. אני יוצא לחופשה ב-1 ביוני 2025 וחוזר ב-7 ביוני 2025".
    • הוראות מפורשות לזכור או לשכוח (EXPLICIT_INSTRUCTIONS): מידע שהמשתמש מבקש מהסוכן לזכור או לשכוח. לדוגמה, אם המשתמש אומר "תזכור שאני משתמש בעיקר ב-Python", Memory Bank יוצר זיכרון כמו "אני משתמש בעיקר ב-Python".

  • נושאים בהתאמה אישית: אתם מגדירים את התווית וההוראות כשמגדירים את המופע של Memory Bank. הם ישמשו בהנחיה לשלב החילוץ של מאגר הזיכרון. לדוגמה,

    מילון

    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."""
    }
}

    מבוסס על כיתה

    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."""
  )
)

    כשמשתמשים בנושאים מותאמים אישית, מומלץ גם לספק פרומפט עם כמה דוגמאות (few-shot) שמדגימות איך צריך לחלץ זיכרונות מהשיחה.

בעזרת התאמה אישית, אפשר להשתמש בכל שילוב של נושאי זיכרון. לדוגמה, אתם יכולים להשתמש בקבוצת משנה של הנושאים הזמינים בנושא ניהול זיכרון:

מילון

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

מבוסס על כיתה

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)
      ),
  ]
)

אפשר גם לשלב בין נושאים מנוהלים לנושאים בהתאמה אישית (או להשתמש רק בנושאים בהתאמה אישית):

מילון

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

מבוסס על כיתה

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

פרומפט עם כמה דוגמאות (few-shot)

דוגמאות עם מעט נתונים מאפשרות לכם להדגים ל-Memory Bank את התנהגות החילוץ הצפויה של הזיכרון. לדוגמה, אפשר לספק דוגמה לשיחה ולהזין את הזיכרונות שרוצים לחלץ מהשיחה הזו.

מומלץ להשתמש תמיד בשיטת few-shot עם נושאים מותאמים אישית כדי ש-Memory Bank יוכל ללמוד את ההתנהגות הרצויה. כשמשתמשים בנושאים מנוהלים, לא חייבים להשתמש בשיטת few-shot, כי Memory Bank מגדיר דוגמאות לכל נושא. הדגמה של שיחות שלא צפויות להניב זיכרונות על ידי הצגת רשימה ריקה של generated_memories.

לדוגמה, אפשר לספק פרומפט עם כמה דוגמאות (few-shot) שממחישות איך לחלץ משוב על העסק מהודעות של לקוחות:

מילון

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

מבוסס על כיתה

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

אפשר גם לספק דוגמאות לשיחות שלא אמורות להניב זיכרונות שנוצרו על ידי AI, על ידי מתן רשימה ריקה לפלט הצפוי (generated_memories):

מילון

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": []
}

מבוסס על כיתה

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=[]
)

נקודת מבט בנושא זיכרון

כברירת מחדל, הזיכרונות נוצרים בגוף ראשון (למשל, "אני משתמש ב-Memory Bank לניהול זיכרון"). אתם יכולים להגדיר את Memory Bank כך שיפיק תיאור בגוף שלישי (לדוגמה, "המשתמש משתמש ב-Memory Bank לניהול הזיכרון") באמצעות הפרמטר enable_third_person_memories.

מילון

customization_config = {
  "enable_third_person_memories": True
}

מבוסס על כיתה

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

התאמה אישית של קונסולידציה

במהלך האיחוד, Memory Bank קובע איך לשלב מידע חדש שנרכש במערך הזיכרון הקיים. הזיכרון המרכזי בודק אם צריך להוסיף זיכרונות חדשים, לעדכן זיכרונות קיימים עם הקשר נוסף או למחוק זיכרונות לא רלוונטיים.

כדי לוודא שהזיכרונות יהיו איכותיים ומגובים בנתונים, אפשר להגדיר את Memory Bank כך שינתח את ההיסטוריה של הזיכרון כדי להבחין בין מגמות ארוכות טווח לבין חריגות חד-פעמיות.

כברירת מחדל, מאגר הזיכרון משווה מידע חדש רק לתמונת המצב העדכנית ביותר של הזיכרון של המועמד ('עדכון זיכרון'). כדי להעמיק את הניתוח הזה, צריך להגדיר את הפרמטר revisions_per_candidate_count. הפרמטר הזה מגדיר כמה גרסאות קודמות של כל 'זיכרון פוטנציאלי' (הרשומה הספציפית שנבדקת לצורך עדכון) נלקחות בחשבון ב-Memory Bank במהלך האיחוד.

מילון

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

מבוסס על כיתה

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
    )
)

הגדלת הערך של revisions_per_candidate_count תגרום לכך שהזיכרונות יהיו עקביים יותר ומגובים בראיות, כי המערכת תביא בחשבון את החזרה על מידע שהוזן. עם זאת, ככל שהמספר גבוה יותר, כך צריכת האסימונים גבוהה יותר במהלך תהליך האיחוד.

הגדרת חיפוש לפי דמיון

ההגדרה של חיפוש הדמיון קובעת באיזה מודל הטמעה נעשה שימוש במופע שלכם לחיפוש הדמיון. חיפוש דמיון משמש לזיהוי של זיכרונות שמועמדים לאיחוד ולשליפה של זיכרונות שמבוססת על חיפוש דמיון. אם לא מספקים את ההגדרה הזו, Memory Bank משתמש ב-text-embedding-005 כמודל ברירת המחדל.

אם אתם מצפים שהשיחות עם המשתמשים יהיו בשפות שאינן אנגלית, כדאי להשתמש במודל שתומך בכמה שפות, כמו gemini-embedding-2,‏ gemini-embedding-001 או text-multilingual-embedding-002, כדי לשפר את איכות האחזור.

מילון

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

מבוסס על כיתה 

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

מחליפים את מה שכתוב בשדות הבאים:

  • ‫EMBEDDING_MODEL: מודל הטמעת הטקסט של Google שמשמש לחיפוש דמיון, בפורמט projects/{project}/locations/{location}/publishers/google/models/{model}.

הגדרת היצירה

הגדרת היצירה קובעת באיזה מודל שפה גדול (LLM) המערכת משתמשת כדי ליצור זיכרונות, כולל חילוץ זיכרונות ואיחוד זיכרונות חדשים עם זיכרונות קיימים.

החל מ-29 ביוני 2026, ב-Memory Bank נעשה שימוש ב-gemini-3.5-flash עבור מודל ברירת המחדל. מופעים שנוצרו לפני התאריך הזה משתמשים ב-gemini-2.5-flash.

למופעים חדשים של Memory Bank שמשתמשים במודל ברירת המחדל:

  • מופעים של Memory Bank בusמספר אזורים או בus-*אזור יחיד (לדוגמה, us-central1) משתמשים בנקודת הקצה של Gemini 3.5 במספר אזורים us.
  • מופעי Memory Bank באזור גיאוגרפי נרחב eu או באזור יחיד eu-* (לדוגמה, europe-west2) משתמשים בנקודת הקצה של Gemini 3.5 באזור גיאוגרפי נרחב eu.
  • כל האזורים האחרים של Memory Bank משתמשים בנקודת הקצה הגלובלית של Gemini 3.5.

במקרים של Memory Bank שנוצרו לפני 29 ביוני 2026 באמצעות מודל ברירת המחדל, Memory Bank משתמש בנקודת הקצה של global Gemini באזורים שבהם אין נקודת קצה אזורית של Gemini 2.5.

מילון

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

מבוסס על כיתה 

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

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

מחליפים את מה שכתוב בשדות הבאים:

  • ‫LLM_MODEL: מודל ה-LLM של Google שבו משתמשים כדי לחלץ ולצרף זיכרונות, בפורמט projects/{project}/locations/{location}/publishers/google/models/{model}.

הגדרת אורך חיים (TTL)

ההגדרה של אורך החיים (TTL) קובעת איך Memory Bank צריך להגדיר באופן דינמי את זמן התפוגה של הזיכרונות. אחרי שתוקף הזיכרונות יפוג, הם לא יהיו זמינים לשחזור ויימחקו.

אם לא מספקים את ההגדרה, זמן התפוגה של הזיכרונות שנוצרו או עודכנו לא מוגדר באופן דינמי, ולכן הזיכרונות לא יפוגו אלא אם זמן התפוגה שלהם יוגדר באופן ידני.

יש שתי אפשרויות להגדרת ה-TTL:

  • Default TTL (ערך ברירת מחדל של TTL): ערך ה-TTL יחול על כל הפעולות שיוצרות או מעדכנות זיכרון, כולל UpdateMemory,‏ CreateMemory ו-GenerateMemories.

    מילון

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

    מבוסס על כיתה 

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫TTL: משך הזמן בשניות של ה-TTL. בזיכרונות מעודכנים, זמן התפוגה החדש שחושב (עכשיו + TTL) יחליף את זמן התפוגה הקודם של הזיכרון.

  • TTL גרנולרי (לכל פעולה): ה-TTL מחושב על סמך הפעולה שיצרה או עדכנה את הזיכרון. אם לא מגדירים את השדה הזה לפעולה מסוימת, הפעולה לא תעדכן את תאריך התפוגה של הזיכרון.

    מילון

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

    מבוסס על כיתה 

    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",
      )
  )
)

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CREATE_TTL: משך הזמן בשניות של ה-TTL של זיכרונות שנוצרו באמצעות CreateMemory.
    • ‫GENERATE_CREATED_TTL: משך הזמן בשניות של ה-TTL של זיכרונות שנוצרו באמצעות GenerateMemories.
    • ‫GENERATE_UPDATED_TTL: משך הזמן בשניות של ה-TTL של זיכרונות שעודכנו באמצעות GenerateMemories. זמן התפוגה החדש שחושב (עכשיו + TTL) יחליף את זמן התפוגה הקודם של הזיכרון.

המאמרים הבאים

תחילת העבודה

כדי לנהל זיכרונות לטווח ארוך, אפשר להתחיל להשתמש ב-Memory Bank API.

תחילת העבודה

איך מתחילים לעבוד עם הערכה לפיתוח סוכנים (ADK).