הגדרת Memory Bank

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

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

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

לפני שמתחילים לעבוד עם 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, if it is not already enabled.

    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, if it is not already enabled.

    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-agentplatform>=2.0.1

אימות

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

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

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

Agent Platform SDK 

import agentplatform

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

איפה

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

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

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

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

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

# create the resource
memory_bank = client.memory_banks.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.name)

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

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

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

שימוש ב-Agent Runtime

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

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

AdkApp

אם אתם משתמשים בתבנית של הערכה לפיתוח סוכנים (ADK) ב-Agent Platform, הסוכן משתמש ב-VertexAiMemoryBankService כברירת מחדל כשהוא נפרס ב-Agent Runtime. כלומר, כלי הזיכרון של ADK קוראים זיכרונות מ-Memory Bank.

from google.adk.agents import Agent
from agentplatform.frameworks 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.runtimes.create(
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
runtime = client.runtimes.update(
      name=runtime.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,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.memory_banks.create()

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

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

יצירה

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "generation_config": ...,
    "unstructured_memory_configs": [...],
    "structured_memory_configs": [...],
    "similarity_search_config": ...,
    "ttl_config": ...,
    "disable_memory_revisions": False,
  }
)

עדכון

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

memory_bank = client.memory_banks.update(
  # You can access the name using `memory_bank.name` for a MemoryBank object.
  name="MEMORY_BANK_NAME",
  managed_semantic_memory_config={
    "generation_config": ...,
    "unstructured_memory_configs": [...],
    "structured_memory_configs": [...],
    "similarity_search_config": ...,
    "ttl_config": ...,
    "disable_memory_revisions": False,
  }
)

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

  • ‫MEMORY_BANK_NAME: השם של Memory Bank. הוא צריך להיות בפורמט projects/.../locations/.../reasoningEngines/.... אזורים נתמכים ב-Memory Bank

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

הגדרת מופע של Memory Bank

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

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

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

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

מילון

managed_semantic_memory_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"
  },
  "unstructured_memory_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "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"}}
      ],
      "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 agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  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"
  ),
  unstructured_memory_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.

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config=managed_semantic_memory_config
)

# Alternatively, update an existing Memory Bank instance's config.
memory_bank = client.memory_banks.update(
    name=memory_bank.name,
    managed_semantic_memory_config=managed_semantic_memory_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": [...]
}

managed_semantic_memory_config = {
  "unstructured_memory_configs": [
    user_level_config,
    default_config
  ]
}

מבוסס-כיתה 

from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

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

default_config = CustomizationConfig(
  memory_topics=[...],
  generate_memories_examples=[...]
)

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[
    user_level_config,
    default_config,
  ]
)

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

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

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

    מילון

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

    מבוסס-כיתה

    from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.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 agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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)

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

מומלץ תמיד להשתמש בדוגמאות בודדות עם נושאים מותאמים אישית כדי ש-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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from agentplatform.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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.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 agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

התאמה אישית של איחוד

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

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

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

מילון

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

מבוסס-כיתה

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

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

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

החלת הגדרות של התאמה אישית

כדי להחיל הגדרות של התאמה אישית על מופע Memory Bank, צריך לספק אותן ברשימה unstructured_memory_configs של managed_semantic_memory_config:

מילון

managed_semantic_memory_config = {
  "unstructured_memory_configs": [customization_config],
  # Include other configurations (similarity search, generation, TTL)...
}

מבוסס-כיתה

from agentplatform.types import ManagedSemanticMemoryConfig

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[customization_config],
  # Include other configurations (similarity search, generation, TTL)...
)

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

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

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

מילון

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

מבוסס-כיתה 

from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig

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.

מילון

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

מבוסס-כיתה 

from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig

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.

    מילון

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

    מבוסס-כיתה 

    from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig

ttl_config = TtlConfig(
    default_ttl=f"TTLs"
)

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

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

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

    מילון

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

    מבוסס-כיתה 

    from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfigGranularTtlConfig as GranularTtlConfig

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) יחליף את זמן התפוגה הקודם של הזיכרון.

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

Quickstart

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

Quickstart

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