הגדרת Memory Bank

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

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

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

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

הגדרת הפרויקט ב- Cloud de Confiance

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

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

  2. Verify that billing is enabled for your Cloud de Confiance project.

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

קבלת ההרשאות הנדרשות

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

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

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

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

התקנת ספריות

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

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

pip install google-cloud-agentplatform>=2.0.1

אימות

פועלים לפי ההוראות במאמר אימות ב-Gemini Enterprise Agent Platform.

הגדרת לקוח של 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) של פלטפורמת הסוכנים, הסוכן משתמש ב-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:

יצירה

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.runtimes.update(
  # You can access the name using `memory_bank.name` for a MemoryBank object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": {
        "generation_config": ...,
        "customization_configs": [...],
        "structured_memory_configs": [...],
        "similarity_search_config": ...,
        "ttl_config": ...,
        "disable_memory_revisions": False,
      }
    }
  }
)

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

אתם יכולים להשתמש ב-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
)

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

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

אפשר לחשוב על התאמה אישית של התנהגות החילוץ של Memory Bank בשני שלבים: הסבר והדגמה. נושאי הזיכרון מורים ל-Memory Bank איזה מידע לשמור. פרומפט עם כמה דוגמאות (few-shot) מראות ל-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 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."
        )
    ]
)

אפשר גם לספק דוגמאות לשיחות שלא אמורות ליצור זיכרונות, על ידי מתן רשימה ריקה לפלט הצפוי (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 יכול לנתח את ההיסטוריה של הזיכרון כדי להבחין בין מגמות לטווח ארוך לבין חריגות חד-פעמיות.

כברירת מחדל, 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)...
)

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

הגדרת החיפוש לפי דמיון קובעת באיזה מודל הטמעה המכונה משתמשת לחיפוש לפי דמיון. חיפוש לפי דמיון משמש לזיהוי הזיכרונות שצריך להעביר לאיחוד ולאחזור זיכרון שמבוסס על חיפוש לפי דמיון. אם לא תספקו את ההגדרה הזו, המערכת תשתמש במודל 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:

  • ברירת המחדל של 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 כדי לנהל זיכרונות לטווח ארוך.

מדריך למתחילים

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