[GWSStudio100本ノック] Workspace Studioでエージェントを作成するときの個人的なテクニックをまとめてみた

はじめに

本記事は、Google Workspace Studio(旧Flows)の実践ノウハウを100本紹介する連載「Google Workspace Studio活用方法100本ノック」の一つとなります。

ちなみにですが、このブログは「XIMIX Google Workspace Studio(旧flows)のみ Advent Calendar 2025」の最終日のブログとなります。私がこのアドベントカレンダーを完走するために活用したテクニックを最後のブログとして作成してみました。

今回は、これまでのエージェント構築で蓄積した知見から、「Workspace Studioでエージェントを組むときに押さえておきたいテクニック」をまとめます。スターター選定のコツ、Geminiステップのプロンプト設計、条件分岐やループ再利用の方法など、日常的にエージェントを作る際に役立つヒントを整理し、エージェント作成の精度とスピードを高めることが目的です。

前提条件

• 利用環境：Google Workspace Studioにアクセスできるユーザーであること。

テクニック

エージェントの作成は自然言語で効率的に！

Workspace Studioではトップ画面で自然言語のエージェントを作成することができます。私がここまで作成した活用ブログの全体像のセクションに記載している内容を入力して作成すればある程度Geminiがテンプレートを作成してくれます。

「[GWSStudio100本ノック] 受信したメール内容を要約するエージェントを作成してみた」の全体像で記載していた内容をそのまま入力して自動作成してもらうようにします。少し待つとほぼブログの通りのステップを自動で作成してくれるので、これをそのまま利用して効率的にエージェント構築を進められると思います。

3rdパーティの統合機能はマーケットプレイスから導入！

Workspace StudioがWorkspace Flowsという名前だったころ、SalesforceやJiraなどとのインテグレーション(統合機能)はデフォルトで利用できました。Workspace Studioにリブランディングされてからしばらく経ったタイミングで、この統合機能はマーケットプレイスから導入する方式に変更されました。ちなみに、2025年12月現在はGoogleが用意したものとデベロッパーが用意したものは別のページで管理されています。

ちなみにですが、Workspace Studioに対応しているインテグレーションにはロゴが掲載されています。

また、3rdパーティのインテグレーションには今後Slackが追加される予定のようです。(公式ドキュメント)私はGASを利用したカスタムステップでSlackと連携するブログを書かせていただいたのですが、不要になるかもしれないなと感じています。

Ask GeminiのプロンプトはGeminiに考えさせよう！

Workspace StudioではAsk Geminiのステップではプロンプトを入力することができます。このプロンプトに入力する内容はエージェントの心臓といっても差し支えないと思います。このプロンプトを作成するときは最近アップデートされたこともあるのでGemini3.0で作成することをおすすめします。

私がアドベントカレンダーで作成したブログのプロンプトの内容はGeminiと壁打ちすることで作成しました。どのような内容とするかはできるだけ伝えたほうが良いですが、壁打ちすることで作成することをおすすめします。

GASのカスタムステップを有効活用しよう！(2025年12月は限定プレビュー)

Workspace Studioではサービス開始当初はGoogle Apps Script(GAS)を利用してカスタムステップを作成することができました。私はこの機能を利用して4つほどブログを作成していました。現在は限定プレビューとなってしまったため利用することができませんが、皆様が利用できるようになったときには私が作成したブログを有効活用していただけると嬉しいです。

本当は個別でブログを書いて公開する予定としていたWorkspace StudioのGAS作成用のGemのシステムプロンプトも以下に共有させていただきます。まだ完成度はまだまだですが限定プレビューが終わったころに内容を洗練させていきたいと考えています。

このドキュメントは、Google Workspace Studioのカスタムステップ（Action）として機能するGoogle Apps Script (GAS) を開発するための包括的な指針である。

1. 全体アーキテクチャとファイル構成

Workspace Studio連携用GASは、必ず以下の2つのファイル設定を含む必要がある。
appsscript.json (マニフェスト): 入出力インターフェースと関数バインディングを定義。
Code.gs (スクリプト): onConfig（設定画面）と onExecute（実行処理）のロジック、および必須ヘルパー関数を実装。

2. マニフェストファイル (appsscript.json) の要件

プロジェクト設定で「マニフェストファイルをエディタで表示」を有効にし、以下の構造を記述すること。
addOns.flows.workflowElements: ここにアクションを定義する。

inputs / outputs:
id: スクリプト内の変数名と完全に一致させること。
dataType: 基本的に STRING を推奨する（数値やJSONも文字列として受け渡す方がトラブルが少ない）。

関数指定:
onConfigFunction: 設定画面を生成する関数名。
onExecuteFunction: 処理を実行する関数名。

JSON
// 例: マニフェストの一部
"workflowAction": {
  "inputs": [
    { "id": "myInput", "dataType": { "basicType": "STRING" } }
  ],
  "outputs": [
    { "id": "myResult", "dataType": { "basicType": "STRING" } }
  ]
}

3. スクリプト実装要件 (Code.gs)

3.1. 必須ヘルパー関数 (Boilerplate)

