이 가이드에서는 사용자가 Google Workspace Studio의 에이전트에 추가할 수 있는 단계를 만드는 방법을 설명합니다.
단계는 에이전트의 작업 시퀀스에 있는 단일 단계입니다. 단계에서 에이전트를 시작할 수 없습니다.
예를 들어 산술 연산을 실행하는 단계를 생각해 보세요. 사용자에게 두 개의 값과 수학 연산을 묻습니다. 그런 다음 값에 수학 연산을 실행하고 결과를 출력합니다.
단계를 빌드하려면 부가기능의 매니페스트 파일에서 단계를 구성하고, Google Workspace 부가기능의 코드에서 애플리케이션 로직을 작성하고, 단계를 배포하고 테스트합니다.
단계 정의
단계를 구성하려면 매니페스트 파일에서 정의하고 코드에서 애플리케이션 로직을 작성합니다.
매니페스트 파일에서 단계 정의
매니페스트 파일 appsscript.json에서 다음을 실행합니다.
onConfigFunction및onExecuteFunction을 부가기능 코드의 해당 함수 이름으로 설정합니다. 이 예시에서 함수는onConfigCalculate()및onExecuteCalculate()이라고 합니다.onConfigFunction는 단계를 설정하고 구성합니다. 필요한 경우 이메일을 보낼 주소와 같이 단계를 실행하는 데 필요한 사용자 데이터를 수집합니다. 이 가이드의 예에서는 두 개의 값과 수학 연산을 요청합니다.onExecuteFunction이 단계를 실행합니다. 사용자로부터 데이터를 수집한 경우 해당 데이터가 이 함수로 전달됩니다. 해당하는 경우 출력을 반환합니다. 이 가이드의 예에서는 수학 계산 결과를 출력합니다.
필요한 입력 및 출력을 설정하여 단계에서 데이터를 수집하고 이후 단계로 전송할 수 있습니다. 이 예시에서는 사용자에게 두 개의 값과
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"
}
}
]
}
}
}
다음으로 코드에서 단계를 정의하여 지원 코드를 작성합니다.
코드에서 단계 정의
애플리케이션 코드에서 다음을 수행합니다.
onConfigFunction를 작성합니다. 이 예시에서는onConfigCalculate()이라고 합니다. 사용자가 에이전트에 단계를 추가하면 에이전트 빌더에서 단계의 측면을 구성할 수 있습니다. 사용자로부터 필요한 정보를 수집하기 위해onConfigFunction는 구성 카드를 정의합니다.카드는 부가기능의 사용자 인터페이스를 구성하는 요소입니다. 카드는 정의된 레이아웃, 버튼과 같은 대화형 UI 요소, 이미지와 같은 리치 미디어를 지원합니다. 카드는 이메일 전송을 위한 이메일 주소와 같이 단계 실행에 필요한 사용자의 데이터를 가져오는 방법입니다.
OnConfigFunction는 카드를 반환합니다. 이 카드는 사용자가 단계의 데이터를 설정하는 UI를 정의합니다. 이 예시에서onConfigFunction는 사용자에게 두 값과 수학 연산을 묻는 카드를 빌드합니다.이 예시에서는
onExecuteCalculate()이라는onExecuteFunction를 작성합니다. 단계가 에이전트에서 실행되면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);
}
걸음 테스트
단계를 테스트하려면 애드온의 테스트 배포를 설정하고, 에이전트에 단계를 추가한 후 에이전트를 실행하세요.
부가기능의 테스트 배포를 설정합니다.
- Apps Script 편집기에서 스크립트 프로젝트를 엽니다.
- 배포 > 테스트 배포를 클릭합니다.
- 설치를 클릭합니다.
- 하단에서 완료를 클릭합니다.
다른 사용자가 부가기능을 테스트하도록 하려면 해당 사용자의 계정과 Apps Script 프로젝트를 공유하면 됩니다 (수정 액세스 권한 필요). 그런 다음 사용자에게 이전 단계를 따르도록 안내합니다.
설치되면 상담사에서 부가기능을 즉시 사용할 수 있습니다. 부가기능이 표시되기 전에 에이전트를 새로고침해야 할 수도 있습니다. 또한 부가기능을 사용하기 전에 승인해야 합니다.
테스트 배포에 대해 자세히 알아보려면 게시되지 않은 부가기능 설치를 참고하세요.
에이전트를 엽니다.
단계를 포함하는 에이전트를 만듭니다.
- 새 에이전트를 클릭합니다.
- 에이전트 시작 방법을 선택합니다. 단계를 테스트할 때는 이메일 보내기 등 직접 시작할 수 있는 트리거를 선택하는 것이 좋습니다. 단계에 입력 변수가 필요한 경우 스타터의 출력의 일부로 입력 변수를 구성합니다.
- 단계 추가를 클릭합니다. 빌드하거나 업데이트한 단계(Calculate)를 선택합니다.
- 단계를 구성합니다. 계산 단계에서 두 값과 수학 연산을 선택합니다. 단계는 자동으로 저장됩니다.
- 단계의 출력을 테스트하려면 다른 단계를 추가하세요. 예를 들어 이메일 메시지에 출력을 추가하려면 Gmail의 메일 보내기 단계를 추가하면 됩니다. 메시지에서 변수를 클릭하고 단계의 출력을 선택합니다. 계산 단계에서는 변수 > 2단계: 계산된 결과 > 계산된 결과를 선택합니다. 변수가 메시지 필드에 칩으로 표시됩니다.
- 사용 설정을 클릭합니다. 에이전트를 실행할 준비가 되었습니다.
에이전트의 스타터를 작동시켜 에이전트를 실행합니다. 예를 들어 이메일을 수신할 때 에이전트가 시작되는 경우 자신에게 이메일을 보냅니다.
에이전트가 예상대로 실행되는지 확인합니다. 에이전트 빌더의 활동 탭을 방문하여 로그를 확인합니다. 활동 탭에서 맞춤 로그를 만드는 방법을 알아보려면 활동 로그를 참고하세요.