איך מתקשרים לסוכן ספציפי באמצעות StreamAssist API

כדי להתקשר לסוכן רשום ספציפי, צריך לספק את השדה האופציונלי agentsSpec בבקשת ה-API בארכיטקטורת REST של streamAssist או בקריאה לספריית הלקוח. ב-AgentsSpec API מוגדרת הספציפיקציה של הסוכנים שמשמשים לטיפול בבקשה. העוזר הדיגיטלי מנתב את השאילתות ישירות לסוכן הזה ושומר על הקשר של הסשן בין התורות.

בקצרה

מפרט פרטים
השיטה של ה-API projects.locations.collections.engines.assistants.streamAssist
גרסאות של נקודות קצה ‫v1alpha לאיתור מזהי סוכנים; v1 להתקשרות אל streamAssist
פרמטר מפתח agentsSpec.agentSpecs[].agentId
סוגי נציגים נתמכים סוכני צ'אט של Core Assistant,‏ Deep Research ו-כלי לתכנון סוכנים (לשעבר עם תכנות מינימלי)
הרשאת IAM נדרשת discoveryengine.assistants.assist
היקף הרשאות OAuth שנדרש https://www.googleapis.com/auth/cloud-platform

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

  1. מפעילים את Discovery Engine API ‏ (discoveryengine.googleapis.com) בפרויקט Google Cloud .
  2. מוודאים שלחשבון המשתמש או לחשבון השירות יש תפקיד שמעניק את הרשאת ה-IAM‏ discoveryengine.assistants.assist, כמו עריכה ב-Discovery Engine (roles/discoveryengine.editor) או אדמין של Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
  3. מוודאים שאפליקציית Gemini Enterprise (מנוע) נוצרה ומכילה לפחות סוכן רשום אחד.
  4. אם אתם מבצעים אימות באמצעות Application Default Credentials ‏ (ADC), ודאו שהלקוח שולח את כותרת הפרויקט לצורכי מכסה: -H "X-Goog-User-Project: PROJECT_ID".

איפה נמצא מזהה האפליקציה

כתובת ה-URL‏ streamAssist דורשת את מזהה המנוע והמיקום שלו (global,‏ us או eu). אם אתם יודעים רק את השם המוצג של האפליקציה, אתם יכולים לרשום את המנועים בפרויקט כדי לאתר את המזהה הבסיסי:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines"

בתשובה, הפורמט של המנוע name הוא projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. הפלח ENGINE_ID הוא APP_ID שנדרש בשיחה.

איך מוצאים את מזהה הסוכן

‫agentId הוא המקטע האחרון של השם המלא של משאב הסוכן ב-Discovery Engine API:

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{AGENT_ID}

סוכנים רשומים משתמשים במזהה מספרי ארוך (למשל 15492003793394502655) ולא בשם מוצג ידידותי. בבקשה שלך, עליך לציין רק את המחרוזת המספרית הסופית הזו {AGENT_ID}.

כדי לראות את רשימת הסוכנים שרשומים באפליקציה ולגלות את המזהים המספריים שלהם, מתקשרים אל אוסף agents בנקודת הקצה v1alpha:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

כל משאב של סוכן שמוחזר כולל את השדות הבאים:

  • ‫name: נתיב המשאב המלא שמסתיים ב-{AGENT_ID}.
  • ‫displayName: השם שקריא לאנשים ומוצג במסוף Google Cloud .
  • ‫state: המצב התפעולי (למשל ENABLED או PRIVATE).
  • אובייקט הגדרה שמציין את סוג הסוכן (למשל a2aAgentDefinition או lowCodeAgentDefinition).

לסכימת משאבי הסוכן המלאה, אפשר לעיין במאמרי העזרה של ה-API בארכיטקטורת REST agents.

שליחת שאילתות לנציגי תמיכה

כדי לשלוח שאילתות לסוכן ספציפי, צריך ליצור את הבקשה עם agentsSpec מתאים ולהריץ אותה באמצעות REST או ספריות לקוח.

מבנה גוף הבקשה

