AIアシスタントの連携アクションを設定する

AI回答は、上流のナレッジ検索ノードで得た検索結果を利用するナレッジで明示的に選び、その根拠から回答します。

AIアシスタントは、利用できる連携アクションから必要な処理を選び、検索や外部処理の結果から回答します。HTTPリクエストの接続先APIとサイトJS連携で呼び出す処理は、Kotaelへ登録する前に用意してください。連携アクションは、外部機能そのものを作成する設定ではありません。

1. スタジオでAIエージェントを開き、詳細設定の連携アクションへ進みます。
2. 種別を選んで追加から、HTTPリクエスト、サイトJS連携、またはナレッジ検索を選びます。
3. 表示名と、英小文字で始まる連携アクションIDを設定します。IDは作成後に変更できません。
4. 使うタイミングへ、どの質問や依頼で使うかを入力します。

使うタイミングには、HTTPリクエストなら「注文の配送状況を確認したいとき」、サイトJS連携なら「訪問者が商品の追加を希望したとき」、ナレッジ検索なら「返品・交換の条件を案内するとき」のように具体的な目的を書きます。

AIに読み取らせる情報では、AIアシスタントが受け取った訪問者の質問・回答から値を読み取る方法を項目ごとに指定します。HTTPリクエストとサイトJS連携では、たとえばorder_idに「訪問者が伝えた注文番号」、product_idに「訪問者が指定した商品番号。例：P001」と設定します。文字列、数値、はい・いいえ、選択肢から値の形式を選び、必要な項目だけ必須にします。ナレッジ検索の入力項目は、変更できないqueryだけです。

先にHTTP許可ホストへ接続先のホスト名を1行ずつ登録します。連携アクションの接続先URLには、そのホストを使うHTTPS URLだけを指定できます。AuthorizationヘッダーやX-API-Keyは直接入力せず、HTTPシークレットへ保存してリクエストヘッダーから選びます。

GETではクエリパラメーターへorder_id={{args.order_id}}&limit=10のように入力します。POST、PUT、PATCHでは送信する内容（JSON）へ{"order_id":"{{args.order_id}}"}のように入力します。DELETEには送信内容の入力欄は表示されません。応答を待つ時間は通常5秒のまま使えます。

AIエージェントを設置するページで、KotaelAgentQueueへ処理を登録します。この方法はインストールコードの読み込み前後どちらでも使えます。連携アクションのアクション名には、登録コードと同じ名前を指定します。

window.KotaelAgentQueue = window.KotaelAgentQueue || [];
window.KotaelAgentQueue.push([
  "addToCart",
  async ({ product_id }) => addProductToCart(product_id),
]);

インストールコードの読み込み後は、KotaelAgent.registerActionでも登録できます。この例では、設置先のサイトにaddProductToCartを先に実装しておく必要があります。登録した処理は、JSONとして扱える結果を返すようにしてください。アクション名が一致しない場合、処理内でエラーになった場合、または応答待ち時間を過ぎた場合は連携に失敗します。

ナレッジ検索では、AIに読み取らせる情報の項目名は変更できないqueryです。AIに伝える入力内容へ「訪問者の質問から検索文を作成します。」のように検索文の作り方を指定します。たとえば「開封しても返品できますか？」という質問から「開封済み商品の返品条件」のような検索文を作ります。

検索対象のナレッジを1件以上選び、1回の検索で取得する件数を1〜10件で設定します。必要な場合だけ検索結果に含める最低一致度を0〜1で指定してください。この連携アクションはAIアシスタントが必要と判断した場合に検索します。フローが進むたびに必ず検索する場合や、0件の行き先を決める場合は、フローのナレッジ検索ノードを使います。

実行前に訪問者へ確認を有効にすると、AIが用意した入力内容を表示し、訪問者が実行ボタンを選んだ場合だけ処理します。確認画面の見出し、実行ボタン、取り消しボタンの文言は必要に応じて変更できます。GETから別の送信方法へ変更すると、この設定は自動で有効になります。

訪問者が取り消した処理は実行されません。AIアシスタントは取り消し結果を受け取り、ほかに得られた情報があれば回答を続けます。情報の更新、削除、購入など、訪問者の状態を変える処理では確認を有効にしてください。

1. 連携アクションで変更を適用し、AIエージェントの設定を一時保存を選びます。
2. フローを編集し、AIアシスタントの対応する質問・依頼へユーザー回答の{{question.text}}など、このノードへ渡す変数を挿入します。
3. 利用できる連携アクションで使う処理を1件以上選び、連携アクションの実行上限を0〜4回で設定します。0にすると連携アクションを実行しません。
4. プレビューで、処理が必要な質問、不要な質問、入力が不足した質問、確認の実行と取り消しを試します。サイトJS連携は模擬戻り値で成功やエラーを確認します。
5. 初回は利用可能にする、更新時は変更を反映を選びます。埋め込み設定が未公開の場合は、AIエージェントを選んで公開します。

前の質問で受け取った注文番号なども使う場合は、その値を保持した変数を対応する質問・依頼へ挿入してください。過去の会話がすべて自動で渡されるわけではありません。

プレビューのデバッグログでは、AIアシスタントが選んだ連携アクションと結果を確認できます。公開後はAIエージェントの実行ログを開き、連携アクションの表示名、種別、完了・エラー・待機・取り消し・タイムアウトの状態を確認します。HTTPリクエストとサイトJS連携の結果を回答に使った場合は、訪問者の回答に参照した情報が表示されます。