בניית שלב

במדריך הזה מוסבר איך ליצור שלב שמשתמשים יכולים להוסיף לסוכן בסטודיו של Google Workspace.

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

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

איור 1: משתמש מגדיר את שלב המחשבון כחלק מסוכן.

כדי ליצור שלב, צריך להגדיר אותו בקובץ המניפסט של התוסף, לכתוב את הלוגיקה של האפליקציה בקוד של התוסף ל-Google Workspace, ולפרוס ולבדוק את השלב.

הגדרת השלב

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

הגדרת השלב בקובץ המניפסט

בקובץ המניפסט, appsscript.json:

1. מגדירים את onConfigFunction ואת onExecuteFunction לשמות של הפונקציות המתאימות בקוד של התוסף. בדוגמה הזו, הפונקציות נקראות onConfigCalculate() ו-onExecuteCalculate().
   • הקוד onConfigFunction מגדיר את השלב. אם יש צורך בכך, המערכת אוספת נתונים מהמשתמשים שנדרשים לביצוע השלב, כמו הכתובת לשליחת אימייל. בדוגמה שבמדריך הזה, אנחנו מבקשים שני ערכים ופעולה מתמטית.
   • ‫onExecuteFunction מבצע את השלב. אם נאספו נתונים מהמשתמשים, הנתונים האלה מועברים לפונקציה הזו. אם רלוונטי, הפונקציה מחזירה פלט. בדוגמה של המדריך הזה, הפלט הוא התוצאה של חישוב מתמטי.

2. מגדירים את קלט ופלט נדרשים, כדי שהשלב יוכל לאסוף נתונים ולשלוח אותם לשלבים הבאים. בדוגמה הזו, מבקשים מהמשתמש שני ערכים ופעולה מתמטית שמוגדרת ב-inputs[]. תציג את התוצאה המחושבת כפי שמוגדר ב-outputs[].

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

זה קובץ המניפסט של שלב המחשבון:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

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

הגדרת השלב בקוד

בתוך קוד האפליקציה, מבצעים את הפעולות הבאות:

1. כותבים את onConfigFunction, שנקרא onConfigCalculate() בדוגמה הזו. כשמשתמשים מוסיפים את השלב לסוכן, הם יכולים להגדיר היבטים של השלב בכלי ליצירת סוכנים. כדי לאסוף את הפרטים הנדרשים מהמשתמש, onConfigFunction מגדיר כרטיס הגדרה.

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

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

2. כותבים את onExecuteFunction שנקרא onExecuteCalculate() בדוגמה הזו. כששלב מופעל בסוכן, הפונקציה OnExecuteFunction מופעלת. כל ערכי הקלט שהמשתמש הגדיר במהלך ההגדרה, כפי שמוגדר ב-onConfigurationFunction, מועברים אל OnExecuteFunction.

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

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

השלב מוכן לבדיקה.

הנה הקוד של שלב המחשבון:

Apps Script

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation.
 *
 * The input fields are configured to let the user select outputs from previous
 * steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
  .setFieldName("value1")
  .setTitle("First Value")
  .setHostAppDataSource(
    CardService.newHostAppDataSource()
      .setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
      )
  );
  const secondInput = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Second Value").setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );
  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation")
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  var card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

/**
* Returns output variables from a step.
*
* This function constructs an object that, when returned, sends the
* provided variable values as output from the current step.
* The variable values are logged to the console for debugging purposes.
*/
function outputVariables(variableDataMap) {
const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
  .setVariableDataMap(variableDataMap);

const hostAppAction = AddOnsResponseService.newHostAppAction()
  .setWorkflowAction(workflowAction);

const renderAction = AddOnsResponseService.newRenderActionBuilder()
  .setHostAppAction(hostAppAction)
  .build();

return renderAction;
}

/**
 * Executes the calculation step based on the inputs from a flow event.
 *
 * This function retrieves input values and the operation from the flow event,
 * performs the calculation, and returns the result as an output variable.
 * The function logs the event for debugging purposes.
 */
function onExecuteCalculate(event) {
  console.log("output: " + JSON.stringify(event));
  var calculatedValue = 0;
  var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
  var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
  var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];

  if (operation == "+") {
    calculatedValue = value1 + value2;
  } else if (operation == "-") {
    calculatedValue = value1 - value2;
  } else if (operation == "x") {
    calculatedValue = value1 * value2;
  } else if (operation == "/") {
    calculatedValue = value1 / value2;
  }

  const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };

  return outputVariables(variableDataMap);
}

בדיקת השלב

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

1. מגדירים פריסת בדיקה לתוסף:

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

   אתם יכולים לשתף את פרויקט Apps Script עם חשבון של משתמשים אחרים (נדרשת גישת עריכה) כדי לאפשר להם לבדוק את התוסף. לאחר מכן מבקשים מהמשתמשים לפעול לפי השלבים הקודמים.

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

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

2. פותחים את Agents (סוכנים).

3. יוצרים סוכן שכולל את השלב:

   1. לוחצים על New agent (סוכן חדש).
   2. בוחרים איך הסוכן יתחיל. כשבודקים שלב, מומלץ לבחור התחלה שאפשר להגדיר לבד, כמו שליחת אימייל לעצמכם. אם השלב דורש משתנה קלט, צריך להגדיר את משתנה הקלט כחלק מהפלט של ה-starter.
   3. לוחצים על הוספת שלב. בוחרים את השלב שיצרתם או עדכנתם, שנקרא חישוב.
   4. מגדירים את השלב. בשלב החישוב, בוחרים שני ערכים ופעולה מתמטית. השלב נשמר באופן אוטומטי.
   5. כדי לבדוק את הפלט של השלב, מוסיפים עוד שלב. לדוגמה, כדי להוסיף פלט להודעת אימייל, אפשר להוסיף את השלב שליחת הודעה של Gmail. בקטע הודעה, לוחצים על משתנים ובוחרים את הפלט של השלב. בשלב החישוב, בוחרים באפשרות משתנים > שלב 2: תוצאה מחושבת > תוצאה מחושבת. המשתנה מופיע כצ'יפ בשדה הודעה.
   6. לוחצים על הפעלה. הסוכן מוכן להפעלה.

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

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

נושאים קשורים

• משתני קלט
• אימות משתנה קלט
• משתני פלט
• הגדרת משאב בהתאמה אישית
• משתנים דינמיים
• רישום פעילות ושגיאות ביומן
• אובייקטים של אירועים ב-Workspace Studio