Agent Platform Memory Bank API quickstart

אתם יכולים להשתמש ב-Agent Platform SDK כדי לבצע קריאות ל-API ישירות אל Memory Bank. אם אתם לא רוצים ש-Agent Framework יתזמר בשבילכם קריאות, או שאתם רוצים לשלב את Memory Bank עם Agent Framework אחרים חוץ מהערכה לפיתוח סוכנים (ADK), אתם יכולים להשתמש ב-Agent Platform SDK.

במסמך הזה מוסבר איך ליצור, להעלות, לאחזר ולהסיר זיכרונות באמצעות קריאות ל-API.

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

לפני שמתחילים

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

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

יצירת זיכרונות באמצעות סשנים ב-Agent Platform

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

  1. יוצרים סשן עם מזהה משתמש אטום. כל הזיכרונות שנוצרים בסשן הזה מקבלים באופן אוטומטי את ההיקף {"user_id": "USER_ID"}, אלא אם מציינים היקף אחר באופן מפורש כשיוצרים את הזיכרונות.

    import agentplatform

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

session = client.sessions.create(
  # The name can be fetched using `sessions.name`.
  name="SESSIONS_NAME",
  user_id="USER_ID"
)

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

    • ‫PROJECT_ID: מזהה הפרויקט.

    • ‫LOCATION: האזור שלכם. רשימת האזורים שבהם אפשר להשתמש ב-Memory Bank

    • ‫SESSIONS_NAME: השם של המכונה של Sessions שיצרתם או של מכונה קיימת של Sessions. השם צריך להיות בפורמט הבא: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • ‫USER_ID: מזהה של המשתמש. כל הזיכרונות שנוצרים בסשן הזה מקבלים באופן אוטומטי את ההיקף {"user_id": "USER_ID"}, אלא אם מציינים היקף אחר באופן מפורש כשיוצרים זיכרונות.

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

    import datetime

client.sessions.events.append(
  name=session.response.name,
  author="user",  # Required by Sessions.
  invocation_id="1",  # Required by Sessions.
  timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
  config={
    "content": {
      "role": "user",
      "parts": [{"text": "hello"}]
    }
  }
)

  3. כדי ליצור זיכרונות מהיסטוריית השיחות, צריך להפעיל בקשה ליצירת זיכרון בסשן:

    client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
    # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
    "session": session.response.name
  },
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE
)

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

  • ‫SCOPE (אופציונלי): מילון שמייצג את היקף הזיכרונות שנוצרו, עם עד 5 זוגות של ערכי מפתח וללא תווים של *. לדוגמה, {"session_id": "MY_SESSION"}. רק זיכרונות עם אותו היקף נלקחים בחשבון לאיחוד. אם לא מציינים ערך, המערכת משתמשת ב-{"user_id": session.user_id}.

העלאת זיכרונות

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

כדי לשמור על עקביות עם הזיכרונות שנוצרו, נסו לכתוב עובדות שחולצו מראש באותה נקודת מבט שהגדרתם להיקף הנתון. כברירת מחדל, הזיכרונות נוצרים בגוף ראשון (לדוגמה, I am a software engineer).

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

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

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

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • ‫SCOPE: מילון שמייצג את היקף הזיכרונות שנוצרו. לדוגמה, {"session_id": "MY_SESSION"}. רק זיכרונות עם אותו היקף נלקחים בחשבון לאיחוד.

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

memory = client.memory_banks.memories.create(
    name=memory_bank.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns a MemoryOperation containing the created Memory like:

MemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

אחזור זיכרונות ושימוש בהם

אתם יכולים לאחזר זיכרונות של המשתמש ולכלול אותם בהוראות המערכת כדי לתת ל-LLM גישה להקשר אישי שלכם.

איך מאחזרים זיכרונות

# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

אתם יכולים להשתמש ב-jinja כדי להמיר את הזיכרונות המובְנים להנחיה:


from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

הסרת זיכרונות

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

הסרה לפי שם המשאב

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

client.memory_banks.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

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

  • ‫MEMORY_NAME: שם הזיכרון שרוצים למחוק. השם צריך להיות בפורמט הבא: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. כדי למצוא את שם הזיכרון, צריך לאחזר את הזיכרונות.

הסרה לפי קריטריונים

אתם יכולים להשתמש במחיקה לפי קריטריונים כדי להסיר זיכרון אחד או יותר. רק הזיכרונות שתואמים למסננים שציינתם יימחקו. צריך לציין לפחות אחד מהשדות filter (שמיושם בשדות המערכת) או filter_groups (שמיושם בשדות המטא-נתונים).

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    # Specify at least one of `filter` or `filter_groups`.
    filter="FILTER_STRING",
    filter_groups=FILTER_GROUPS,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

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

  • ‫FILTER_STRING: מחרוזת שמשתמשת בתחביר EBNF לסינון לפי שדות מערכת. שדות המערכת כוללים את create_time, update_time, fact ו-topics. מידע נוסף על סינון לפי שדות מערכת מופיע בקטע סינון לפי שדות מטא-נתונים בדף "אחזור זיכרונות".
  • ‫FILTER_GROUPS: רשימה של מילונים או אובייקטים לסינון לפי מטא-נתונים של זיכרון. מידע נוסף על סינון לפי שדות מטא-נתונים זמין בקטע סינון לפי שדות מערכת בדף "אחזור זיכרונות".

הפעולה תחזיר את מספר הזיכרונות שנמחקו (אם force=True) או שהיו נמחקים אם הפעולה הייתה מבוצעת (אם force=False).

print(operation.response.purge_count)

לדוגמה, אפשר למחוק את כל הזיכרונות ששייכים להיקף user_id "123":

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

הסרה לפי משמעות סמנטית

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

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

from google import genai

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

הסרת המשאבים

כדי להסיר את כל המשאבים שבהם השתמשתם בפרויקט, אתם יכולים למחוק את הפרויקט ב- Google Cloud שבו השתמשתם במדריך למתחילים.

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

  1. כדי למחוק את Agent Platform Memory Bank ואת Agent Runtime במכונות של Gemini Enterprise Agent Platform, משתמשים בדוגמת הקוד הבאה:

    client.memory_banks.delete(name=memory_bank.name, force=True)
client.runtimes.delete(name=sessions.name, force=True)

  2. מוחקים את כל הקבצים שנוצרו באופן מקומי.

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

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

יצירת סוכן ADK שזוכר את העדפות המשתמש.