הערה: חבילת המסמכים הזו מיועדת למהדורות Standard,‏ Plus,‏ תשלום לפי שימוש ו-Frontline של Gemini Enterprise. לעיון במסמכי התיעוד של מהדורת Business, אפשר להיכנס אל מרכז העזרה של Gemini Enterprise – מהדורת Business.

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

איך מתקשרים לסוכן ספציפי באמצעות 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, סוכני צ'אט של Workflow Builder (לשעבר "עם תכנות מינימלי") ותהליכי עבודה של Workflow Builder (ראו הפעלת תהליך עבודה)
הרשאת IAM נדרשת	`discoveryengine.assistants.assist`
היקף ההרשאות הנדרש של OAuth	`https://www.googleapis.com/auth/cloud-platform`

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

הפעל אתממשק API של מנוע גילוי (discoveryengine.googleapis.com ) ב שלך Google Cloud פּרוֹיֶקט.
מוודאים שלחשבון המשתמש או לחשבון השירות יש תפקיד שמעניק את הרשאת ה-IAM‏ discoveryengine.assistants.assist, כמו עריכה ב-Discovery Engine‏ (roles/discoveryengine.editor) או אדמין ב-Gemini Enterprise‏ (roles/discoveryengine.agentspaceAdmin).
מוודאים שאפליקציית Gemini Enterprise (מנוע) נוצרה ומכילה לפחות סוכן רשום אחד.
אם אתם מבצעים אימות באמצעות 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 בנקודת הקצה (endpoint) של 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 או workflowAgentDefinition).

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

קריאה לתהליך עבודה

כדי להפעיל תהליך עבודה ב-Workflow Builder, שולחים את אותה בקשה עם מזהה תהליך העבודה ב-agentsSpec.agentSpecs[].agentId. כל קריאה מתחילה הפעלה ידנית של תהליך העבודה.

הגרסה שפועלת: אם תהליך העבודה פורסם, הקריאה מפעילה את הגרסה שפורסמה. שינויים שנשמרו ב-Workflow Builder אבל עדיין לא פורסמו לא משפיעים על הגורמים שמבצעים קריאות ל-API עד שמפרסמים אותם. אם תהליך העבודה אף פעם לא פורסם, הקריאה מפעילה את הטיוטה שלו.
מי יכול להפעיל אותו: הבעלים והאדמינים של תהליך העבודה יכולים להפעיל אותו. משתמשים אחרים יכולים להפעיל תהליך עבודה שפורסם אחרי שהוא שותף איתם. רק הבעלים או אדמין יכולים לקרוא לתהליך עבודה שמעולם לא פורסם. קוראים אחרים מקבלים את השגיאה HTTP 403.
טריגרים: בתהליך העבודה חייב להיות טריגר ידני אחד בדיוק. הקריאות נכשלות בתהליך עבודה שמשלב טריגר ידני עם טריגר אחר, או שיש בו יותר מטריגר ידני אחד.
קלט: אי אפשר להגדיר את משתני הקלט של הטריגר הידני באמצעות streamAssist. אם לטריגר הידני יש קלט נדרש, ההפעלה נכשלת, גם אם לקלט יש ערך ברירת מחדל. הקלט האופציונלי ריק, וערכי ברירת המחדל לא מוחלים. טקסט השאילתה מועבר לצומתי ה-LLM של תהליך העבודה, כך שאפשר לכלול שם נתונים, אבל הוא לא ממלא משתני קלט.

מגבלות

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

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

פתרון בעיות

אתם יכולים להיעזר בטבלה הבאה כדי לפתור שגיאות נפוצות בהפעלה של streamAssist:

תיאור הבעיה	סיבה אפשרית	רזולוציה
שגיאת HTTP 404 כשמציגים את רשימת הנציגים	קריאה ל-`agents` בנקודת הקצה `v1` או `v1beta`.	במקום זאת, צריך לשלוח את בקשת הרשימה לנקודת הקצה (endpoint) של `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.
`HTTP 403` עם `Only the agent owner or an admin can run a draft of this agent.`	תהליך העבודה אף פעם לא פורסם, והמשתמש ששלח את הבקשה הוא לא הבעלים או האדמין שלו.	מפרסמים את תהליך העבודה ב-Workflow Builder ומשתפים אותו עם המתקשר.
`HTTP 403` עם `User does not have permission to access the Agent.`	תהליך העבודה לא משותף עם המתקשר.	משתפים את תהליך העבודה עם המתקשר.
תהליך העבודה מתנהג כמו גרסה ישנה יותר	השיחה מפעילה את הגרסה שפורסמה, ולא את השינויים שלא פורסמו ב-Workflow Builder.	מפרסמים את תהליך העבודה.
הקריאה לתהליך העבודה מסתיימת עם `answer.state` `FAILED` ושגיאת `INTERNAL`	בתהליך העבודה יש טריגר ידני וטריגר נוסף, או יותר מטריגר ידני אחד.	משאירים טריגר ידני אחד.