כדי להפנות שאילתה לסוכן ספציפי, צריך לכלול את אובייקט agentsSpec האופציונלי בגוף בקשת ה-POST:

{
  "query": {
    "text": "QUERY_TEXT"
  },
  "session": "SESSION_RESOURCE_NAME",
  "agentsSpec": {
    "agentSpecs": [
      {
        "agentId": "AGENT_ID"
      }
    ]
  }
}

הפניה לשדה

  • ‫agentsSpec (אובייקט, אופציונלי): הגדרה של סוכנים שמשמשים לטיפול בבקשה.
  • ‫agentsSpec.agentSpecs[] (מערך, אופציונלי): רשימה של הגדרות נציג. אפשר לציין כמה סוכנים במערך הזה.
  • ‫agentsSpec.agentSpecs[].agentId (מחרוזת, חובה במפרט): המזהה של משאב הסוכן הרשום. חייב להיות בהתאם ל-RFC-1034, עם אורך מקסימלי של 63 תווים.

סכימת הבקשה המלאה מופיעה במאמר streamAssist הפניית API ל-REST.

Call streamAssist

REST

הפקודה הבאה curl שולחת שאילתה לסוכן ספציפי באמצעות ה-API בארכיטקטורת REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "query": {
      "text": "List all contact cards."
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

מחליפים את ה-placeholders הבאים:

  • ‫LOCATION: האזור הרב-אזורי גם לשם המארח וגם לנתיב המשאב (global, ‏us או eu). אם האפליקציה נמצאת במיקום global, צריך להשמיט את קידומת המיקום משם המארח (discoveryengine.googleapis.com).
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫APP_ID: מזהה המנוע של Gemini Enterprise (מופיע במאמר איך מאתרים את מזהה האפליקציה והמיקום).
  • ‫AGENT_ID: מזהה הסוכן המספרי (כפי שמוסבר במאמר איפה מוצאים את מזהה הסוכן).

Python

בדוגמה הזו של Python מתבצעת קריאה ל-streamAssist באמצעות ספריית הלקוח google-cloud-discoveryengine:

# Install library: pip install google-cloud-discoveryengine
from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Replace placeholder values with your project and agent details.
project_id = "PROJECT_ID"
location = "LOCATION"          # For example: "us", "eu", or "global"
engine_id = "APP_ID"
agent_id = "AGENT_ID"          # The numeric agent ID
query_text = "List all contact cards."

client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)
client = discoveryengine.AssistantServiceClient(client_options=client_options)

assistant_path = client.assistant_path(
    project=project_id,
    location=location,
    collection="default_collection",
    engine=engine_id,
    assistant="default_assistant",
)

request = discoveryengine.StreamAssistRequest(
    name=assistant_path,
    query=discoveryengine.Query(text=query_text),
    agents_spec=discoveryengine.StreamAssistRequest.AgentsSpec(
        agent_specs=[
            discoveryengine.StreamAssistRequest.AgentsSpec.AgentSpec(
                agent_id=agent_id,
            )
        ]
    ),
)

for response in client.stream_assist(request=request):
    for reply in response.answer.replies:
        # Filter out model reasoning fragments (thought: true)
        if hasattr(reply, "grounded_content") and reply.grounded_content.content:
            print(reply.grounded_content.content.text, end="", flush=True)

print()

הסבר על התשובה שמתקבלת בסטרימינג

נקודת הקצה streamAssist מחזירה זרם של נתחי JSON דרך REST, או איטרטור של אובייקטים של תגובה בספריות לקוח:

  • טקסט התשובה: טקסט התשובה מגיע בהדרגה ב-answer.replies[].groundedContent.content.text. כדי לשחזר את התשובה המלאה, צריך לשרשר את קטעי הטקסט האלה לפי סדר הקבלה.
  • קטעי חשיבה רציונלית: קטעים שמסומנים בסמל "thought": true מייצגים את תהליך החשיבה הרציונלית הפנימי של המודל. צריך לסנן את הקטעים האלה כשמציגים את הפלט הסופי למשתמשי הקצה.
  • מצב ההרצה: הערך בשדה answer.state משתנה מ-IN_PROGRESS למצב סיום:
    • ‫SUCCEEDED: הבקשה הושלמה ונוצרה תשובה.
    • ‫SKIPPED: השאילתה התעלמה או עקפה. בודקים את assistSkippedReasons לפרטים (למשל, NON_ASSIST_SEEKING_QUERY_IGNORED לברכות קצרות).
    • ‫FAILED: הייתה שגיאת הרצה בהפעלה.
  • המשכיות של הסשן: הנתח האחרון כולל את sessionInfo.session (שם משאב הסשן) ואת assistToken.

