הערכה לפיתוח סוכנים (ADK) מקשרת בין הסוכנים ל-Memory Bank של פלטפורמת הסוכנים באמצעות VertexAiMemoryBankService, הטמעה של ממשק BaseMemoryService של ה-ADK. במאמר הזה מוסבר איך לבחור כלי לאחזור ול-callback של זיכרון, ואיך לחבר את שירות הזיכרון בכל סביבת זמן ריצה של ADK.
כדי להריץ דוגמה פתורה, קודם עיינו במדריך למתחילים בנושא Memory Bank עם ADK.
לפני שמתחילים
- נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloudליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
אם משתמשים במעטפת מקומית, צריך ליצור פרטי כניסה לאימות מקומי בחשבון המשתמש:
gcloud auth application-default login
אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.
אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו שנכנסתם ל-CLI של gcloud באמצעות הזהות המאוחדת.
- מתקינים את ADK ואת Agent Platform SDK:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- יוצרים מכונה של Memory Bank במסוף Google Cloud או באמצעות Agent Platform SDK. בדף Memory Bank, לוחצים על Link to an agent > Use with ADK כדי לקבל קוד הגדרה שמולא מראש. אם המופע נוצר על ידי Agent Runtime, אפשר לדלג על השלב הזה.
התפקידים הנדרשים
כדי לקבל את ההרשאות שנדרשות ליצירת מכונה של Memory Bank, וליצירה ולאחזור של זיכרונות, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- יצירה או עדכון של מכונה של Memory Bank: משתמש ב-Agent Platform (`roles/aiplatform.user`)
- לקרוא, לכתוב או ליצור זיכרונות: משתמש ב-Memory Bank (`roles/aiplatform.memoryUser`)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
איך רכיבי ADK פועלים עם Memory Bank
סוכן ADK משתמש ברכיבים הבאים כדי לקרוא ולכתוב זיכרונות:
| רכיב | תפקיד | חובה |
|---|---|---|
| מכונה של Memory Bank | אחסון ואיחוד של זיכרונות. | כן |
VertexAiMemoryBankService |
מקשר את הסוכן ל-Memory Bank בתור שירות הזיכרון של ADK. | כן |
| שירות סשנים | שומר את היסטוריית השיחות. אפשר להשתמש בכל שירות סשן של ADK. | כן |
| כלי לאחזור זיכרון | אחזור זיכרונות של הסוכן. איך מאחזרים זיכרונות באמצעות כלי | כדי לקרוא את הזיכרונות |
| קריאה חוזרת (callback) של יצירת זיכרון | שליחת אירועי שיחה ל-Memory Bank אחרי שהנציג מגיב. איך יוצרים זיכרונות באמצעות קריאה חוזרת (callback) | כדי לכתוב זיכרונות |
ADK Runner או AdkApp |
מתזמר את הנציג, השירותים, הכלים והקריאות החוזרות (callbacks). | כן |
בתרשים הבא מוצג איך הרכיבים האלה פועלים בכל שלב כשנציג משתמש ב-PreloadMemoryTool ובקריאה חוזרת (callback) לזיכרון:
Memory Bank מקצה כל זיכרון למזהה המשתמש ולשם האפליקציה שמפעילה את הנציג, בתור {"user_id": USER_ID, "app_name": APP_NAME}. רק בקשות עם אותו מזהה משתמש ושם אפליקציה מאחזרות את הזיכרונות האלה.
יצירת זיכרונות באמצעות פונקציית קריאה חוזרת (callback)
קריאה חוזרת (callback) של יצירת זיכרון שולחת אירועי שיחה אל Memory Bank. Memory Bank מחלץ זיכרונות מהאירועים האלה ומאחד אותם עם זיכרונות קיימים. בוחרים שיטה בהתאם לתדירות שבה מעבדים אירועים:
| Method | אירועים שנשלחו | מתי משתמשים |
|---|---|---|
callback_context.add_events_to_memory |
קבוצת משנה של אירועים שתבחרו | מומלץ. לעבד אירועים באופן מצטבר, למשל אחרי כל תור. |
callback_context.add_session_to_memory |
כל האירועים בסשן | צריך להפעיל את הפונקציה פעם אחת בסוף הסשן, כדי שאותם אירועים לא יעובדו יותר מפעם אחת. |
בדוגמה הבאה, אירועים אחרונים נשלחים אחרי כל תשובה של הנציג:
from google.adk.agents.callback_context import CallbackContext
async def generate_memories_callback(
callback_context: CallbackContext,
) -> None:
await callback_context.add_events_to_memory(
events=callback_context.session.events[-5:]
)
return None
כדי לשלוח את הסשן המלא, צריך להפעיל את await callback_context.add_session_to_memory() בקריאה חוזרת בסוף הסשן.
כברירת מחדל, VertexAiMemoryBankService שולח אירועים באמצעות הטמעת אירועים. כדי להמתין עד שתהליך יצירת הזיכרון יסתיים בבדיקות או בהדגמות, מעבירים את custom_metadata={"wait_for_completion": True} אל add_events_to_memory.
אחזור זיכרונות באמצעות כלי
כלי לאחזור זיכרונות שולט במועד שבו הנציג מאחזר זיכרונות ובאופן שבו הזיכרונות נכנסים להנחיה. בוחרים באחד מהכלים הבאים:
| כלי | כשהזיכרונות מאוחזרים | מתי משתמשים |
|---|---|---|
PreloadMemoryTool |
בתחילת כל תור. הזיכרונות מוזרקים להקשר של בקשת המודל לפני התור של המשתמש הנוכחי. | הגדירו הקשר בסיסי לגבי המשתמש בכל שלב. |
LoadMemoryTool |
כשהמודל מחליט שצריך להשתמש בזיכרונות כדי לענות על השאילתה. | המודל יחליט מתי הזיכרונות רלוונטיים. |
FunctionTool בהתאמה אישית |
כשהמודל קורא לכלי, בהתאם לתיאור של הכלי. | תנו לסוכן הוראות מתי לאחזר זיכרונות. |
בדוגמה הבאה נוצר סוכן שמשתמש ב-PreloadMemoryTool ובקריאה החוזרת (callback) מהקטע הקודם:
from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction="You are a vehicle voice agent. Limit responses to 30 words.",
tools=[PreloadMemoryTool()],
after_agent_callback=generate_memories_callback,
)
כדי לאפשר למודל להחליט מתי לאחזר זיכרונות, מייבאים את LoadMemoryTool מ-google.adk.tools.load_memory_tool ומעבירים את LoadMemoryTool() ב-tools.
כדי לכתוב כלי אחזור בהתאמה אישית, צריך להפעיל את tool_context.search_memory מקריאת API לכלי:
from typing import Any
from google import adk
from google.adk.tools import FunctionTool, ToolContext
async def search_memories(query: str, tool_context: ToolContext) -> Any:
"""Query this tool when you need information about user preferences."""
return await tool_context.search_memory(query)
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction=(
"You are a vehicle voice agent. Before you change a setting, call "
"search_memories to look up the user's preferences. Limit responses "
"to 30 words."
),
tools=[FunctionTool(func=search_memories)],
after_agent_callback=generate_memories_callback,
)
חיבור שירות הזיכרון לסביבת זמן הריצה
האופן שבו מתחברים אל VertexAiMemoryBankService תלוי במקום שבו הסוכן פועל. בוחרים את סביבת זמן הריצה:
מפעיל מקומי
כשמריצים את הנציג באמצעות adk.Runner, יוצרים את שירות הזיכרון ומעבירים אותו ל-runner:
import asyncio
import os
from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
memory_service = VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()
runner = adk.Runner(
agent=agent,
app_name="APP_NAME",
session_service=session_service,
memory_service=memory_service,
)
async def main() -> None:
session = await session_service.create_session(
app_name="APP_NAME",
user_id="USER_ID",
)
message = types.Content(
role="user", parts=[types.Part(text="Can you fix the temperature?")]
)
async for event in runner.run_async(
user_id="USER_ID",
session_id=session.id,
new_message=message,
):
if event.is_final_response() and event.content:
print(event.content.parts[0].text)
asyncio.run(main())
מחליפים את מה שכתוב בשדות הבאים:
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud , לדוגמה
my-project. - LOCATION: המיקום שלכם, לדוגמה
global. המיקומים שנתמכים ונקודות הקצה הגלובליות ובמספר אזורים של Memory Bank. - MEMORY_BANK_ID: מזהה המכונה של Memory Bank, לדוגמה
456ב-projects/my-project/locations/us-central1/reasoningEngines/456. - APP_NAME: שם האפליקציה ב-ADK, לדוגמה
my_agent. Memory Bank כולל את שם האפליקציה בהיקף הזיכרון, כך שהזיכרונות מבודדים בין האפליקציות. - USER_ID: מזהה של המשתמש, לדוגמה
user-123. הזיכרונות שנוצרים בסשן הזה מוגבלים למזהה הזה.
Agent Runtime ב-Gemini Enterprise Agent Platform
כשפורסים סוכן ADK ב-Agent Runtime באמצעות תבנית ADK (AdkApp), התבנית משתמשת ב-VertexAiMemoryBankService כברירת מחדל. אתם יכולים ליצור את המכונה של Memory Bank ולפרוס את הנציג בשלב אחד:
import asyncio
import agentplatform
from agentplatform.frameworks import AdkApp
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION",
)
adk_app = AdkApp(agent=agent)
# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
async def main() -> None:
session = await runtime_instance.async_create_session(
user_id="USER_ID"
)
async for event in runtime_instance.async_stream_query(
user_id="USER_ID",
session_id=session.get("id"),
message="Can you fix the temperature?",
):
print(event)
asyncio.run(main())
כדי לפרוס את הנציג במשאב קיים ולשמור את הזיכרונות הקיימים של המשאב, צריך להפעיל את client.runtimes.update:
runtime_instance = client.runtimes.update(
name="RUNTIME_NAME",
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
כשמריצים את AdkApp באופן מקומי, כברירת מחדל נעשה שימוש ב-InMemoryMemoryService.
כדי להשתמש ב-Memory Bank באופן מקומי, צריך לשנות את שירות הזיכרון:
from google.adk.memory import VertexAiMemoryBankService
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
מחליפים את מה שכתוב בשדות הבאים:
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud , לדוגמה
my-project. - LOCATION: האזור או מספר האזורים של Agent Runtime, לדוגמה
us-central1. רק מכונותVertexAiMemoryBankServiceעצמאיות תומכות ב-global, ולא ב-client.runtimes.create. לרשימת המיקומים הנתמכים - STAGING_BUCKET: ה-URI של הקטגוריה ב-Cloud Storage להכנה של Agent Runtime, לדוגמה
gs://my-staging-bucket. - USER_ID: מזהה של המשתמש, לדוגמה
user-123. - RUNTIME_NAME: שם המשאב של Agent Runtime הקיים של הסוכן, בפורמט
projects/.../locations/.../reasoningEngines/.... - MEMORY_BANK_ID: מזהה המכונה של Memory Bank, לדוגמה
456ב-projects/my-project/locations/us-central1/reasoningEngines/456.
Cloud Run
כדי לפרוס את הנציג ב-Cloud Run, פועלים לפי ההוראות במאמרי העזרה של ADK ומעבירים את המכונה של Memory Bank בתור שירות הזיכרון:
adk deploy cloud_run \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
מחליפים את MEMORY_BANK_ID במזהה המכונה של Memory Bank, לדוגמה 456. כדי לבדוק את הסוכן שנפרס, קראו את המסמכים בנושא פריסת ADK ב-Cloud Run.
Google Kubernetes Engine (GKE)
כדי לפרוס את הנציג ב-GKE, פועלים לפי המסמכים של ADK ומעבירים את המכונה של Memory Bank כשירות הזיכרון:
adk deploy gke \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
מחליפים את MEMORY_BANK_ID במזהה המכונה של Memory Bank, לדוגמה 456. כדי לבדוק את הסוכן שנפרס, קראו את הקטע בדיקת הסוכן במסמכי התיעוד של פריסת ADK ב-GKE.
ADK Web
ADK Web הוא ממשק דפדפן מקומי לבדיקה ולבחינה של הנציג במהלך הפיתוח.
ADK Web קורא את הפרויקט והמיקום שלכם ממשתני הסביבה. מריצים את הפקודות הבאות בטרמינל, מהספרייה שמכילה את תיקיית הנציג:
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_IDמחליפים את מה שכתוב בשדות הבאים:
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud , לדוגמה
my-project. - LOCATION: המיקום שלכם, לדוגמה
global. המיקומים שנתמכים ונקודות הקצה הגלובליות ובמספר אזורים של Memory Bank. - MEMORY_BANK_ID: מזהה המכונה של Memory Bank, לדוגמה
456.
ואז פותחים את http://localhost:8000 בדפדפן. כברירת מחדל, ADK Web מגדיר את מזהה המשתמש בתור user. כדי להשתמש במזהה משתמש אחר, מוסיפים את הפרמטר userId לשאילתה, לדוגמה http://localhost:8000?userId=USER_ID.
שימוש ב-Memory Bank במספר אזורים עם סביבת זמן ריצה אזורית
כברירת מחדל, כשמשתמשים בסביבת זמן ריצה עם Memory Bank מובנה, הסוכן ו-Memory Bank נפרסים באותו אזור. כדי לשמור על Memory Bank מרכזי אחד בפריסות אזוריות, אתם יכולים להתאים בין Memory Bank בכמה אזורים (כמו us) לבין סביבת זמן ריצה אזורית (כמו us-central1).
כדי להשתמש ב-Memory Bank במספר אזורים, צריך לשנות את ברירת המחדל של ה-builder של שירות הזיכרון ב-ADK, כך שיצביע על המיקום ומזהה המכונה במספר אזורים:
import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService
# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
project="PROJECT_ID",
location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]
# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="us",
agent_engine_id=memory_bank_id,
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
project="PROJECT_ID",
location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
מחליפים את מה שכתוב בשדות הבאים:
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud , לדוגמה
my-project. - STAGING_BUCKET: ה-URI של הקטגוריה ב-Cloud Storage להכנה של Agent Runtime, לדוגמה
gs://my-staging-bucket.
כדי למחוק את המשאבים האלה, צריך למחוק את סביבת זמן הריצה ואת המכונה בכמה אזורים.
אם מוחקים מופע מיד אחרי שיחה, יכול להיות שהבקשה תיכשל עם השגיאה FAILED_PRECONDITION בזמן שתהליך יצירת הזיכרון מסתיים. במקרה כזה, צריך להמתין דקה ולהפעיל שוב את המחיקה.
client_runtime.runtimes.delete(
name=runtime_instance.api_resource.name,
force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)