Esta página foi traduzida pela API Cloud Translation.

Criar uma etapa

Este guia explica como criar uma etapa que os usuários podem adicionar a um agente no Google Workspace Studio.

Uma etapa é uma única etapa na sequência de tarefas de um agente. As etapas não podem iniciar um agente.

Por exemplo, considere uma etapa que faz aritmética. Ele pede ao usuário dois valores e uma operação matemática. Em seguida, ele executa a operação matemática nos valores e gera o resultado.

Um usuário configura a etapa da calculadora como parte de um agente.

Figura 1:um usuário configura a etapa da calculadora como parte de um agente.

Para criar uma etapa, configure-a no arquivo de manifesto do complemento, escreva a lógica do aplicativo no código do complemento do Google Workspace e implante e teste a etapa.

Definir a etapa

Para configurar uma etapa, defina-a no arquivo de manifesto e escreva a lógica do aplicativo em código.

Definir a etapa no arquivo de manifesto

No arquivo de manifesto, appsscript.json:

Defina onConfigFunction e onExecuteFunction como os nomes das funções correspondentes no código do complemento. Neste exemplo, as funções são chamadas de onConfigCalculate() e onExecuteCalculate().
- O onConfigFunction configura e define a etapa. Se necessário, coleta dados dos usuários necessários para executar a etapa, como o endereço para enviar um e-mail. No exemplo deste guia, pedimos dois valores e uma operação matemática.
- onExecuteFunction executa a etapa. Se os dados foram coletados dos usuários, eles serão transmitidos para essa função. Se aplicável, retorna uma saída. No exemplo deste guia, mostra o resultado de um cálculo matemático.
Defina as entradas e saídas necessárias, o que permite que a etapa colete dados e os envie para etapas posteriores. Neste exemplo, peça ao usuário dois valores e uma operação matemática definida em inputs[]. Gere o resultado calculado conforme definido em outputs[].

Para saber mais sobre entradas e saídas, consulte Variáveis de entrada e Variáveis de saída. Para garantir que os agentes sejam executados sem erros, valide as variáveis de entrada.

Confira o arquivo de manifesto para a etapa "Calculator":

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

Em seguida, escreva o código de suporte definindo a etapa no código.

Definir a etapa no código

No código do aplicativo, faça o seguinte:

Escreva a onConfigFunction, chamada de onConfigCalculate() neste exemplo. Quando os usuários adicionam a etapa a um agente, eles podem configurar aspectos dela no criador de agentes. Para coletar as informações necessárias do usuário, o onConfigFunction define um card de configuração.

As fichas são os elementos básicos das interfaces de usuário em complementos. Os cards oferecem suporte a um layout definido, elementos interativos da interface, como botões, e mídia avançada, como imagens. Os cards são a maneira de receber dados de um usuário para que a etapa seja executada, como um endereço de e-mail para enviar uma mensagem.

O OnConfigFunction retorna um card. Este card define a interface em que os usuários configuram os dados da etapa. Neste exemplo, o onConfigFunction cria um card que pede ao usuário dois valores e uma operação matemática.
Escreva o onExecuteFunction chamado onExecuteCalculate() neste exemplo. Quando sua etapa é executada em um agente, o OnExecuteFunction é executado. Todos os valores de entrada definidos pelo usuário durante a configuração, conforme definido em onConfigurationFunction, são transmitidos para OnExecuteFunction.

Escreva OnExecuteFunction() para que ele execute a tarefa de forma síncrona usando as entradas fornecidas. Lembre-se de que OnExecuteFunction() precisa retornar todas as saídas definidas no manifesto do seu agente. Caso contrário, um erro vai ocorrer.

Este exemplo de código inclui uma função de suporte, outputVariables(), que cria e envia as variáveis fornecidas como saída da etapa.

Sua etapa está pronta para teste.

Confira o código da etapa "Calculadora":

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

Teste sua etapa

Para testar sua etapa, configure uma implantação de teste para seu complemento, adicione a etapa a um agente e execute o agente.

Configure uma implantação de teste para seu complemento:
1. Abra o projeto de script no editor do Apps Script.
2. Clique em Implantar > Testar implantações.
3. Clique em Instalar.
4. Na parte de baixo, clique em Concluído.
Você pode permitir que outros usuários testem o complemento compartilhando o projeto do Apps Script com a conta deles. É necessário ter acesso de edição. Em seguida, peça para os usuários seguirem as etapas anteriores.

Depois de instalado, o complemento fica disponível imediatamente em Agentes. Talvez seja necessário atualizar os agentes antes que o complemento apareça. Você também precisa autorizar o uso do complemento.

Para saber mais sobre implantações de teste, consulte Instalar um complemento não publicado.
Abra "Agentes".
Crie um agente que inclua sua etapa:
1. Clique em Novo agente.
2. Selecione como o agente vai começar. Ao testar uma etapa, é recomendável escolher um gatilho que você possa acionar sozinho, como enviar um e-mail para você mesmo. Se a etapa exigir uma variável de entrada, configure-a como parte da saída do iniciador.
3. Clique em Adicionar etapa. Selecione a etapa que você criou ou atualizou, chamada Calcular.
4. Configure a etapa. Para a etapa de cálculo, escolha dois valores e uma operação matemática. A etapa é salva automaticamente.
5. Para testar a saída da etapa, adicione outra. Por exemplo, para adicionar saída a uma mensagem de e-mail, você pode adicionar a etapa Enviar uma mensagem do Gmail. Em Mensagem, clique em Variáveis e selecione a saída da etapa. Para a etapa de cálculo, selecione Variáveis > Etapa 2: resultado calculado > Resultado calculado. A variável aparece como um ícone no campo Mensagem.
6. Clique em Ativar. Seu agente está pronto para ser executado.
Execute o agente ativando o início do agente. Por exemplo, se o agente for iniciado quando você receber um e-mail, envie um e-mail para você mesmo.
Verifique se o agente é executado conforme o esperado. Para verificar os registros, acesse a guia Atividade do criador de agentes. Para saber como criar registros personalizados na guia "Atividade", consulte Registros de atividades.

Criar uma etapa Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.