המשך השיחה באותו סשן

כדי לשמור על ההקשר בין התורות, צריך להעביר את המחרוזת session מ-sessionInfo בבקשות הבאות:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "session": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
    "query": {
      "text": "Who is John Doe?"
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

אם משמיטים את השדה session או מציינים את הערך - כמזהה הסשן, ה-API יוצר באופן אוטומטי סשן חדש ומבודד.

מגבלות

המגבלות הבאות חלות כשמתקשרים לסוכנים באמצעות streamAssist:

  • סוגי סוכנים שלא נתמכים:
    • סוכני תהליכי עבודה לא אפשריים.
    • אין תמיכה בסוכני A2A או ADK שנרשמו לאפליקציית Gemini Enterprise דרך streamAssist. כדי להפעיל סוכן A2A ישירות באמצעות נקודת הקצה שלו ב-Registry, אפשר לעיין במאמר הפעלת סוכן באמצעות נקודת הקצה שלו ב-Registry A2A.
  • פעולות שינוי: ה-streamAssist API מותאם לשאילתות שיחה ולאחזור לקריאה בלבד דרך מחברים. אין תמיכה בהפעלה פרוגרמטית של כלים ופעולות שמשנים את המצב (כמו טיוטת אימייל, יצירת אירוע ביומן או שליחת הודעות בצ'אט) באמצעות streamAssist. ניסיון להפעיל תהליך עבודה של סוכן שמבצע פעולות משנות עלול לגרום לכשלים שקטים או ללולאות ביצוע לא מבוססות.

פתרון בעיות

בטבלה הבאה מפורטות שגיאות נפוצות בהפעלת streamAssist:

תיאור הבעיה הסיבה הנפוצה רזולוציה
שגיאת HTTP 404 כשמציגים רשימה של סוכנים מתבצע חיוג אל agents בנקודת הקצה v1 או v1beta. במקום זאת, שולחים את בקשת הרשימה לנקודת הקצה v1alpha.
התשובה נראית כללית למרות שהוגדרה agentsSpec הערך המספרי agentId לא תקין, או שהשאילתה כללית מדי ולא מפעילה התנהגות של דומיין. מאשרים את המזהה המספרי המדויק מv1alphaרשימת הסוכנים, שולחים שאילתה ספציפית לדומיין ובודקים אם יש בטקסט התשובה ניסוח ספציפי לסוכן.
לא הוחזרה שגיאה, אבל סוכן היעד לא פעל הפורמט של agentId היה שגוי, ולכן המערכת חזרה אוטומטית לתיאום ברירת המחדל. מוודאים שהמספר agentId מכיל ספרות בלבד ושהוא תואם בדיוק למזהה מרשימת הרישום.
החזרת מצב התגובה SKIPPED הקלט הוערך כשאילתה שלא קשורה לבקשת עזרה (למשל, ברכה קצרה). שולחים שאילתת משימה מהותית; בודקים את assistSkippedReasons במטען הייעודי (payload) של התשובה.
HTTP 401 או HTTP 403 Permission Denied חסר היקף OAuth, תפקיד IAM לא מספיק או כותרת פרויקט מכסה חסרה. צריך לוודא שלמתקשר יש discoveryengine.assistants.assist, שהיקף ה-OAuth כולל cloud-platform, ולהוסיף -H "X-Goog-User-Project: PROJECT_ID" אם משתמשים ב-ADC.

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