Agent Platform Memory Bank API quickstart

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

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

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

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

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

import vertexai

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

memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()

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

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

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

    import vertexai

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

session = client.agent_engines.sessions.create(
  # The name can be fetched using `sessions.api_resource.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.agent_engines.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.agent_engines.memories.generate(
  name=memory_bank.api_resource.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.agent_engines.memories.generate(
    name=memory_bank.api_resource.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.agent_engines.memories.create(
    name=memory_bank.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  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 all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=memory_bank.api_resource.name,
        scope={"user_id": "123"}
    )
)

אתם יכולים להשתמש ב-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.agent_engines.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.agent_engines.memories.purge(
    name=memory_bank.api_resource.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.agent_engines.memories.purge(
    name=memory_bank.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

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

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

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

from google import genai

client.agent_engines.memories.generate(
    name=memory_bank.api_resource.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, משתמשים בדוגמת הקוד הבאה. המחיקה הזו תגרום גם למחיקה של כל הסשנים או הזיכרונות שמשויכים למופע Agent Platform.

    agent_engine.delete(force=True)

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

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

תחילת העבודה

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