Workspace Studioとの通信プロトコル準拠のため、以下のヘルパー関数を必ず実装し利用すること。
pushCard(card): 設定画面のJSONオブジェクトをラップして返す。
outputVariables(variableDataMap): 実行結果をWorkspace Studioに返す。
getStringValue(inputItem): Workspace Studioからの入力値（String/Integer）を安全に文字列化して取得する。

3.2. 設定画面関数 (onConfigFunction)

UI構築: CardService クラスでのビルドではなく、JSONオブジェクト形式で定義し、pushCard() で返す方式を採用すること。
変数連携: 各ウィジェットには必ず hostAppDataSource を設定し、Workspace Studioの前のステップの変数を挿入可能にすること。

JavaScript
// ウィジェット設定の必須パターン
"textInput": {
  "name": "inputName", // マニフェストのIDと一致
  "hostAppDataSource": { "workflowDataSource": { "includeVariables": true } }
}

3.3. 実行関数 (onExecuteFunction)

引数: event オブジェクトを受け取る。
入力取得: event.workflow.actionInvocation.inputs から取得する。
重要: 直接 .stringValues[0] を参照せず、必ずヘルパー関数 getStringValue() を経由させること。（Workspace Studio側で数値として扱われたデータが欠落するのを防ぐため）
出力返却: AddOnsResponseService を使用して値を返す。複雑な構造データ（BigQueryの結果など）は JSON.stringify() で文字列化して返すこと。

4. 外部サービス連携の方針

4.1. Google Workspace 標準サービス

推奨: 「サービスの追加」から Advanced Services（例: People API, BigQuery API）を追加して利用する。
非推奨: ContactsApp などの古いAPIは使用しない。

4.2. 外部API (Slack等) との連携

UrlFetchApp を使用してREST APIを実行する。
認証トークンはコードに直書きせず、スクリプトプロパティ (PropertiesService) に格納する。

4.3. サービスアカウント (GCP) の利用

実行ユーザーの権限ではなく、特定の権限で実行（例: BigQuery）する場合は、OAuth2 ライブラリを導入する。
秘密鍵 (private_key) は改行コード処理 (.replace(/\\n/g, '\n')) が必要なため注意する。

5. 安全性とエラーハンドリング

5.1. 入力バリデーション

SQLなどを外部から受け取る際は、危険なコマンド（DROP, DELETE 等）が含まれていないかチェックする。
AI生成テキストを受け取る場合は、Markdown記法（```sql）などを除去するクリーニング処理を実装する。

5.2. エラー処理

try-catch ブロックで全体を囲む。
エラー発生時はスクリプトを強制終了させず、エラーメッセージを Output変数（例: status や error_message）に入れてWorkspace Studio側に返し、Workspace Studio側で分岐できるようにする設計を推奨する。

6. 実装テンプレート (コピー用)

新規作成時は以下のテンプレートをベースにすること。

JavaScript
// ---------------------------------------------------------// Helper Functions (DO NOT MODIFY)// ---------------------------------------------------------

function pushCard(card) {
  return { "action": { "navigations": [{ "push_card": card }] } };
}

function outputVariables(variableDataMap) {
 const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction().setVariableDataMap(variableDataMap);
 const hostAppAction = AddOnsResponseService.newHostAppAction().setWorkflowAction(workflowAction);
 return AddOnsResponseService.newRenderActionBuilder().setHostAppAction(hostAppAction).build();
}

function getStringValue(inputItem) {
  if (!inputItem) return "";
  if (inputItem.stringValues && inputItem.stringValues.length > 0) return inputItem.stringValues[0];
  if (inputItem.integerValues && inputItem.integerValues.length > 0) return String(inputItem.integerValues[0]);
  return "";
}

// ---------------------------------------------------------// Main Functions// ---------------------------------------------------------

/**
 * Configuration Screen
 */
function onConfigExample() {
  var card = {
    "sections": [
      {
        "header": "Settings",
        "widgets": [
          {
            "textInput": {
              "name": "myInput", // Match with manifest ID
              "label": "Input Label",
              "hostAppDataSource" : { "workflowDataSource" : { "includeVariables" : true } }
            }
          }
        ]
      }
    ]
  };
  return pushCard(card);
}

/**
 * Execution Logic
 */
function onExecuteExample(event) {
  console.log("Event: " + JSON.stringify(event));

  // 1. Get Inputs safely
  const inputs = event.workflow.actionInvocation.inputs;
  const myInput = getStringValue(inputs["myInput"]);
  var result = "";

  try {
    // 2. Business Logic here
    if (!myInput) throw new Error("Input is empty");
    result = "Processed: " + myInput;
  } catch (e) {
    console.error(e);
    result = "Error: " + e.toString();
  }

  // 3. Return Outputs
  const variableDataMap = {
    "myResult": AddOnsResponseService.newVariableData().addStringValue(result)
  };
  return outputVariables(variableDataMap);
}

まとめ

Workspace Studioで業務自動化を加速させるには、基本機能の習得だけでなく、テンプレート活用やプロンプト設計、条件分岐のベストプラクティスなどの“細かいコツ”を押さえることが重要です。

本記事で紹介したテクニックを活用すれば、エージェント構築の再現性が高まり、チーム内での展開や運用もスムーズになります。これから本格的にエージェントを整備する際のハンドブックとして、ぜひ活用してください。