Creare un passaggio

Questa guida spiega come creare un passaggio che gli utenti possono aggiungere a un agente in Google Workspace Studio.

Un passaggio è un singolo passaggio nella sequenza di attività di un agente. I passaggi non possono avviare un agente.

Ad esempio, considera un passaggio che esegue operazioni aritmetiche. Chiede all'utente due valori e un'operazione matematica. Quindi esegue l'operazione matematica sui valori e restituisce il risultato.

Un utente configura il passaggio del calcolatore come parte di un agente.

Figura 1: un utente configura il passaggio del calcolatore come parte di un agente.

Per creare un passaggio, configuralo nel file manifest del componente aggiuntivo, scrivi la logica dell'applicazione nel codice del componente aggiuntivo di Google Workspace e implementa e testa il passaggio.

Definisci il passaggio

Per configurare un passaggio, definiscilo nel file manifest e scrivi la relativa logica dell'applicazione nel codice.

Definisci il passaggio nel file manifest

Nel file manifest, appsscript.json:

  1. Imposta onConfigFunction e onExecuteFunction sui nomi delle funzioni corrispondenti nel codice del componente aggiuntivo. In questo esempio, le funzioni vengono chiamate onConfigCalculate() e onExecuteCalculate().
    • onConfigFunction configura il passaggio. Se necessario, raccoglie i dati degli utenti necessari per eseguire il passaggio, ad esempio l'indirizzo a cui inviare un'email. Nell'esempio di questa guida, chiediamo due valori e un'operazione matematica.
    • onExecuteFunction esegue il passaggio. Se i dati sono stati raccolti dagli utenti, vengono passati a questa funzione. Se applicabile, restituisce un output. Nell'esempio di questa guida, restituisce il risultato di un calcolo matematico.

  2. Imposta input e output richiesti, in modo che il passaggio possa raccogliere i dati e inviarli ai passaggi successivi. In questo esempio, chiedi all'utente due valori e un'operazione matematica definita in inputs[]. Restituisci il risultato calcolato come definito in outputs[].

    Per saperne di più su input e output, consulta Variabili di input e Variabili di output. Per assicurarti che gli agenti vengano eseguiti senza errori, convalida le variabili di input.

Ecco il file manifest per il passaggio Calcolatore:

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

Successivamente, scrivi il codice di supporto definendo il passaggio nel codice.

Definisci il passaggio nel codice

Nel codice dell'applicazione:

  1. Scrivi onConfigFunction, denominato onConfigCalculate() in questo esempio. Quando gli utenti aggiungono il passaggio a un agente, possono configurare gli aspetti del passaggio nel generatore di agenti. Per raccogliere le informazioni richieste dall'utente, onConfigFunction definisce una scheda di configurazione.

    Le schede sono gli elementi di base per le interfacce utente nei componenti aggiuntivi. Le schede supportano un layout definito, elementi UI interattivi come pulsanti e contenuti multimediali avanzati come immagini. Le schede ti consentono di ottenere da un utente i dati necessari per l'esecuzione del passaggio, ad esempio un indirizzo email per l'invio di un'email.

    OnConfigFunction restituisce una carta. Questa scheda definisce l'interfaccia utente in cui gli utenti impostano i dati del passaggio. In questo esempio, onConfigFunction crea una scheda che chiede all'utente due valori e un'operazione matematica.

  2. Scrivi onExecuteFunction denominato onExecuteCalculate() in questo esempio. Quando il passaggio viene eseguito in un agente, viene eseguito OnExecuteFunction. Qualsiasi valore di input impostato dall'utente durante la configurazione, come definito in onConfigurationFunction, viene passato a OnExecuteFunction.

    Scrivi OnExecuteFunction() in modo che esegua in modo sincrono la sua attività utilizzando gli input forniti. Ricorda che OnExecuteFunction() deve restituire tutti gli output definiti nel manifest dell'agente, altrimenti si verifica un errore.

Questo esempio di codice include una funzione di supporto, outputVariables(), che costruisce e invia le variabili fornite come output del passaggio.

Il passaggio è pronto per il test.

Ecco il codice per il passaggio Calcolatore:

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

Testare il passo

Per testare il passaggio, configura un deployment di test per il componente aggiuntivo, aggiungi il passaggio a un agente e poi esegui l'agente.

  1. Configura un deployment di test per il componente aggiuntivo:

    1. Apri il progetto di script nell'editor di Apps Script.
    2. Fai clic su Deployment > Verifica deployment.
    3. Fai clic su Installa.
    4. In basso, fai clic su Fine.

    Puoi consentire ad altri utenti di testare il componente aggiuntivo condividendo il progetto Apps Script con il loro account (è richiesto l'accesso in modifica). Quindi, chiedi agli utenti di seguire i passaggi precedenti.

    Una volta installato, il componente aggiuntivo è immediatamente disponibile in Agenti. Potresti dover aggiornare gli agenti prima che venga visualizzato il componente aggiuntivo. Devi anche autorizzare il componente aggiuntivo prima di utilizzarlo.

    Per scoprire di più sui deployment di test, consulta Installare un componente aggiuntivo non pubblicato.

  2. Apri Agenti.

  3. Crea un agente che includa il passaggio:

    1. Fai clic su Nuovo agente.
    2. Seleziona come si avvia l'agente. Quando testi un passaggio, è consigliabile scegliere un trigger che puoi attivare tu stesso, ad esempio inviandoti un'email. Se il passaggio richiede una variabile di input, configura la variabile di input come parte dell'output dello starter.
    3. Fai clic su Aggiungi passaggio. Seleziona il passaggio che hai creato o aggiornato, denominato Calcola.
    4. Configura il passaggio. Per il passaggio di calcolo, scegli due valori e un'operazione matematica. Il passaggio viene salvato automaticamente.
    5. Per testare l'output del passaggio, aggiungine un altro. Ad esempio, per aggiungere un output a un messaggio email, puoi aggiungere il passaggio Invia un messaggio di Gmail. In Messaggio, fai clic su Variabili e seleziona l'output del passaggio. Per il passaggio di calcolo, seleziona Variabili > Passaggio 2: risultato calcolato > Risultato calcolato. La variabile viene visualizzata come chip nel campo Messaggio.
    6. Fai clic su Attiva. L'agente è pronto per essere eseguito.

  4. Esegui l'agente attivando il suo starter. Ad esempio, se il tuo agente si avvia quando ricevi un'email, invia un'email a te stesso.

  5. Verifica che l'agente venga eseguito come previsto. Controlla i log visitando la scheda Attività del generatore di agenti. Per scoprire come creare log personalizzati nella scheda Attività, consulta Log delle attività.