このガイドでは、Google Workspace Studio のエージェントに追加できるステップを作成する方法について説明します。
ステップは、エージェントの一連のタスクの 1 つのステップです。ステップでエージェントを開始できません。
たとえば、算術演算を行うステップについて考えてみましょう。ユーザーに 2 つの値と算術演算を尋ねます。次に、値に対して算術演算を実行し、結果を出力します。
ステップをビルドするには、アドオンのマニフェスト ファイルでステップを構成し、Google Workspace アドオンのコードでアプリケーション ロジックを記述して、ステップをデプロイしてテストします。
ステップを定義する
ステップを構成するには、マニフェスト ファイルで定義し、アプリケーション ロジックをコードで記述します。
マニフェスト ファイルでステップを定義する
マニフェスト ファイルで、appsscript.json:
onConfigFunctionとonExecuteFunctionを、アドオンのコード内の対応する関数の名前に設定します。この例では、関数はonConfigCalculate()とonExecuteCalculate()です。onConfigFunctionはステップを設定して構成します。必要に応じて、メールの送信先アドレスなど、ステップの実行に必要なデータをユーザーから収集します。このガイドの例では、2 つの値と算術演算をリクエストしています。onExecuteFunctionはステップを実行します。ユーザーからデータが収集された場合、そのデータはこの関数に渡されます。該当する場合は、出力を返します。このガイドの例では、数学の計算結果を出力します。
必要な入力と出力を設定します。これにより、ステップでデータを収集して後続のステップに送信できます。この例では、ユーザーに 2 つの値と
inputs[]で定義された算術演算を尋ねます。outputs[]で定義されている計算結果を出力します。入力と出力の詳細については、入力変数と出力変数をご覧ください。エージェントがエラーなしで実行されるように、入力変数を検証します。
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"
}
}
]
}
}
}
次に、コードでステップを定義して、サポート コードを記述します。
コードでステップを定義する
アプリケーション コードで、次の操作を行います。
onConfigFunctionを記述します。この例ではonConfigCalculate()と呼びます。ユーザーがエージェントにステップを追加すると、エージェント ビルダーでステップの側面を構成できます。ユーザーから必要な情報を収集するために、onConfigFunctionは構成カードを定義します。カードは、アドオンのユーザー インターフェースの構成要素です。カードは、定義されたレイアウト、ボタンなどのインタラクティブな UI 要素、画像などのリッチメディアをサポートしています。カードは、ステップの実行に必要なユーザーのデータ（メールの送信に使用するメールアドレスなど）を取得するために使用します。
OnConfigFunctionはカードを返します。このカードは、ユーザーがステップのデータを設定する UI を定義します。この例では、onConfigFunctionは、ユーザーに 2 つの値と算術演算を求めるカードを作成します。この例では、
onExecuteCalculate()という名前のonExecuteFunctionを記述します。ステップがエージェントで実行されると、OnExecuteFunctionが実行されます。onConfigurationFunctionで定義されているように、構成時にユーザーが設定した入力値はOnExecuteFunctionに渡されます。提供された入力を使用してタスクを同期的に実行するように
OnExecuteFunction()を記述します。OnExecuteFunction()は、エージェントのマニフェストで定義されたすべての出力を返す必要があります。そうしないと、エラーが発生します。
このコードサンプルには、提供された変数をステップの出力として構築して送信するサポート関数 outputVariables() が含まれています。
ステップのテストの準備が整いました。
Calculator ステップのコードは次のとおりです。
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);
}
ステップをテストする
ステップをテストするには、アドオンのテスト用デプロイを設定し、ステップをエージェントに追加して、エージェントを実行します。
アドオンのテスト用デプロイを設定します。
- Apps Script エディタでスクリプト プロジェクトを開きます。
- [デプロイ] > [デプロイをテスト] をクリックします。
- [インストール] をクリックします。
- 下部にある [完了] をクリックします。
他のユーザーにアドオンをテストしてもらうには、Apps Script プロジェクトをそのユーザーのアカウントと共有します（編集権限が必要です）。その後、お客様に上記の手順をご案内します。
インストールすると、アドオンは Agents で直ちに使用できるようになります。アドオンが表示される前に、エージェントの更新が必要になることがあります。アドオンを使用する前に、アドオンを承認する必要もあります。
テスト デプロイの詳細については、未公開のアドオンをインストールするをご覧ください。
[エージェント] を開きます。
ステップを含むエージェントを作成します。
- [New agent] をクリックします。
- エージェントの起動方法を選択します。ステップをテストする際は、自分で開始できるスターター（自分宛にメールを送信するなど）を選択することをおすすめします。ステップに入力変数が必要な場合は、スターターの出力の一部として入力変数を構成します。
- [ステップを追加] をクリックします。作成または更新したステップ（[Calculate]）を選択します。
- ステップを構成します。計算ステップでは、2 つの値と算術演算を選択します。手順は自動的に保存されます。
- ステップの出力をテストするには、別のステップを追加します。たとえば、メール メッセージに出力を追加するには、Gmail の [メッセージを送信] ステップを追加します。[メッセージ] で、 [変数] をクリックし、ステップの出力を選択します。計算ステップで、[変数] > [ステップ 2: 計算結果] > [計算結果] を選択します。変数は [メッセージ] フィールドにチップとして表示されます。
- [有効にする] をクリックします。エージェントの実行準備が整いました。
エージェントのスターターを起動して、エージェントを実行します。たとえば、メールを受信したときにエージェントが起動する場合は、自分宛てにメールを送信します。
エージェントが想定どおりに実行されることを確認します。ログを確認するには、エージェント ビルダーの [アクティビティ] タブにアクセスします。[アクティビティ] タブでカスタムログを作成する方法については、アクティビティ ログをご覧ください。