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

שימוש בסוכן של ערכת פיתוח סוכנים

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

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

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

אחזור מופע של סוכן

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

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

Agent Platform SDK

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

import vertexai

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

adk_app = client.agent_engines.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 תואם למחלקה AgentEngine שכוללת את המאפיינים הבאים:

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

בהמשך הקטע הזה נניח שיש לכם מכונת AgentEngine שנקראת 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 משתמש בסשנים מנוהלים מבוססי-ענן. בקטע הזה מוסבר איך משתמשים בסשנים מנוהלים.

יצירת סשן

כדי ליצור סשן למשתמש, משתמשים בשיטה 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.

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

כדי להציג את רשימת הסשנים של משתמש, משתמשים בשיטה 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.

קבלת סשן

כדי לקבל סשן ספציפי, משתמשים בשיטה 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.

מחיקת סשן

כדי למחוק סשן, משתמשים בשיטה 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"},}'

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

כדי להזרים תשובות מסוכן בסשן, משתמשים בשיטה 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 vertexai

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

response = client.agent_engines.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.agent_engines.check_query_job(
    name="JOB_NAME",
    config={
        "retrieve_result": True,
    },
)
print(response)

ביטול של עבודת שאילתה שפועלת במשך זמן רב

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

Agent Platform SDK

response = client.agent_engines.cancel_query_job(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    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"
}'

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

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

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

כדי לשמור בזיכרון מידע משמעותי מסשן (שאפשר להשתמש בו בסשנים עתידיים), משתמשים בשיטה 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 היא השאילתה שלפיה יתבצע חיפוש הדמיון.

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

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

אחזור מופע של סוכן

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

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

שימוש בסוכן של ערכת פיתוח סוכנים