כלים ב-Playbook

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

אתם יכולים להשתמש בכלים מובְנים או ליצור כלים בהתאמה אישית לפי הצרכים שלכם.

בדיקת כלים

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

אתם יכולים להשתמש בתכונה לבדיקת כלים גם כשאתם מוסיפים כלי לדוגמה.

כלים מובנים

הכלים המובנים מתארחים ב-Google. אתם יכולים להפעיל את הכלים האלה בנציגים בלי להגדיר אותם ידנית.

הכלים המובנים שנתמכים הם:

  • Code Interpreter: כלי מאינטראקציה ישירה של Google שמשלב את היכולת ליצור קוד ולהריץ קוד, ומאפשר לבצע משימות שונות, כולל ניתוח נתונים, הצגת נתונים חזותית, עיבוד טקסט ופתרון משוואות או בעיות אופטימיזציה.

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

סכימה לדוגמה:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

כלי OpenAPI

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

כדי לבדוק אם הכלי מוגדר בצורה נכונה, אפשר להשתמש בתכונה "בדיקת הכלי" שזמינה בדף הכלי. התכונה הזו זמינה גם בתצוגת הדוגמה כשמוסיפים הפעלת כלי לדוגמה.

אפשר גם להפעיל כלי OpenAPI בצד הלקוח.

סכימה לדוגמה:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

אפשר להשתמש בהפניה לסכימה הפנימית @dialogflow/sessionId כסוג סכימה של פרמטר. בסוג הסכימה הזה, מזהה הסשן של Dialogflow CX בשיחה הנוכחית מסופק כערך פרמטר.

לדוגמה:

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

מגבלות על כלי OpenAPI

המגבלות הבאות חלות:

  • סוגי הפרמטרים הנתמכים הם path,‏ query ו-header. אין תמיכה בסוג הפרמטר cookie.
  • פרמטרים שמוגדרים על ידי סכימת OpenAPI תומכים בסוגי הנתונים הבאים: string,‏ number,‏ integer,‏ boolean ו-array. אין תמיכה בסוג object.
  • אי אפשר לציין פרמטרים של שאילתה בעורך הדוגמאות של המסוף.
  • גופי הבקשה והתגובה חייבים להיות ריקים או בפורמט application/json.

יצירת סכימה של כלי OpenAPI

כשמגדירים סכימה, לוחצים על Use Gemini כדי ליצור את הסכימה באמצעות AI גנרטיבי.

כדי ליצור את התמונה, צריך לספק את הפרטים הבאים:

  • כתובת URL של בקשה.
  • שיטת HTTP, כמו GET או POST.
  • קלט לדוגמה.
  • פלט לדוגמה.
  • פרומפט טקסטואלי שמתאר את הכלי.

אחרי שיוצרים את הסכימה, אפשר לערוך אותה לפי הצורך ולהוסיף עוד כתובות URL ושיטות באופן ידני.

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

כששולחים קריאה ל-API חיצוני, אפשר להשתמש באפשרויות האימות הבאות.

אימות של סוכן השירות ב-Dialogflow CX

‫Dialogflow CX יכול ליצור טוקן של מזהה באמצעות סוכן השירות של Dialogflow CX. הטוקן מתווסף לכותרת ה-HTTP של ההרשאה כש-Dialogflow CX קורא ל-API חיצוני.

אתם יכולים להשתמש בטוקן של מזהה כדי לגשת לפונקציות של Cloud Run ולשירותי Cloud Run אחרי שאתם מקצים את התפקידים roles/cloudfunctions.invoker ו-roles/run.invoker ל-service-agent-project-number@gcp-sa-dialogflow..

אם פונקציות Cloud Run ושירותי Cloud Run נמצאים באותו פרויקט משאבים, לא צריך הרשאות נוספות בממשק לניהול זהויות והרשאות גישה (IAM) כדי להפעיל אותם.

אימות של חשבון שירות

חשבונות שירות יכולים לאמת בקשות של כלים לכל ממשק Google API שתומך בכך.

אם עדיין לא עשיתם זאת, צרו חשבון שירות. מאחר שחשבונות שירות הם חשבונות משתמשים, אפשר להקצות להם תפקידים כדי לגשת למשאבים בפרויקט, בדיוק כמו שמקצים תפקידים לכל חשבון משתמש אחר. אתם יכולים להשתמש בכתובת האימייל של חשבון השירות כדי ליצור טוקן גישה, ולשלוח אותו בכותרת Authorization של הבקשה לכלי.

אם אתם מגדירים את הכלי לשימוש בחשבונות שירות, אתם צריכים את ההרשאות הבאות:

  • roles/iam.serviceAccountUser

כדי לאפשר ל-Dialogflow CX ליצור אסימונים, צריך לתת לסוכן השירות של Dialogflow CX את ההרשאות הבאות:

  • roles/iam.serviceAccountTokenCreator

לחשבון השירות צריכות להיות גם הרשאות גישה לשירות שמארח את הכלי.

