‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שימוש בסוכן ADK

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

במדריך הזה אנחנו יוצאים מנקודת הנחה שקראתם וביצעתם את ההוראות במאמרים הבאים:

יצירת סוכן באמצעות הערכה לפיתוח סוכנים (ADK): כדי ליצור את agent כמכונה של AdkApp.
אימות משתמשים כדי לאמת את המשתמש ששולח שאילתות לנציג.
מייבאים ומפעילים את ה-SDK כדי להפעיל את הלקוח ולקבל מכונה שנפרסה (אם צריך).

קבלת מופע של סוכן

כדי לשלוח שאילתה ל-AdkApp, קודם צריך ליצור מכונה חדשה או לקבל מכונה קיימת.

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

Agent Platform SDK

מריצים את הקוד הבא:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

adk_app = client.runtimes.get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

print(adk_app)

כאשר

‫PROJECT_ID הוא Google Cloud מזהה הפרויקט שבו יוצרים ופורסים סוכנים,
‫LOCATION הוא אחד מהאזורים הנתמכים, וגם
‫RESOURCE_ID הוא המזהה של הנציג שנפרס כמשאב reasoningEngine.

ספריית הבקשות של Python

מריצים את הקוד הבא:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
)

‫API בארכיטקטורת REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

כשמשתמשים ב-Agent Platform SDK, האובייקט adk_app תואם לכיתה AgentRuntime שמכילה את הפרטים הבאים:

‫adk_app.api_resource עם מידע על הנציג שנפרס. אפשר גם להפעיל את adk_app.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי adk_app. פרטים נוספים זמינים בקטע פעולות נתמכות.
adk_app.api_client שמאפשרת אינטראקציות סינכרוניות בין שירותים
‫adk_app.async_api_client שמאפשר אינטראקציות אסינכרוניות עם שירותים

בהמשך החלק הזה נניח שיש לכם מכונה של AgentRuntime בשם adk_app.

פעולות נתמכות

אפשר לבצע את הפעולות הבאות ב-AdkApp:

‫async_stream_query: להצגת תשובה לשאילתה באופן שוטף.
‫async_create_session: ליצירת סשן חדש.
‫async_list_sessions: כדי להציג את הסשנים הזמינים.
‫async_get_session: לאחזור סשן ספציפי.
‫async_delete_session: כדי למחוק סשן ספציפי.
‫async_add_session_to_memory: ליצירת זיכרונות מסשן.
‫async_search_memory: לאחזור זיכרונות.

כדי להציג את כל הפעולות הנתמכות:

Agent Platform SDK

מריצים את הקוד הבא:

adk_app.operation_schemas()

ספריית הבקשות של Python

מריצים את הקוד הבא:

import json

json.loads(response.content).get("spec").get("classMethods")

‫API בארכיטקטורת REST

מיוצג ב-spec.class_methods מהתגובה לבקשת ה-curl.

פעולות לסשנים

אחרי שפורסים את הסוכן ב-Agent Platform, ‏AdkApp משתמש בסשנים מנוהלים מבוססי-ענן. בקטע הזה מוסבר איך להשתמש בסשנים מנוהלים.

יצירת סשן

כדי ליצור סשן למשתמש, משתמשים ב-method‏ AdkApp.async_create_session:

Agent Platform SDK

session = await adk_app.async_create_session(user_id="USER_ID")

print(session)

ספריית הבקשות של Python

מריצים את הקוד הבא:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_create_session",
    "input": {"user_id": "USER_ID"},
  }),
)
print(response.content)

‫API בארכיטקטורת REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_create_session", "input": {"user_id": "USER_ID"},}'

‫USER_ID: בוחרים מזהה משתמש משלכם עם מגבלת תווים של 128. לדוגמה, user-123.

הסשן נוצר כייצוג מילוני של אובייקט סשן של ADK.

הצגת רשימת סשנים

כדי להציג את הסשנים של משתמש, משתמשים ב-method‏ AdkApp.async_list_sessions:

Agent Platform SDK

response = await adk_app.async_list_sessions(user_id="USER_ID"):
for session in response.sessions:
    print(session)

ספריית הבקשות של Python

