Tworzenie kroku

Z tego przewodnika dowiesz się, jak utworzyć krok, który użytkownicy mogą dodać do agenta w Google Workspace Studio.

Krok to pojedynczy etap w sekwencji zadań agenta. Kroki nie mogą uruchomić agenta.

Rozważmy na przykład krok, który wykonuje działania arytmetyczne. Prosi użytkownika o podanie 2 wartości i działania matematycznego. Następnie wykonuje działanie matematyczne na wartościach i zwraca wynik.

Użytkownik konfiguruje krok kalkulatora w ramach agenta.

Ilustracja 1. Użytkownik konfiguruje krok kalkulatora w ramach agenta.

Aby utworzyć krok, skonfiguruj go w pliku manifestu dodatku, napisz logikę aplikacji w kodzie dodatku do Google Workspace, a następnie wdróż i przetestuj krok.

Zdefiniuj krok

Aby skonfigurować krok, zdefiniuj go w pliku manifestu i napisz logikę aplikacji w kodzie.

Zdefiniuj krok w pliku manifestu

W pliku manifestu appsscript.json:

  1. Ustaw onConfigFunction i onExecuteFunction na nazwy odpowiednich funkcji w kodzie dodatku. W tym przykładzie funkcje mają nazwy onConfigCalculate() i onExecuteCalculate().
    • onConfigFunction konfiguruje krok. W razie potrzeby zbiera dane od użytkowników niezbędne do wykonania kroku, np. adres, na który ma zostać wysłany e-mail. W przykładzie w tym przewodniku prosimy o 2 wartości i działanie matematyczne.
    • onExecuteFunction wykonuje krok. Jeśli dane zostały zebrane od użytkowników, są przekazywane do tej funkcji. W odpowiednich przypadkach zwraca dane wyjściowe. W przykładzie w tym przewodniku zwraca wynik obliczeń matematycznych.

  2. Ustaw wymagane dane wejściowe i wyjściowe, aby krok mógł zbierać dane i wysyłać je do kolejnych kroków. W tym przykładzie poproś użytkownika o podanie 2 wartości i działania matematycznego zdefiniowanego w inputs[]. Wygeneruj obliczony wynik zgodnie z definicją w outputs[].

    Więcej informacji o danych wejściowych i wyjściowych znajdziesz w sekcjach Zmienne wejściowe i Zmienne wyjściowe. Aby mieć pewność, że agenci działają bez błędów, sprawdź zmienne wejściowe.

Oto plik manifestu dla kroku Kalkulator:

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"
          }
        }
      ]
    }
  }
}

Następnie napisz kod pomocniczy, definiując krok w kodzie.

Zdefiniuj krok w kodzie

W kodzie aplikacji wykonaj te czynności:

  1. Wpisz onConfigFunction, w tym przykładzie onConfigCalculate(). Gdy użytkownicy dodadzą krok do agenta, mogą skonfigurować jego aspekty w narzędziu do tworzenia agentów. Aby zebrać od użytkownika wymagane informacje, element onConfigFunction definiuje kartę konfiguracji.

    Karty to elementy składowe interfejsów użytkownika w dodatkach. Karty obsługują zdefiniowany układ, interaktywne elementy interfejsu, takie jak przyciski, oraz multimedia, np. obrazy. Karty umożliwiają uzyskiwanie od użytkownika danych potrzebnych do uruchomienia kroku, np. adresu e-mail do wysłania wiadomości.

    Funkcja OnConfigFunction zwraca kartę. Ta karta określa interfejs, w którym użytkownicy ustawiają dane kroku. W tym przykładzie onConfigFunction tworzy kartę, która prosi użytkownika o podanie 2 wartości i działania matematycznego.

  2. Wpisz onExecuteFunction o nazwie onExecuteCalculate(), jak w tym przykładzie. Gdy krok jest wykonywany na agencie, uruchamiana jest funkcja OnExecuteFunction. Wszystkie wartości wejściowe ustawione przez użytkownika podczas konfiguracji zgodnie z definicją w onConfigurationFunction są przekazywane do OnExecuteFunction.

    Napisz funkcję OnExecuteFunction(), która synchronicznie wykonuje zadanie przy użyciu podanych danych wejściowych. Pamiętaj, że OnExecuteFunction() musi zwrócić wszystkie dane wyjściowe zdefiniowane w pliku manifestu agenta, w przeciwnym razie wystąpi błąd.

Ten przykładowy kod zawiera funkcję pomocniczą outputVariables(), która tworzy i wysyła podane zmienne jako dane wyjściowe z kroku.

Krok jest gotowy do testowania.

Oto kod kroku Kalkulator:

Google 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);
}

Sprawdź swój krok

Aby przetestować krok, skonfiguruj wdrożenie testowe dodatku, dodaj krok do agenta, a następnie uruchom agenta.

  1. Skonfiguruj wdrożenie testowe dodatku:

    1. Otwórz projekt skryptu w edytorze Apps Script.
    2. Kliknij Wdrażanie > Testuj wdrożenia.
    3. Kliknij Zainstaluj.
    4. U dołu kliknij Gotowe.

    Możesz umożliwić innym użytkownikom testowanie dodatku, udostępniając projekt Apps Script na ich kontach (wymagane są uprawnienia do edycji). Następnie poproś użytkowników o wykonanie opisanych wcześniej czynności.

    Po zainstalowaniu dodatek jest natychmiast dostępny w usłudze Agenci. Przed pojawieniem się dodatku może być konieczne odświeżenie agentów. Przed użyciem dodatku musisz go też autoryzować.

    Więcej informacji o wdrażaniu testowym znajdziesz w artykule Instalowanie nieopublikowanego dodatku.

  2. Otwórz agentów.

  3. Utwórz agenta, który zawiera Twój krok:

    1. Kliknij Nowy agent.
    2. Wybierz sposób uruchamiania agenta. Podczas testowania kroku warto wybrać starter, który możesz uruchomić samodzielnie, np. wysyłając do siebie e-maila. Jeśli krok wymaga zmiennej wejściowej, skonfiguruj ją jako część danych wyjściowych startera.
    3. Kliknij Dodaj krok. Wybierz utworzony lub zaktualizowany krok o nazwie Oblicz.
    4. Skonfiguruj krok. W przypadku kroku obliczania wybierz 2 wartości i działanie matematyczne. Krok zostanie zapisany automatycznie.
    5. Aby przetestować dane wyjściowe kroku, dodaj kolejny krok. Aby na przykład dodać dane wyjściowe do e-maila, możesz dodać krok Wyślij wiadomość w Gmailu. W sekcji Wiadomość kliknij Zmienne i wybierz dane wyjściowe kroku. W przypadku kroku obliczania wybierz Zmienne > Krok 2. Obliczony wynik > Obliczony wynik. Zmienna pojawi się jako element w polu Wiadomość.
    6. Kliknij Włącz. Agent jest gotowy do uruchomienia.

  4. Uruchom agenta, włączając jego starter. Jeśli na przykład Twój agent uruchamia się po otrzymaniu e-maila, wyślij do siebie e-maila.

  5. Sprawdź, czy agent działa zgodnie z oczekiwaniami. Sprawdź dzienniki, otwierając kartę Aktywność w narzędziu do tworzenia agentów. Aby dowiedzieć się, jak tworzyć niestandardowe logi na karcie Aktywność, przeczytaj artykuł Dzienniki aktywności.