רישום וניהול של סוכני Dialogflow

תצוגה מקדימה

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בשלב טרום-GA, בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. אתם יכולים לקרוא מידע נוסף בקטע תיאור שלבי ההשקה.

בדף הזה מוסבר איך לרשום סוכני Dialogflow ולהשתמש בהם ב-Gemini Enterprise.

סקירה כללית

כדי להשתמש בנציג Dialogflow עם Gemini Enterprise, קודם צריך לפרוס את הנציג ואז לרשום אותו. כשרושמים את הסוכן ב-Dialogflow, מקשרים את הסוכן שנפרס ל-Gemini Enterprise כדי שהם יוכלו לתקשר.

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

לפני שרושמים את נציג Dialogflow, צריך לוודא שהשלבים הבאים הושלמו:

• פורסים את הנציג ב-Dialogflow. כדי לראות את לוח הבקרה של Dialogflow ושל סוכנים בממשק שיחה, עיינו במאמר סוכנים בממשק שיחה.

• התפקיד אדמין ב-Gemini Enterprise.

• מפעילים את Discovery Engine API. כדי להפעיל את Discovery Engine API בפרויקט ב- Google Cloud, נכנסים לדף Discovery Engine API במסוף Google Cloud .

  כניסה ל-Discovery Engine API

• יוצרים אפליקציית Gemini Enterprise. מידע נוסף זמין במאמר יצירת אפליקציה.

רישום סוכן Dialogflow ב-Gemini Enterprise

אתם יכולים לרשום את הסוכן של Dialogflow ב-Gemini Enterprise באמצעות מסוףGoogle Cloud או ה-API בארכיטקטורת REST. אחרי הרישום, הסוכן יהיה זמין למשתמשים באפליקציית Gemini Enterprise.

מכסת הרישום והרישוי של הנציגים: רישום של נציג באפליקציה צורך יחידה אחת ממכסת היצירה היומית של הנציגים בפרויקט (discoveryengine.googleapis.com/agents_tier_enterprise_regional). המכסה נקבעת לפי מספר הרישיונות ל-Gemini Enterprise Standard (יצירה אחת לכל משתמש ביום, במאגר) או ל-Plus (10 לכל משתמש ביום, במאגר) שמוקצים לפרויקט. רישיונות Frontline לא כוללים מכסה ליצירת פריטים.

אם אתם רושמים סוכן לקצה העורפי בכמה אפליקציות או מנועים של Gemini Enterprise באותו פרויקט, כל קריאה ל-API של הרישום (agents.create) נחשבת ליצירת סוכן במסגרת המכסה היומית הזו. סקריפטים של פריסה אוטומטית או צינורות עיבוד נתונים של CI/CD שרושמים סוכן בהרבה אפליקציות יכולים להיתקל בשגיאה HTTP 429 RESOURCE_EXHAUSTED: Agent creation quota exceeded אם מספר הקריאות לרישום ביום חורג ממספר הרישיונות הרגילים שהוקצו. לפני שאתם משיקים כמה אפליקציות, ודאו שהפרויקט שלכם כולל מספיק רישיונות Standard. פרטים נוספים זמינים במאמר מכסות יומיות ליצירת פרויקטים.

המסוף

כדי לרשום נציג Dialogflow באמצעות מסוף Google Cloud :

1. נכנסים לדף Gemini Enterprise במסוף Google Cloud .

   אל Gemini Enterprise

2. בוחרים את הפרויקט הרצוי.

3. לוחצים על שם האפליקציה שבה רוצים לרשום את הנציג.

4. לוחצים על נציגים > הוספת נציגים. מופיע החלון Choose an agent type.

5. בכרטיס Custom agent via Dialogflow, לוחצים על Add כדי לרשום את הסוכן של Dialogflow ב-Gemini Enterprise. החלונית Configuration נפתחת.

6. כדי להגדיר את הנציג:

   1. מזינים שם בשדה שם הנציג. הערך הזה מופיע ב-Gemini Enterprise בתור השם המוצג של הסוכן.

   2. בשדה תיאור הסוכן, מזינים תיאור. הערך הזה משמש את ה-LLM כדי לקבוע אם להפעיל את הנציג בתגובה לשאילתה של משתמש.

   3. בשדה Dialogflow agent source, מזינים את נתיב המשאב של הנציג ב-Dialogflow שרוצים לרשום ב-Gemini Enterprise.

      צריך להשתמש בפורמט הזה: projects/{project}/locations/{location}/agents/{agent}

      האפשרות זמינות הנציג, כשהיא נבחרת, מוגדרת כברירת מחדל.

   4. לוחצים על יצירה.

