kintone.ai.generateText()の使い方と利用時のポイント

目次

はじめに

kintoneのカスタマイズから生成AIを呼び出せる kintone.ai.generateText() を使って、顧客リストアプリの内容を分析・要約するカスタマイズを作成します。
この記事では、基本的な実装方法に加えて、利用時の注意点やトークン使用量の目安を解説します。

caution
警告

本APIは、APIラボで提供されている検討中のAPIです。
今後、仕様が変更されたり、提供を終了したりする可能性があります。
本番環境で利用する前に、最新のAPI仕様と注意事項を確認してください。

この記事でできること

  • 顧客リストアプリのレコード一覧画面に[分析する]ボタンを追加する。
  • ボタンを押すと、生成AIが顧客ランクと最終連絡日をもとに顧客の状況を要約し、優先してフォローすべき顧客を提案する。
  • 生成されたテキストが、レコード一覧の上に確認ダイアログとして表示される。
  • 実行時のトークン数とAIクレジット使用量の目安を確認する。

この記事では、PC版のレコード一覧画面を対象にカスタマイズします。

warning
注意

このAPIを実行するたびに、 AIクレジット (External link) が使用されます。
AIクレジットが月ごとの上限に達すると、その月はこのAPIを利用できなくなります。
AIクレジットの付与量や追加購入については、上記のリンク先を確認してください。
まずは、本番環境とは別の試用環境などで、少量のデータを使って試してください。

環境を用意する

顧客リストアプリを用意する

アプリストアの「 顧客リスト (External link) 」を選択し、「サンプルデータを含める」にチェックを入れて、アプリを作成します。
作成したアプリには、20件のレコードが登録されています。

「顧客リスト」アプリを追加したら、次の設定で日付フィールドを追加します。

項目 設定値
フィールドの種類 日付
フィールド名 最終連絡日
フィールドコード contact

フィールドを追加したら、各レコードに最終連絡日を入力します。

生成AIのJavaScript APIを有効にする

次に、アップデートオプションで、「kintone AI:生成AIでテキストを生成するJavaScript API」を有効にします。

合わせて、kintone AIの管理画面から「生成AIでテキストを生成するJavaScript API」を有効にします。

カスタマイズを作成する

レコード一覧画面に[分析する]ボタンを追加し、押すと生成AIによる分析結果を確認ダイアログに表示するカスタマイズです。
以下はサンプルコードです。
利用する際は、環境や要件に合わせて調整してください。

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
(() => {
  'use strict';

  kintone.events.on('app.record.index.show', (event) => {
    // 二重にボタンを追加しない
    if (document.getElementById('ai-analyze-button')) {
      return event;
    }

    const headerSpace = kintone.app.getHeaderMenuSpaceElement();

    const button = document.createElement('button');
    button.id = 'ai-analyze-button';
    button.textContent = '分析する';

    headerSpace.append(button);

    button.addEventListener('click', async () => {
      // 実行中の連続クリックを防ぐ
      button.disabled = true;
      button.textContent = '分析中...';

      try {
        // 分析に必要なフィールドだけを取得する
        const {records} = await kintone.api(
          kintone.api.url('/k/v1/records', true),
          'GET',
          {
            app: kintone.app.getId(),
            fields: ['レコード番号', '会社名', '顧客ランク', 'contact'],
            query: 'order by レコード番号 asc limit 100'
          }
        );

        // AIに渡すデータを整形する
        const customers = records.map((record) => ({
          レコード番号: record.レコード番号.value,
          会社名: record.会社名.value,
          顧客ランク: record.顧客ランク.value,
          最終連絡日: record.contact.value
        }));

        const today = new Date().toISOString().slice(0, 10);

        const {textStream} = await kintone.ai.generateText({
          model: 'claude-4-6-sonnet-v1',
          messages: [
            {
              role: 'system',
              content: 'あなたは営業支援を行うアシスタントです。'
            },
            {
              role: 'user',
              content:
                `今日は${today}です。次の顧客リスト(JSON)を、顧客ランクと最終連絡日をもとに分析してください。\n` +
                '1. 顧客ランクごとの傾向を簡潔に要約してください。\n' +
                '2. 最終連絡日から時間が経っている顧客を挙げてください。\n' +
                '3. 優先してフォローすべき顧客を、理由とともに3社まで提案してください。\n' +
                'Markdown記法は使わず、プレーンテキストで回答してください。\n\n' +
                JSON.stringify(customers)
            }
          ],
          temperature: 0.2,
          maxTokens: 1500
        });

        // 生成されたテキストを、差分ごとに受け取って1つにまとめる
        let text = '';
        for await (const part of textStream) {
          text += part;
        }

        // 生成が終わってから、確認ダイアログに結果を表示する
        await kintone.showConfirmDialog({
          title: '顧客リストの分析結果',
          body: text,
          showOkButton: true,
          okButtonText: '閉じる',
          showCancelButton: false,
          showCloseButton: true
        });
      } catch (error) {
        console.log(error);
        await kintone.showConfirmDialog({
          title: 'エラー',
          body:
            'エラーが発生しました。AIクレジットの上限に達したか、短時間にリクエストが集中した可能性があります。',
          showOkButton: true,
          showCancelButton: false,
          showCloseButton: true
        });
      } finally {
        button.disabled = false;
        button.textContent = '分析する';
      }
    });

    return event;
  });
})();