אימות באמצעות מפתח API

  • כדי להגדיר אימות באמצעות מפתח API, אתם יכולים לספק את שם המפתח, מיקום הבקשה (כותרת או מחרוזת שאילתה) ומפתח API, כדי ש-Dialogflow CX יעביר את מפתח ה-API בבקשה.
  • מומלץ לספק את מפתח ה-API באמצעות Secret Manager.
  • אחרי 15 באוגוסט 2025, נציגים מיוצאים לא יכילו יותר מפתחות API של ערכים גולמיים.

OAuth

תהליך פרטי הכניסה של לקוח OAuth נתמך באימות בין שרתים:

  • אתם יכולים להשתמש בתהליך הזה אם הכלי לפיתוח אפליקציות AI גנרטיבי הוא הבעלים של המשאב, ואתם לא צריכים הרשאה ממשתמש הקצה.
  • צריך להגדיר את מזהה הלקוח, סוד הלקוח ונקודת הקצה של הטוקן מספק OAuth ב-Dialogflow CX.
  • מומלץ לספק את סוד הלקוח באמצעות Secret Manager. החל מ-15 באוגוסט 2025, נציגים מיוצאים לא יכילו סודות לקוח עם ערכים גולמיים.
  • מערכת Dialogflow CX מחליפה טוקן גישה של OAuth מספק OAuth ומעבירה אותו בכותרת ההרשאה של הבקשה.

טוקן למוכ"ז

  • אפשר להגדיר אימות Bearer כדי להעביר באופן דינמי את טוקן למוכ"ז מהלקוח. האסימון הזה נכלל בכותרת ההרשאה של הבקשה.
  • כשמגדירים אימות של כלי, אפשר להגדיר פרמטר של סשן שישמש כטוקן למוכ"ז. לדוגמה, משתמשים ב-$session.params.<parameter-name-for-token> כדי לציין את הטוקן.

  • בזמן הריצה, מקצים את הטוקן למוכ"ז לפרמטר של הסשן:

    DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

  • אם אתם צריכים להגדיר אסימון סטטי במקום לאחזר את האסימון מפרמטר של סשן, מומלץ לספק את האסימון באמצעות Secret Manager. אחרי 15 באוגוסט 2025, נציגים מיוצאים לא יכילו טוקנים למוכ"ז עם ערכים גולמיים.

אימות TLS בו-זמני (mTLS)

  • מידע נוסף זמין במאמר אימות TLS בו-זמני (mTLS).
  • יש תמיכה באישורי לקוח בהתאמה אישית. אפשר להגדיר אישורי לקוח ברמת הנציג בכרטיסייה Security בהגדרות הנציג.
  • האישור (בפורמט PEM) והמפתח הפרטי (בפורמט PEM) הם שדות חובה. אחרי שמגדירים את אישור הלקוח, הוא משמש במהלך Mutual TLS לכל הכלים וה-webhooks.

אישור CA בהתאמה אישית

אימות ב-Secret Manager

אם אתם משתמשים ב-OAuth, במפתח API או בטוקן למוכ"ז, אתם יכולים לאחסן את פרטי הכניסה כסודות באמצעות Secret Manager.

כדי לאמת את הכלי באמצעות סודות, פועלים לפי השלבים הבאים:

  1. אם עדיין אין לכם סוד, צרו סוד.
  2. נותנים לסוכן השירות של Dialogflow את התפקיד מנהל גישה לסודות ב-Secret Manager (roles/secretmanager.secretAccessor) בסוד החדש.
  3. מעתיקים את פרטי הכניסה ללוח.
  4. מוסיפים גרסה חדשה של סוד לסוד. מדביקים את פרטי הכניסה בתור ערך הסוד.
    • אל תכללו תו של שורה חדשה בסוף ערך הסוד.
  5. מעתיקים את השם של גרסת הסוד שהוספתם. פורמט השם הוא projects/{project_id}/secrets/{secret_id}/versions/{version_id}.
  6. פותחים את מסך העריכה של הכלי ואז:
    • אם אתם משתמשים ב-OAuth, בוחרים באפשרות OAuth בתור Authentication type, לוחצים על Secret version בקטע סוד לקוח ומדביקים את שם גרסת הסוד בתיבת הקלט Secret version.
    • אם משתמשים במפתח API, בוחרים באפשרות API key בתור Authentication type, ואז לוחצים על Secret version בקטע API key. מדביקים את שם הגרסה של הסוד בתיבת הקלט Secret version.
    • אם אתם משתמשים בטוקן למוכ"ז, בחרו באפשרות Bearer token בתור Authentication type, ואז לחצו על Secret version בקטע Bearer token. מדביקים את שם הגרסה של הסוד בתיבת הקלט Secret version.
  7. לוחצים על Save.

גישה לרשת פרטית של כלי OpenAPI

הכלי OpenAPI משתלב עם גישה לרשת פרטית של Service Directory כדי להתחבר ליעדי API ברשת ה-VPC שלכם. כך תנועת הנתונים נשארת ברשת Google Cloud , ומתבצעת אכיפה של IAM ושל VPC Service Controls.

