בדף הזה מוסבר איך לחבר סוכן של ערכה לפיתוח סוכנים (ADK) למפגשים בפלטפורמת הסוכנים, ואיך להשתמש במפגשים מנוהלים בסביבה המקומית ובסביבת הייצור.
לפני שמתחילים
בהוראות האלה נעשה שימוש במבנה הבסיסי הבא של קובץ פרויקט להגדרת סוכן ADK וקוד הפריסה והרצת הסוכן:
my_agent/
agent.py # main agent code
runner.py # code for interacting with the agent
deploy.py # code for deploying the agent to Google Cloud
כדי לוודא שהסביבה שלכם מוגדרת, צריך לפעול לפי השלבים קבלת התפקידים הנדרשים ואימות במאמר הגדרת הסביבה.
הגדרה של משתני סביבה
כדי להשתמש ב-ADK, צריך להגדיר את משתני הסביבה:
import os
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
מחליפים את מה שכתוב בשדות הבאים:
- PROJECT_ID: מזהה הפרויקט.
- LOCATION: האזור שלכם. אזורים נתמכים לשיחות.
יצירת מופע של Agent Runtime
כדי לגשת להפעלות של Agent Platform, צריך קודם להשתמש במופע של Agent Runtime. כדי להתחיל להשתמש בסשנים, לא צריך לפרוס קוד. אם השתמשתם בעבר ב-Agent Runtime, יצירת מופע של Agent Runtime תיקח רק כמה שניות בלי פריסת קוד. אם זו הפעם הראשונה שאתם משתמשים ב-Agent Runtime, יכול להיות שייקח יותר זמן.
פרויקט ב-Google Cloud
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create(
config={
"display_name": "My Session Store",
}
)
# Print the runtime ID, you will need it in the later steps to initialize
# the ADK `VertexAiSessionService`.
print(remote_agent.api_resource.name.split("/")[-1])
מחליפים את מה שכתוב בשדות הבאים:
PROJECT_ID: מזהה הפרויקט.
LOCATION: האזור שלכם. אזורים נתמכים לשיחות.
פיתוח סוכן ADK
כדי ליצור סוכן ADK, פועלים לפי ההוראות במאמר ערכה לפיתוח סוכנים, או משתמשים בקוד הבא כדי ליצור סוכן שמברך משתמש עם ברכות קבועות. שומרים את הקוד הזה בקובץ בשם agent.py.
# file: my_agent/agent.py
from google import adk
def greetings(query: str):
"""Tool to greet user."""
if 'hello' in query.lower():
return {"greeting": "Hello, world"}
else:
return {"greeting": "Goodbye, world"}
# Define an ADK agent
root_agent = adk.Agent(
model="gemini-2.0-flash",
name='my_agent',
instruction="You are an Agent that greet users, always use greetings tool to respond.",
tools=[greetings]
)
הגדרת הכלי להרצת ADK
ADK Runtime מתזמר את ההפעלה של הסוכנים, הכלים והקריאות החוזרות, ומתזמר קריאות לקריאה ולכתיבה של סשנים. מאתחלים את Runner באמצעות VertexAiSessionService, שמתחבר לסשנים של Agent Platform. שומרים את הקוד הזה בקובץ בשם runner.py.
פרויקט ב-Google Cloud
# file: my_agent/runner.py
import agent # Import from your agent.py
from google.adk import Runner
from google.adk.sessions import VertexAiSessionService
from google.genai import types
app_name="APP_NAME"
user_id="USER_ID"
# Create the ADK runner with VertexAiSessionService
session_service = VertexAiSessionService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="AGENT_ENGINE_ID"
)
runner = Runner(
agent=agent.root_agent,
app_name=app_name,
session_service=session_service)
# Helper method to send query to the runner
async def call_agent(query, session_id, user_id):
content = types.Content(role='user', parts=[types.Part(text=query)])
async for event in runner.run_async(
user_id=user_id, session_id=session_id, new_message=content):
if event.is_final_response():
final_response = event.content.parts[0].text
print("Agent Response: ", final_response)
מחליפים את מה שכתוב בשדות הבאים:
APP_NAME: השם של אפליקציית הסוכן.
USER_ID: בוחרים מזהה משתמש משלכם, עד 128 תווים. לדוגמה,
user-123.AGENT_ENGINE_ID: מזהה המשאב של מופע Agent Runtime.
בסוכנים שפרסתם, מזהה המשאב מופיע כמשתנה הסביבה
GOOGLE_CLOUD_AGENT_ENGINE_ID.בסוכנים מקומיים, אפשר לאחזר את מזהה המשאב באמצעות
remote_agent.api_resource.name.split("/")[-1].
איך מתקשרים עם הסוכן
אחרי שמגדירים את הסוכן ומגדירים סשנים ב-Agent Platform, אפשר ליצור אינטראקציה עם הסוכן כדי לוודא שההיסטוריה והמצבים של הסשן נשמרים.
ממשק המשתמש של ADK
כדי לבדוק את הסוכן באמצעות ממשק המשתמש של ADK ולהתחבר לסשנים של Agent Platform, מריצים את הפקודה adk web בטרמינל.
בדרך כלל, adk web קורא משתני סביבה מקובץ .env, אבל הוא מתעלם מהקובץ הזה כשמשתמשים בדגל --session_service_uri. במקום זאת, צריך להגדיר את משתני הסביבה GOOGLE_CLOUD_PROJECT ו-GOOGLE_CLOUD_LOCATION בסשן הטרמינל לפני שמריצים את הפקודה.
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"export GOOGLE_CLOUD_LOCATION="LOCATION"adk web --session_service_uri=agentengine://AGENT_ENGINE_ID
# Sample output
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Python
שימוש בקוד ADK Python כדי לנהל סשנים ומצבים. כדי ליצור אינטראקציה עם הסוכן, מוסיפים את הקוד הבא לסוף הקובץ runner.py.
קטעי הקוד הבאים מכילים קריאות await ברמה העליונה, כדי לשמור על תמציתיות. כדי להריץ את הקוד הזה כסקריפט Python, צריך להציב את קטעי הקוד בתוך פונקציית async ולהשתמש ב-asyncio.run() כדי להריץ אותו, כמו בדוגמה הזו:
import asyncio
async def main():
# Place one or more snippets here.
# For example:
session = await session_service.create_session(
app_name=app_name,
user_id=user_id)
await call_agent("Hello!", session.id, user_id)
asyncio.run(main())
יצירת סשן ושליחת שאילתה לסוכן
אפשר להשתמש בקוד הבא כדי ליצור סשן ולשלוח שאילתה לסוכן. אפשר לציין מזהה סשן מותאם אישית כדי לארגן סשנים באמצעות תוכנית מתן שמות משלכם או כדי לעבור במהירות משירותים אחרים. אם לא מציינים מזהה סשן, Agent Platform יוצרת אותו באופן אוטומטי.
# file: my_agent/runner.py
# Create a session
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
session_id=session_id)
await call_agent("Hello!", session.id, user_id)
# Agent response: "Hello, world"
await call_agent("Thanks!", session.id, user_id)
# Agent response: "Goodbye, world"
אם משתמשים במזהי סשן בהתאמה אישית, חשוב להקפיד על ההגבלות הבאות כדי למנוע התנגשויות עם מזהים שנוצרו על ידי המערכת:
- אם התו הראשון הוא אות, המזהה יכול להיות באורך של עד 63 תווים. התווים התקפים הם אותיות קטנות, מספרים ומקפים (
[a-z0-9-]). התו האחרון חייב להיות אות או מספר. - אם התו הראשון הוא מספר, המזהה יכול להיות באורך של עד 9 תווים. התווים התקינים הם מספרים (
[0-9]) ללא אפסים מובילים.
אחרי שהסשן נוצר ומועבר ל-runner, ADK משתמש בסשן כדי לאחסן אירועים מהאינטראקציה הנוכחית. אפשר גם לחזור לסשן קודם על ידי הזנת המזהה של הסשן הזה.
הגדרת אורך החיים (TTL) של סשן
לכל הביקורים חייב להיות זמן תפוגה. אפשר להגדיר את מועד התפוגה הזה כשיוצרים או מעדכנים סשן. הסשן ואירועי הצאצא שלו נמחקים אוטומטית אחרי שפג תוקף הזמן. אפשר להגדיר את זמן התפוגה (expire_time) ישירות או להגדיר את אורך החיים (TTL) (ttl) בשניות. אם לא מציינים את שניהם, המערכת משתמשת ב-TTL של 365 ימים כברירת מחדל.
משך החיים (TTL)
אם מגדירים את אורך החיים (TTL), השרת מחשב את זמן התפוגה כ-create_time + ttl לסשנים שנוצרו לאחרונה או כ-update_time + ttl לסשנים שעודכנו.
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
# Session will be deleted 10 days after creation time.
ttl=f"{24 * 60 * 60 * 10}s"
)
```
מועד התפוגה
import datetime
expire_time = datetime.datetime.now(
tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10)
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
# Session will be deleted at the provided time (10 days after current time).
expire_time=expire_time.isoformat()
)
רשימת סשנים קיימים
רשימה של כל הביקורים הקיימים שמשויכים למזהה משתמש נתון.
# List sessions
sessions = await session_service.list_sessions(app_name=app_name,user_id=user_id)
print(sessions)
# ListSessionsResponse(session_ids=['1122334455', '9988776655'])
ניהול מצבי סשן
מצבים מכילים מידע שהסוכן צריך לשיחה. כשיוצרים סשן, אפשר לספק מצב התחלתי כמילון:
# Create a session with state
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
state={'key': 'value'})
print(session.state['key'])
# value
כדי לעדכן את מצב הסשן מחוץ למפעיל, מוסיפים אירוע חדש לסשן באמצעות state_delta:
# file: my_agent/runner.py
from google.adk.events import Event, EventActions
import time
# Define state changes
state_changes = {'key': 'new_value'}
# Create event with actions
actions_with_update = EventActions(state_delta=state_changes)
system_event = Event(
invocation_id="invocation_id",
author="system", # Or 'agent', 'tool' etc.
actions=actions_with_update,
timestamp=time.time()
)
# Append the event
await session_service.append_event(session, system_event)
# Check updated state
updated_session = await session_service.get_session(
app_name=app_name,
user_id=user_id,
session_id=session.id)
# State is updated to new value
print(updated_session.state['key'])
# new_value
שדות מותאמים אישית לאירועים
ערכת ה-ADK תומכת בסכימת אירועים גמישה, כך שתוכלו לכלול נתונים שרירותיים באירועים של סשנים. האפשרות הזו שימושית לצורך פעולה הדדית עם מסגרות אחרות של סוכנים או לאחסון נתוני אירועים בהתאמה אישית.
כשמוסיפים אירוע עם שדות מותאמים אישית, ה-ADK מבצע סריאליזציה של נתוני האירוע בשדה raw_event של אירוע הסשן המאוחסן.
# Create an event with custom fields
custom_event = Event(
invocation_id="invocation_id",
author="user",
timestamp=time.time(),
custom_field="custom_value",
another_field={"nested_key": "nested_value"}
)
# Append the event
await session_service.append_event(session, custom_event)
כשמאחזרים את הסשן, השדות המותאמים אישית האלה נשמרים באירועים שאוחזרו.
מחיקת סשן
מחיקה של סשן ספציפי שמשויך למזהה משתמש:
await session_service.delete_session(app_name=app_name, user_id=user_id, session_id=session.id)
פריסת הסוכן ב-Agent Platform
אחרי שבודקים את הסוכן באופן מקומי, אפשר לפרוס את הסוכן בסביבת הייצור על ידי עדכון המופע של Agent Platform עם הפרמטרים:
פרויקט ב-Google Cloud
client.runtimes.update(
resource_name=remote_agent.api_resource.name,
agent=AGENT,
config={
"display_name": DISPLAY_NAME, # Optional.
"requirements": REQUIREMENTS, # Optional.
"staging_bucket": STAGING_BUCKET, # Required.
},
)
מחליפים את מה שכתוב בשדות הבאים:
AGENT: האפליקציה שמטמיעה את ה-method
query / stream_query(לדוגמה,AdkAppעבור סוכן ADK).DISPLAY_NAME: שם ידידותי למשתמש של הסוכן.
REQUIREMENTS: רשימה של חבילות pip שנדרשות לסוכן. לדוגמה,
["google-cloud-storage", "google-cloud-agentplatform[runtimes,adk]"].STAGING_BUCKET: קטגוריה של Cloud Storage עם הקידומת
gs://.
הסרת המשאבים
כדי לנקות את כל המשאבים שנעשה בהם שימוש בפרויקט הזה, אפשר למחוק את מופע Agent Runtime יחד עם משאבי הצאצא שלו:
remote_agent.delete(force=True)