サンプルコードのポイント

  • 送信するデータを絞る:
    顧客リストアプリには、住所やTEL、添付ファイルなど、分析に不要なフィールドもあります。今回は会社名、顧客ランク、contact(最終連絡日)だけを取得して渡しています。送信するデータを絞ることで、使用するトークン数を抑えられます。
  • maxTokensで出力トークン数に上限を設ける:
    maxTokensには、生成するテキストの最大トークン数を1以上8,192以下の整数で指定できます。今回は出力が約1,000トークンになることを想定し、余裕を持たせて1,500に設定しています。
  • 実行中はボタンを無効にする:
    連続クリックによる重複実行を防ぎます。
  • APIの実行エラーを処理する:
    AIクレジットが月の上限に達した場合や、レート制限に達した場合はエラーメッセージを表示します。

動作確認

  1. アプリの設定で、上記のJavaScriptファイルをカスタマイズとして登録し、アプリを更新します。
  2. レコード一覧画面を開き、[分析する]ボタンをクリックします。
  3. 生成が終わるまで、ボタンは[分析中…]と表示されます。生成が終わると、分析結果が確認ダイアログに表示されます。

実行結果の例

【1. 顧客ランクごとの傾向】

Aランク(12社)
最も多くの顧客を占めるランクです。
最終連絡日は2026-09-01(金都運総研)から2026-09-25(戸田ネットソリューションズ)まで幅広く分布しています。
直近1〜2週間以内に連絡が取れている顧客が多い一方、9月上旬以前に連絡が止まっている顧客も複数います。
重要度が高いにもかかわらずフォローが滞っているケースと考えられます。

Bランク(4社)
鈴木土地建物、岩下税理士事務所、新山物産、林田商会の4社で、最終連絡日はいずれも9月上旬〜中旬に集中しています。
Aランクほど緊急度は高くないものの、最終連絡から1ヶ月近く経過している会社もあり、定期的なフォローが必要な状況です。

Cランク(4社)
仲間建材工業、岡崎商会、板橋電子株式会社、林田商会の4社で、最終連絡日はいずれも9月上旬〜中旬です。
優先度は相対的に低いです。

【2. 最終連絡日から時間が経っている顧客】

今日(2026-10-08)から30日以上経過している顧客を目安に抽出します。

金都運総研(Aランク):2026-09-01、37日経過
林田商会(Bランク):2026-09-02、36日経過
板橋電子株式会社(Cランク):2026-09-03、35日経過
新山物産(Bランク):2026-09-04、34日経過
岩下税理士事務所(Bランク):2026-09-07、31日経過
岡崎商会(Cランク):2026-09-08、30日経過
草刈組(Aランク):2026-09-09、29日経過
鈴木土地建物(Bランク):2026-09-10、28日経過
株式会社井上技研(Aランク):2026-09-11、27日経過