curl

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

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "icon": {
        "uri": "ICON_URI"
      },
      "dialogflowAgentDefinition": {
        "dialogflowAgent": "projects/DIALOGFLOW_PROJECT_ID/locations/DIALOGFLOW_LOCATION/agents/DIALOGFLOW_AGENT_ID"
      }
    }'

מחליפים את המשתנים בערכים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫APP_ID: המזהה של אפליקציית Gemini Enterprise.
• ‫DISPLAY_NAME: השם הידידותי למשתמש של הסוכן שמוצג ב-Gemini Enterprise.
• DESCRIPTION: הסבר קצר על מה שהסוכן עושה, שגלוי למשתמשים ב-Gemini Enterprise. לדוגמה, Extract key information from uploaded invoices for business travel.
• ‫ICON_URI: ה-URI הציבורי של סמל שמוצג לצד השם של נציג Dialogflow. אפשר גם לספק תמונה בקידוד Base64 ב-icon.content.
• ‫DIALOGFLOW_PROJECT_ID: מזהה הפרויקט ב- Google Cloud שמזהה את המיקום של הנציג ב-Dialogflow.
• ‫DIALOGFLOW_LOCATION: המיקום הגיאוגרפי הספציפי שבו מתארח הסוכן של Dialogflow, למשל global או us-central1.
• ‫DIALOGFLOW_AGENT_ID: המזהה הייחודי של הנציג ב-Dialogflow.

התגובה המוצלחת לפקודה הזו מחזירה את כל השדות של משאב הנציג החדש שנוצר ב-Dialogflow, כולל שם המשאב הייחודי שלו בשדה name. אפשר להשתמש בשם המשאב הזה לעדכונים או להפניות בעתיד.

רשימת הסוכנים שמחוברים לאפליקציה

בדוגמת הקוד הבאה אפשר לראות איך מקבלים את הפרטים של כל הנציגים שמחוברים לאפליקציה:

REST

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

מחליפים את המשתנים בערכים:

• ‫ENDPOINT_LOCATION: האזור המרובה לבקשת ה-API. מציינים אחד מהערכים הבאים:
  • ‫us לאזור הגיאוגרפי שכולל מספר אזורים בארה"ב
  • ‫eu למספר אזורים באיחוד האירופי
  • ‫global למיקום הגלובלי
  מידע נוסף זמין במאמר הגדרת מספר אזורים למאגר הנתונים.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: האזור של האפליקציה: global,‏ us או eu.
• ‫APP_ID: המזהה של אפליקציית Gemini Enterprise.

אם הנציג לא נוצר מראש על ידי Google, התשובה כוללת שדה name בשורות הראשונות. הערך של השדה הזה מכיל את מזהה הנציג בסוף הנתיב. לדוגמה, בתגובה הבאה, מזהה הנציג הוא 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

הצגת פרטים של נציג Dialogflow

בדוגמת הקוד הבאה אפשר לראות איך מאחזרים את הפרטים של סוכן שנרשם ב-Gemini Enterprise:

REST

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

מחליפים את המשתנים בערכים:

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

עדכון של נציג Dialogflow

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

• displayName
• description
• reasoning_engine

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

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

curl

  curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
  "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "icon": {
        "uri": "ICON_URI"
      },
      "dialogflowAgentDefinition": {
        "dialogflowAgent": "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/agents/DIALOGFLOW_AGENT_ID"
      }
    }'

מחליפים את המשתנים בערכים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫AGENT_RESOURCE_NAME: שם המשאב של רישום הנציג שרוצים לעדכן.
• ‫DISPLAY_NAME:השם המוצג של הנציג.
• ‫DESCRIPTION: תיאור הסוכן שמוצג ב-Gemini Enterprise. התיאור מיועד רק לשימוש המשתמש.
• ‫ICON_URI: ה-URI הציבורי של סמל שמוצג לצד השם של נציג Dialogflow. אפשר גם לספק תמונה בקידוד Base64 ב-icon.content.
• ‫REASONING_ENGINE_LOCATION: המיקום בענן של מנוע החשיבה הרציונלית שבו יוצרים את הסוכן.
• ‫DIALOGFLOW_AGENT_ID: המזהה הייחודי של הנציג ב-Dialogflow.

מחיקת נציג Dialogflow

דוגמת הקוד הבאה ממחישה איך אפשר למחוק נציג שמחובר לאפליקציה:

REST

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

מחליפים את המשתנים בערכים:

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

דוגמה לפקודה ולתוצאה

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}