מריצים את הקוד הבא:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_list_sessions",
    "input": {"user_id": "USER_ID"},
  }),
)
print(response.content)

‫API בארכיטקטורת REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_list_sessions", "input": {"user_id": "USER_ID"},}'

כאשר USER_ID הוא מזהה המשתמש שהגדרתם. לדוגמה, user-123.

אם מוחזרים סשנים, הם משתמשים בפורמט המילון של אובייקט סשן של ADK.

איך מתחילים סשן

כדי לקבל סשן ספציפי, משתמשים ב-method‏ AdkApp.async_get_session:

Agent Platform SDK

session = await adk_app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")

print(session)

ספריית הבקשות של Python

מריצים את הקוד הבא:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_get_session",
    "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},
  }),
)
print(response.content)

‫API בארכיטקטורת REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_get_session", "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},}'

השדה session הוא ייצוג המילון של אובייקט סשן של ADK.

איך מוחקים סשן

כדי למחוק סשן, משתמשים ב-method‏ AdkApp.async_delete_session:

Agent Platform SDK

await adk_app.async_delete_session(user_id="USER_ID", session_id="SESSION_ID")

ספריית הבקשות של Python

מריצים את הקוד הבא:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_delete_session",
    "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},
  }),
)
print(response.content)

‫API בארכיטקטורת REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_delete_session", "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},}'

הזרמת תשובה לשאילתה

כדי להעביר תשובות בסטרימינג מסוכן בסשן, משתמשים ב-method‏ AdkApp.async_stream_query:

Agent Platform SDK

async for event in adk_app.async_stream_query(
    user_id="USER_ID",
    #session_id="SESSION_ID",  # Optional
    message="What is the exchange rate from US dollars to SEK today?",
):
  print(event)

ספריית הבקשות של Python

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

requests.post(
    f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:streamQuery",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {get_identity_token()}",
    },
    data=json.dumps({
        "class_method": "async_stream_query",
        "input": {
            "user_id": "USER_ID",
            #"session_id": "SESSION_ID",
            "message": "What is the exchange rate from US dollars to SEK today?",
        },
    }),
    stream=True,
)

‫API בארכיטקטורת REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:streamQuery?alt=sse -d '{
  "class_method": "async_stream_query",
  "input": {
    "user_id": "USER_ID",
    #"session_id": "SESSION_ID",
    "message": "What is the exchange rate from US dollars to SEK today?",
  }
}'

אם אתם משתמשים ב-Agent Platform SDK, אתם אמורים לקבל את המשך השיחה, כמו רצף המילונים הבא:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'bOPHtzji',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': '9AoDFmiL',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 1 USD to 9.6607 SEK.'}],
             'role': 'model'},
 'id': 'hmle7trT',
 # ...
}

משימות של שאילתות ממושכות

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

פריסת נציג לשאילתה אסינכרונית

כדי לפרוס סוכן, פועלים לפי ההוראות הכלליות שמפורטות במאמר פריסת סוכן. בפריסה שמבוססת על מקור, מגדירים את השדה deploymentSpec.agentFramework לערך google-adk.

אם אתם משתמשים בנקודת קצה מותאמת אישית ל-API על ידי יצירת קובץ אימג' משלכם של קונטיינר, אתם צריכים להוסיף את משתני הסביבה הבאים כשאתם יוצרים את הנציג באמצעות ה-SDK:

"env_vars" = {
    "API_ENDPOINT_PREFIX": "/api/myendpoint"
}

התחלת משימת שאילתה ממושכת

כתנאי מוקדם, צריך להקצות לסוכן השירות service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com את התפקיד roles/storage.objectCreator בקטגוריית האחסון של קובצי הפלט.

כדי להתחיל משימת שאילתה ארוכה:

Agent Platform SDK

import agentplatform

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

response = client.runtimes.run_query_job(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "query": '{"input":{"user_id":"USER_ID", "message":"What is the exchange rate from US dollars to SEK today?"}}',
        "output_gcs_uri": "gs://GCS_BUCKET_NAME/OUTPUT_FILE",
    },
)
print(response)

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

REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:asyncQuery -d \
'{
  "input_gcs_uri": "gs://GCS_BUCKET_NAME/INPUT_FILE",
  "output_gcs_uri": "gs://GCS_BUCKET_NAME/OUTPUT_FILE"
}'

בקריאה ל-API בארכיטקטורת REST, השדה input_gcs_uri צריך להפנות לקובץ שמכיל את השאילתה. תוכן הקובץ חייב להיות אובייקט JSON עם שדה input שתואם לשדה input של QueryReasoningEngineRequest (למשל { "input": { "user_id": "hello", "message":"$QUERY"} }). אם קובץ הקלט הזה נמצא בקטגוריה שונה ממיקום הפלט, צריך גם להקצות לסוכן השירות service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com את התפקיד roles/storage.objectReader בקטגוריית האחסון שבה נמצאים קובצי הקלט.

הערך output_gcs_uri חייב להיות שם קובץ.

בדיקת הסטטוס של משימת שאילתה ממושכת

כדי לבדוק את הסטטוס של משימת שאילתה ממושכת ולקבל את התוצאות שלה:

Agent Platform SDK

response = client.runtimes.check_query_job(
    name="JOB_NAME",
    config={
        "retrieve_result": True,
    },
)
print(response)

ביטול משימת שאילתה ארוכה

כדי לבטל משימת שאילתה ממושכת, צריך את שם המשאב של ה-LRO שמוחזר ממשימת השאילתה הממושכת.

Agent Platform SDK

response = client.runtimes.cancel_query_job(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "operation_name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
    },
)

REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:cancelAsyncQuery -d \
'{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
  "operation_name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
}'

הביטול הוא אסינכרוני. בקשת הביטול חוזרת ברגע שהיא מתקבלת, אבל המשימה יכולה להמשיך לדווח על סטטוס של RUNNING מ-check_query_job עד שהעבודה שכבר מתבצעת, כמו קריאה לכלי חסימה, מסתיימת.

אחרי שהמשימה מבוטלת, הפעולה שלה מסתיימת עם קוד השגיאה 1 (CANCELLED) וההודעה Cancelled by user.. שימו לב ש-check_query_job מדווח על כל פעולה שהסתיימה עם שגיאה כסטטוס FAILED, כך שמשימה שבוטלה מדווחת כ-FAILED ולא באמצעות סטטוס ביטול נפרד. בודקים את קוד השגיאה כדי להבחין בין ביטול לבין כשל אמיתי.

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

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

הוספת הסשן לזיכרון

כדי לשמור בזיכרון מידע משמעותי מסשן מסוים (שאפשר להשתמש בו בסשנים עתידיים), משתמשים ב-method‏ async_add_session_to_memory:

Agent Platform SDK

await adk_app.async_add_session_to_memory(session="SESSION_DICT")

כאשר SESSION_DICT הוא פורמט המילון של אובייקט סשן ADK.

חיפוש בזיכרונות

כדי לחפש בזיכרונות של הנציג, אפשר להשתמש ב-method‏ async_search_memory:

Agent Platform SDK

response = await adk_app.async_search_memory(
    user_id="USER_ID",
    query="QUERY",
)
print(response)

כאשר

‫USER_ID הוא ההיקף של הזיכרונות הרלוונטיים.
‫QUERY היא השאילתה שרוצים לבצע בה חיפוש דמיון.

שימוש בסוכן ADK קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

קבלת מופע של סוכן

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

פעולות נתמכות

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

פעולות לסשנים

יצירת סשן

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

הצגת רשימת סשנים

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

איך מתחילים סשן

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

איך מוחקים סשן

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

הזרמת תשובה לשאילתה

Agent Platform SDK

ספריית הבקשות של Python

‫API בארכיטקטורת REST

משימות של שאילתות ממושכות

פריסת נציג לשאילתה אסינכרונית

התחלת משימת שאילתה ממושכת

Agent Platform SDK

REST

בדיקת הסטטוס של משימת שאילתה ממושכת

Agent Platform SDK

ביטול משימת שאילתה ארוכה

Agent Platform SDK

REST

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

הוספת הסשן לזיכרון

Agent Platform SDK

חיפוש בזיכרונות

Agent Platform SDK

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

שימוש בסוכן ADK