上記9社が特に連絡が空いている顧客として挙げられます。

【3. 優先してフォローすべき顧客(3社)】

第1位:金都運総研(Aランク、最終連絡日:2026-09-01)
理由:最も連絡が空いている顧客(37日経過)で、かつAランクという最重要顧客です。ランクの高さと経過日数の長さを合わせると、リスクが最も大きく、早急なフォローが必要です。

第2位:草刈組(Aランク、最終連絡日:2026-09-09)
理由:Aランクで29日間連絡が途絶えています。重要顧客でありながら1ヵ月近く連絡の感覚が空いている状態で、関係維持の観点から優先度が高いです。

第3位:株式会社井上技研(Aランク、最終連絡日:2026-09-11)
理由:こちらもAランクで27日間連絡がありません。上位2社に続く経過日数で、重要顧客の中で3番目に対応が急がれます。

なお、BランクではあるものとBランクの林田商会(36日経過)や新山物産(34日経過)も、経過日数が長いため、Aランクの対応後に速やかにフォローすることを推奨します。

使用したトークン数とAIクレジットの目安

今回の実行で使用したトークン数とAIクレジットの目安を示します。

項目 目安
対象レコード数 20件
入力トークン数(絞り込み後のデータ+プロンプト) 約900トークン
出力トークン数 約1,000トークン
使用したAIクレジット 5クレジット前後
(参考)絞り込まずに全フィールドを渡した場合の入力トークン数 約8,500トークン

トークン数とAIクレジットの使用量は、使用するモデル、入力データ、生成されるテキストの量によって変わります。
表の数値は、今回の実行結果に基づく目安です。
AIクレジットの使用量は、[kintoneシステム管理]の[AI]セクションにある AIクレジットの使用状況 (External link) で確認できます。
実行前後の使用量を比較すると、1回の実行で消費したAIクレジットを確認できます。

試用環境では、月500クレジットを利用できます。
今回と同程度の使用量の場合、月100回程度実行できる計算です。

安心して使うためのポイント

  1. AIクレジットの使用量は、プロンプトやデータ量によって大きく変わる可能性があります。本番環境に展開する際は、本番と同程度のデータ量・同じプロンプトで実行し、使用量を確認してください。

  2. まずは、試用環境などの本番環境とは別の環境で、動作と使用量を確認しましょう。本番環境のAIクレジットを消費せずに、使用量を把握できます。

  3. 利用者が自由にプロンプトを入力できる画面では、想定以上に長い文章や大量のデータが入力され、使用量を予測しにくくなります。入力できる文字数やデータ量に上限を設けてください。

  4. maxTokensには、用途に見合った上限を設定してください。

  5. レコードのすべてのフィールドを渡す必要はありません。取得するフィールドを絞り、件数が多い場合は、取得条件で対象を絞りましょう。

  6. 処理中はボタンなどの操作要素を無効にしましょう。合わせて、スピナーなどを使って処理中な旨を示すと、利用者に状況が伝わりやすくなります。

  7. app.record.index.showやapp.record.detail.showなどのレコード表示イベントでは、このAPIを呼び出さないでください。画面を表示するたびにAPIが実行され、意図せずAIクレジットを消費する恐れがあります。ボタンのクリックやプロセス管理のステータス変更など、ユーザーが明示的に操作したタイミングで実行してください。

おわりに

この記事では「生成AIを使いテキストを生成する」APIを利用した場合の、トークン数とAIクレジット使用量の目安を紹介しました。
実際の使用量は、入力するデータやプロンプト、生成されるテキストの量によって変わります。
利用を始める前に、想定する条件で実行し、使用量を確認することが大切です。
使用量を確認・調整するときのポイントは、次のとおりです。

  • 実行するたびにAIクレジットが使用されるため、まずは試用環境で少量のデータから試す。
  • 送るデータとmaxTokensを絞り、使用量をコントロールする。
  • 公開前に、本番と同程度のデータで使用量を確認する。
information

このTipsは、2026年10月版kintoneで動作を確認しています。

公式コミュニティ

kintone開発者同士で質問や知見を共有し、学び合うことができます。