# AIで関連レコード分析 詳細マニュアル | 設定リファレンス・トラブルシューティング - KINTAUROS

> kintoneプラグイン「AIで関連レコード分析」の詳細マニュアル。全設定項目のリファレンス(意味・制約値)、動作条件・制限事項、エラーコード別のトラブルシューティングを掲載。対象バージョン: v3.6.0。

元ページ: https://kintauros.com/plugins/ai-analysis/manual/

AIで関連レコード分析は、関連アプリのレコードを取得して生成AI(Google Gemini / OpenAI / Anthropic Claude)で分析し、結果をフィールドへ書き戻すプラグインです。このマニュアルでは、設定項目のリファレンスと、動作仕様・制限事項・トラブルシューティングを説明します。

機能紹介・画面イメージ・導入手順は[プラグイン紹介ページ](https://kintauros.com/plugins/ai-analysis/)を、ダウンロードは[ダウンロードページ](https://kintauros.com/download/)をご覧ください。このマニュアルは[Markdown版](index.md)でも提供しており、全プラグインのメタ情報と設定スキーマは機械可読な[catalog.json](https://kintauros.com/catalog.json)から取得できます。

## 基本情報

- **プラグインID**: ai-analysis

- **対象バージョン**: v3.6.0(配布中の最新版)

- **カテゴリ**: 帳票・自動化

- **説明**: 関連レコードを生成AIで処理し、レコードの更新を自動化します。

## 動作条件

- **対応環境**: kintone スタンダードコース(デスクトップ版UI)。最新版の Chrome / Edge / Safari / Firefox に対応。

- **動作画面**: レコード詳細画面(分析ボタンの表示・実行)。結果の書き込みには対象レコードの編集権限が必要です。

- **利用するAI**: Google Gemini / OpenAI / Anthropic Claude から設定画面で選択。お客様ご自身で取得したAPIキーが必要です(APIの利用料金はお客様のご負担)。

- **データの送信先**: 分析実行時、対象のレコードデータはkintoneのサーバーを経由して選択したAI提供企業へお客様のAPIキーで送信されます。KINTAUROSのサーバーにレコードデータが送信されることはありません。

## 設定項目リファレンス

プラグイン設定の全項目です。「項目」は設定データ(エクスポートファイルの config)のキーを表し、[] は配列の要素を意味します。設定画面での入力項目と1対1に対応します。この構造の正式な定義はJSON Schema([catalog.json](https://kintauros.com/catalog.json) の configSchema)として公開しています。

- **項目**: 型 / 必須 / 説明・制約

- **modelName**: 文字列 / 任意 / Gemini モデル名 / 省略時は gemini-1.5-flash。

- **buttonLabel**: 文字列 / 任意 / 実行ボタンの表示名 / 省略時は「AI分析開始」。

- **dataSources**: 配列 / 必須 / データ取得設定 / 1件以上

- **dataSources[].subAppId**: 文字列 / 必須 / 取得元アプリID / 形式: ^[0-9]+$

- **dataSources[].subAppName**: 文字列 / 任意 / 取得元アプリ名(表示用の控え)

- **dataSources[].mainLinkField**: 文字列 / 必須 / このアプリの連携キー(フィールドコードまたは "$id") / 1文字以上

- **dataSources[].subLinkField**: 文字列 / 必須 / 取得元アプリの連携キー(フィールドコードまたは "$id") / 1文字以上

- **dataSources[].subAppFields**: 配列(文字列) / 任意 / 取得するフィールド

- **dataSources[].filterConditions**: 配列 / 任意 / 絞り込み条件(AND)

- **dataSources[].filterConditions[].field**: 文字列 / 必須 / 1文字以上

- **dataSources[].filterConditions[].operator**: 文字列 / 必須 / 値: = | != | > | < | >= | <= | like | not like | in | not in

- **dataSources[].filterConditions[].value**: 文字列 / 任意 / -

- **dataSources[].sortConditions**: 配列 / 任意 / 並び替え

- **dataSources[].sortConditions[].field**: 文字列 / 必須 / 1文字以上

- **dataSources[].sortConditions[].order**: 文字列 / 必須 / 値: asc | desc

- **dataSources[].recordLimit**: 文字列 / 任意 / レコード数の上限(既定 5) / 形式: ^[0-9]+$

- **promptTemplate**: 文字列 / 必須 / プロンプト / {{フィールドコード}} でこのアプリの値を、{{SubAppRecords}} で取得レコードを埋め込む。 / 1文字以上

- **outputMapping**: 配列 / 任意 / 出力先と指示

- **outputMapping[].fieldCode**: 文字列 / 必須 / AIの出力を保存するこのアプリのフィールドコード / 1文字以上

- **outputMapping[].instruction**: 文字列 / 必須 / この出力への指示(例: 英語に翻訳して)

- **outputMapping[].type**: 文字列 / 任意 / フィールド型(保存時に自動算出。手で編集しない)

## 設定のポイント

- APIキーは kintone のプラグイン外部API連携(setProxyConfig)にのみ保存され、この設定(getConfigで読める値)には含まれません。設定のエクスポートにもAPIキーは含まれないため、インポート後は設定画面でAPIキーを設定し直してください。

- APIキーはプロバイダごとに保存されます。キー設定済みのプロバイダ間は、設定の provider を切り替えるだけで使い分けられます。

- 初回設定の保存には「データの送信先について」の確認事項へのチェックが必要です。

- フィールドコード "$id" はレコード番号を表します(連携キーとして使用可能)。

## 動作仕様

- レコード詳細画面のボタンを押すと、(1)データ取得設定に従って関連レコードを取得、(2)プロンプトの {{フィールドコード}} と {{SubAppRecords}} を実際の値に展開、(3)AIへ送信、(4)出力マッピングに従って結果をフィールドへ書き込み、の順で実行されます。完了後はページがリロードされます。

- 取得元アプリは複数設定でき、それぞれに連携キー・取得フィールド・絞り込み条件(AND)・並び順・件数上限(既定5件)を指定できます。

- 出力先フィールドごとに「何を書くか」の指示を設定でき、AIの出力を構造化して複数フィールドへ同時に書き込めます。

## 制限事項・既知の仕様

- モバイルアプリの画面では動作しません(デスクトップ版UIのみ)。

- 生成AIの出力は正確性・完全性・最新性を保証できません。出力内容の確認と業務利用の判断はお客様の責任で行ってください。

- 個人情報・機密情報を含むデータを送信するかどうかは、お客様の判断と責任で設定してください。

- 取得元アプリのレコードを読むため、実行するユーザーに取得元アプリの閲覧権限が必要です。

## 設定のインポート / エクスポート

プラグイン設定画面の上部にある「設定のインポート / エクスポート」から、現在の設定をJSONファイルとして書き出し(エクスポート)、別のアプリで読み込み(インポート)できます。検証用アプリから本番アプリへの設定コピーや、バックアップ・復元にご利用ください。

- インポートは取り込む内容の差分を確認してから「設定画面に反映」し、最後に「保存」を押して確定します(反映しただけでは保存されません)。

- 読み込んだファイルはブラウザ内で処理され、KINTAUROSのサーバーには送信されません。

- 別のアプリの設定を取り込んだ場合、このアプリに存在しないフィールドは警告として一覧表示されるので、反映後に該当箇所を選び直してください。

エクスポートファイルは次の形式(封筒形式)です。config の中身が設定本体で、その構造は上の設定項目リファレンスのとおりです。

```
{
  "kintauros": "config/v1",
  "plugin": "<プラグインID>",
  "pluginName": "<プラグイン名>",
  "pluginVersion": "<バージョン>",
  "exportedAt": "<書き出し日時(ISO 8601)>",
  "sourceApp": "<書き出し元アプリID>",
  "config": { ... 設定本体 ... }
}
```

### AIエージェント向け: ブラウザコンソールAPI

各プラグインは共通ランタイム window.KINTAUROS を搭載しており、ブラウザの開発者コンソールから設定の読み取り・検証・保存ができます。設定の保存(save: true)はkintoneの制約上、プラグイン設定画面でのみ成功します。

```
KINTAUROS.config.plugins()                   // このページのKINTAUROSプラグインID一覧
KINTAUROS.config.describeAll()               // 同居プラグインすべての設定サマリ
KINTAUROS.config.of('<プラグインID>').schema()    // 設定のJSON Schema
KINTAUROS.config.of('<プラグインID>').export()    // 現在の設定(封筒つき)
KINTAUROS.config.of('<プラグインID>').validate(x) // 保存せず検証
KINTAUROS.config.of('<プラグインID>').diff(x)     // 現在の設定との差分
await KINTAUROS.config.of('<プラグインID>').import(x, { save: true }) // 検証して保存(設定画面のみ)
```

登録が1件だけのページでは of(...) を省略できます(例: KINTAUROS.config.export())。

## トラブルシューティング

**「使用するAIプロバイダのAPIキーが設定されていません」と表示される**

設定画面の「プロバイダ別設定」で、選択中のプロバイダのAPIキーを入力して保存してください。設定をインポートした直後もAPIキーは引き継がれないため、この状態になります。プラグインを入れ直した場合も同様に、設定画面を開いて保存し直してください。

**「対象となる関連レコードが見つかりませんでした」と表示される**

データ取得設定の連携キー(このアプリ側・取得元アプリ側)の値が一致するレコードが取得元アプリに存在するか、絞り込み条件が厳しすぎないかを確認してください。

**AI分析の実行時にエラーが発生する**

エラーメッセージに含まれるAPIエラーの内容を確認してください。よくある原因は、APIキーの誤り・失効、モデル名の誤り(プロバイダ別設定のモデル名を確認)、APIの利用上限・クレジット不足です。

**結果がフィールドに書き込まれない**

実行したユーザーに対象レコードの編集権限があるか、出力マッピングのフィールドコードが実在するかを確認してください。

## エラーコードと診断情報

AIで関連レコード分析を含むKINTAUROSプラグインは、エラー発生時にブラウザのコンソールへ統一形式のログを出力します。人間向けの1行に続けて、機械可読なJSON(code / plugin / version / appId / message / doc)を出力し、doc には該当エラーの解説ページのURLが入ります。

```
[KINTAUROS <プラグインID>@<バージョン>] E001: 設定されたフィールドが見つかりません: ...
{"kintauros":{"code":"E001","plugin":"...","version":"...","appId":"...","message":"...","doc":"https://kintauros.com/docs/errors/E001"}}
```

各エラーコードの意味と対処は[エラーコード一覧](https://kintauros.com/docs/errors/)を参照してください。また、プラグイン設定画面の「サポート用情報をコピー」から、環境・バージョン・ライセンス状態・直近のエラーを含む診断情報をコピーできます(レコードの内容や個人情報は含まれません)。お問い合わせの際はこの情報を添えてください。

## ライセンスについて

- 初回利用時は、プラグイン設定画面の「利用開始」ボタンから60日間の無料トライアルを開始できます(カード登録不要)。

- トライアル・契約の期限が切れるとプラグインの動作は停止し、画面に案内が表示されます。[料金プラン](https://kintauros.com/#pricing)から契約すると同じ設定のまま再開できます。

- ライセンス確認のための外部通信で送信されるのは、kintoneドメイン名・プラグインID・バージョンのみです。レコードの内容や個人情報が外部に送信されることはありません。

- ライセンスサーバーに一時的に接続できない場合も、プラグインは一定期間動作を継続する設計です。

## サポート

解決しない場合は[お問い合わせ](https://kintauros.com/contact/)からご連絡ください。その際、プラグイン設定画面の「サポート用情報をコピー」でコピーした診断情報を添えていただくと、調査がスムーズです。

最終更新: 2026-08-14 / 対象バージョン: v3.6.0