כדי להגדיר כלי OpenAPI שמטרגט רשת פרטית:

  1. כדי להגדיר את רשת ה-VPC ואת נקודת הקצה של Service Directory, פועלים לפי ההוראות במאמר הגדרת רשת פרטית של Service Directory.
  2. מוודאים שחשבון השירות של Dialogflow CX Service Agent עם הכתובת הבאה קיים בפרויקט של הסוכן: 
    service-agent-project-number@gcp-sa-dialogflow.
     מקצים לחשבון השירות Dialogflow CX Service Agent את התפקידים הבאים ב-IAM:
    • ‫servicedirectory.viewer של הפרויקט ב-Service Directory
    • ‫servicedirectory.pscAuthorizedService של פרויקט הרשת
  3. כשיוצרים את הכלי, צריך לספק את שירות Service Directory יחד עם הסכימה של OpenAPI ופרטי אימות אופציונליים.

גישה לפרמטרים של סשן בכלי OpenAPI

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

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

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Breed of the pet.

אם אין פרמטרים כאלה לסשן, הקלט שנוצר על ידי ה-LLM מועבר לכלי.

ערכי ברירת המחדל של כלי OpenAPI

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

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

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Breed of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

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

כלים של מאגר הנתונים

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

כלי קישור

כלי קישור מאפשרים להגדיר סוכן שיבצע פעולות באמצעות החיבורים שהגדרתם ב-Integration Connectors. כל כלי מחבר מוגדר עם חיבור אחד ופעולה אחת או יותר. אתם יכולים ליצור כמה כלים לחיבור אחד כדי לקבץ פעולות שונות שהנציג יוכל להשתמש בהן.

כלי הקישור תומך בסוגי הקישורים הבאים:

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

יצירת חיבור

כדי ליצור חיבור ולקשר אותו לנציג, עוברים אל Tools > Create, בוחרים את סוג הכלי Connector ואת סוג המחבר הרצוי ולוחצים על Create Connection. הפעולה הזו פותחת את היצירה של Integration Connectors עם כמה שדות שמולאו מראש.

לחלופין, אתם יכולים לעבור אל Integration Connectors ולפעול לפי ההוראות ליצירת חיבור.

פעולות במחבר

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

  1. פעולות CRUD של ישויות:

    לכל חיבור יש ישויות שתואמות לאובייקטים של אותו מקור נתונים (ב-BigQuery אלה טבלאות, וב-Salesforce אלה אובייקטים כמו Order או Case).

    אפשר לבצע פעולות CRUD בכל ישות:

    • יצירה: מאמתת ויוצרת ישות עם ערכי שדות שצוינו.
    • רשימה: חיפוש מבוסס-מסנן של מופעי ישויות.
    • עדכון: שיטה מבוססת-מסנן לשינוי ערכי שדות של ישויות.
    • מחיקה: מחיקת ישות.
    • ‫Get: אחזור של ישות אחת באמצעות entityId.

    למידע נוסף על פעולות CRUD של ישויות, עיינו במסמכי התיעוד של המחברים.

  2. פעולות ספציפיות למחבר:

    הרבה מחברים תומכים בפעולה ExecuteCustomQuery, שמאפשרת להריץ שאילתת SQL על מקור הנתונים, שבה אפשר להפנות לכל אחת מהישויות של מקור הנתונים כטבלאות. למידע נוסף, עיינו ברשימת המחברים הנתמכים.

הפעולות הנוספות משתנות בהתאם לסוג המחבר. לדוגמה, עיינו בפעולות של מחבר ל-BigQuery או בפעולות של מחבר Salesforce.

הגדרת שדות קלט/פלט לפעולות CRUD

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

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

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

אימות

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

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

כלים לפונקציות

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

זה התהליך:

  1. קוד הלקוח שולח בקשה לזיהוי כוונה.
  2. הנציג מזהה שנדרש כלי פונקציה, והתגובה לזיהוי הכוונה מכילה את שם הכלי יחד עם ארגומנטים של קלט. הסשן הזה מושהה עד שמתקבלת בקשה נוספת לזיהוי כוונה עם תוצאת הכלי.
  3. קוד הלקוח מפעיל את הכלי.
  4. קוד הלקוח שולח בקשה נוספת לזיהוי כוונה, שמספקת את תוצאת הכלי כארגומנטים של פלט.

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

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

בדוגמה הבאה מוצגות הבקשה והתגובה הראשוניות לזיהוי כוונה באמצעות REST:

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

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

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

הפעלה בצד הלקוח

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

לדוגמה:

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}

זה התהליך:

  1. קוד הלקוח שולח בקשה לזיהוי כוונה שמציינת את ביצוע הלקוח.
  2. הנציג מזהה שנדרש כלי, והתגובה לזיהוי ה-Intent מכילה את שם הכלי יחד עם ארגומנטים של קלט. הסשן מושהה עד שמתקבלת בקשה נוספת לזיהוי כוונה עם תוצאת הכלי.
  3. קוד הלקוח מפעיל את הכלי.
  4. קוד הלקוח שולח בקשה נוספת לזיהוי כוונה, שמספקת את תוצאת הכלי כארגומנטים של פלט.
הקודם
פרמטרים של Playbook
הבא
הגדרות של Playbook