ステップから拡張機能を呼び出す

アクションからカスタム拡張を呼び出すには、以下のようにします。

1. アクション・エディターで、拡張機能の呼び出し元となるステップを作成するか、または開きます。

2. オプション: 「アシスタントの応答」 フィールドに、拡張機能が呼び出される前に顧客に表示されるメッセージ (例えば、 Please wait while I retrieve your account balance...) を入力します。

   このステップからの出力は、グローバル・コンテキスト変数 skip_user_input が true に設定されたチャネルに送信されます。 この変数は、メッセージを表示するようにチャネルに指示しますが、顧客に応答を求めるプロンプトを出すことは しません 。 代わりに、チャネルは空のメッセージを送信して、アシスタントが拡張機能への呼び出しを続行できるようにします。

   すべての組み込みチャネル統合 (Web チャットなど) では、 skip_user_input コンテキスト変数が考慮されます。 API を使用してカスタム・クライアントを開発する場合は、この変数のロジック検査を組み込む必要があります。 詳しくは、 ユーザー入力の処理 を参照してください。

3. ステップ・エディターで**「処理 (And then)」**をクリックします。

4. **「拡張機能の使用 (Use an extension)」**をクリックします。

5. **「拡張機能セットアップ (Extension setup)」**ウィンドウで以下の情報を指定します。

   • **「拡張機能」**フィールドで、呼び出す拡張機能を選択します。

   • **「操作」**フィールドで、実行する操作を選択します。 (_操作_は、拡張機能によってサポートされるメソッドまたは関数です。)

6. 必須入力パラメーターごとに値を指定します。 _パラメーター_は、操作に送信される入力値です。例えば、取得する顧客レコードの ID や、天気予報に使用するロケーションなどです。

   パラメーターに値を割り当てるには、その値の入力フィールドをクリックします。 次に、使用可能な変数をリストから選択するか、または値を指定する式を作成します。

   

   各パラメーターにはデータ・タイプ (_数値_や_ストリング_など) があります。 選択する変数は、パラメーターのデータ型と互換性がなければならない。詳細は、 パラメーターの互換変数を 参照。

   続行するには、すべての必須パラメーターに値を指定する必要があります。

7. 任意のオプション・パラメーターに値を指定する場合は、**「オプション・パラメーター」**をクリックします。 その後で、使用するオプション・パラメーターごとに、このプロセスを繰り返すことができます。

8. **「適用」**をクリックします。 ( **「適用」**ボタンが使用不可になっている場合は、すべての必須パラメーターに値が指定されていることを確認してください。)

ステップ・エディターの**「処理 (And then)」**セクションに、拡張機能の呼び出しの概要が表示されるようになりました。

変更が必要な場合は、**「拡張機能の編集 (Edit extension)」をクリックして「拡張機能セットアップ (Extension setup)」**ウィンドウを再び開きます。

拡張機能応答データへのアクセス

拡張機能を呼び出した後、応答データの値は、後続のステップでアクセスできる特殊なアクション変数に保管されます。

この変数には、他のアクション変数にアクセスする場合と同じ方法でアクセスできます。 これは、**「アシスタントが伝える内容 (Assistant says)」**テキスト内で参照したり、ステップ条件の一部として評価したり、他のアクションがアクセスできるようにセッション変数に割り当てたりできます。 応答変数は、使用可能な変数のリストに表示されます。応答変数は、拡張機能の名前と、呼び出し元のステップの下に分類されます。

拡張機能を呼び出すたびに、個別の応答変数セットが作成されます。 アクションがさまざまなステップから同じ拡張機能を何度も呼び出す場合は、必ず、正しいステップから変数を選択してください。

各変数は、応答本体からの値を表します。 その値に簡単にアクセスできるようにするために、データは、ネストされた複雑なオブジェクトから抽出され、個々の応答変数にマップされます。 各変数の名前は、応答本体における変数の位置を反映します (例えば、body.name や body.customer.address.zipcode)。

例えば、以下のアクション・ステップでは、拡張機能応答内の availability プロパティーを検査するために式が使用されます。

応答変数に配列が含まれている場合は、配列メソッドを使用して配列のエレメントにアクセスする式を作成できます。 例えば、ステップ条件で contains() メソッドを使用して、配列に特定の値が含まれているかどうかをテストしたり、 join() メソッドを使用して、アシスタント応答に含めることができるストリングとして配列からのデータをフォーマットしたりすることができます。 配列メソッドについて詳しくは、 配列メソッド を参照してください。

成功か失敗かの確認

カスタム拡張機能の呼び出し時に発生するエラーをアシスタントが処理できるようにすることができます。 これを行うには、拡張機能の呼び出しからの応答とともに返される Ran successfully 応答変数を確認します。 この変数はブール (true または false) 値です。

Ran successfully 変数を検査するステップ条件を定義すれば、拡張機能の呼び出しが成功したかどうかに応じてアシスタントが別々に応答できるようにするステップを作成できます。 (ステップ条件について詳しくは、ステップ条件を参照してください。)

以下の例は、ステップ 3 の拡張機能からの障害を検査するステップ条件を示しています。 この条件を使用すれば、エラーが発生したことを顧客に通知するステップを作成したり、場合によってはエージェントに連絡して追加支援を求めるように申し出たりできます。

HTTPによる条件付け

Ran successfully の変数に加えて、レスポンスHTTPに基づくステップ条件を作成することもできます。 これを行うことにより、障害の原因に応じて異なる方法で状況を処理するステップを作成できます。 例えば、タイムアウトエラー HTTP ステータス408）によりコールが失敗した場合、コールを再試行したい場合もあるでしょう。

考えられる HTTP 状況コードは多数あり、さまざまなメソッドで、成功または失敗のさまざまなタイプを示すためにさまざまな状況コードが使用されます。 HTTPを条件とするには、外部サービスがどのような HTTP ステータスコードをどのような状況で返すのかを知る必要があります。 これらのステータスコードは通常、外部APIを記述する OpenAPI ドキュメントで指定される。

HTTPに基づくステップ条件を作成するには、以下の手順に従います

1. テストする値について、 「式」 をクリックします。

2. 使用可能な変数のリストを表示するには、式フィールドにドル記号 ($) を入力します。

3. 拡張機能からの応答値である任意の変数を選択します。 (拡張応答変数である限り、どの変数を選択しても問題ありません)。

   式は自動的に更新され、選択した変数への参照がフォーマット ${step_xxx_result_y.body.variablename} で表示されます。 例えば、応答変数 body.id を選択した場合、参照は ${step_596_result_1.body.id} となると考えられます。

4. 中括弧 ({}) 内で、この参照を編集して .body.variablename を削除します。 ${step_596_result_1} のようなものを残しておく必要があります。

5. 右中括弧 (}) の後に .status を追加します。 結果の参照では、拡張機能の呼び出しから返された状況コードが識別されます (例えば、${step_596_result_1}.status)。

   式の作成について詳しくは、式の作成を参照してください。

6. 演算子と比較値を追加して式を完成させ、式がブール値 (true/false) に評価されるようにします。 例えば、以下の式はタイムアウトエラーを示す HTTP ステータス408をテストします

   ${step_549_result_1}.status==408
   

カスタム拡張機能のデバッグ失敗

拡張機能への呼び出しが失敗している場合、システムAPIに送信され、システムAPIから返される内容についての詳細な情報を見て、問題をデバッグしたいと思うかもしれない。 これを行うには、プレビューペインのインスペクタを使用します：

1. アクションページまたはアクションエディターに移動し、プレビューをクリックしてプレビューペインを開きます。

   プレビューページの {{site.data.keyword.ai-assistant}} プレビューからはインスペクタにアクセスできません。これは、顧客が目にする内容のみを表示します。 代わりに、「アクション」ページの一部であるプレビュー機能を使用してください。これにより、追加情報にアクセスできます。

2. {{site.data.keyword.ai-assistant}} に顧客として対話してください。

3. 拡張機能が呼び出されるたびに、詳細情報にアクセスできるメッセージがプリビューペインに表示されます。

   拡張機能の呼び出しに関する詳細を表示するには、 「検査」 をクリックします。

   をクリックして、インスペクタを表示または非表示にすることもできます。 ただし、内線への特定の通話に関する情報を表示するには、プレビューペインで 「検査」をクリックする必要があります。

   インスペクタの[概要] タブには、内線番号への通話に関する以下の情報が表示されま す：

   デバッグオプション	説明
   内線	拡張機能の設定で指定されている拡張機能の名前。
   操作	呼び出された操作です。
   ステータス	レスポンスの HTTP ステータスコード。 このコードは、外部サービスからエラーが返されているかどうかを判別するときに役立つ可能性があります。
   要求パラメーター	リクエストの一部としてシステムAPIに送信された入力パラメータ。
   応答プロパティー	システムAPIからの応答に含まれるすべてのプロパティの値。 これらは、拡張機能の呼び出しが完了した後にアクション変数にマップされる値です。

   「要求パラメーター」 表と 「応答プロパティー」 表では、長いプロパティー名が切り捨てられて、JSON パスの最後の部分のみが表示される場合があります。 完全なパスとプロパティー名を表示するには、テーブル内のプロパティー名の上にマウス・ポインターを移動します。

4. 未加工の要求データと応答データを表示するには、拡張インスペクターの 「拡張」 タブをクリックします。

   • 要求は cURL コマンドとして表示されます。このコマンドは、コマンド・プロンプトで実行することも、 Postmanなどのツールにインポートすることもできます。 (セキュリティー上の理由から、 Authorization ヘッダーの内容は含まれません。)
   • レスポンスは、システムAPIから返された完全なJSONデータとして表示されます。

会話型検索やスキルに基づくアクションの失敗のデバッグ

会話型検索やスキルベースのアクションの呼び出しに失敗した場合、システムAPIに送信され、システムAPIから返される内容に関する詳細情報を見て、問題をデバッグしたくなるかもしれません。

会話型検索インスペクタは、検索統合で会話型検索が有効になっている場合にのみ表示されます。 カスタムサービス検索統合を使用する場合、検索統合を構成する際にサーバーサイド検索のみを使用する必要があります。 会話型検索インスペクターでは、クライアント側の検索はサポートされていません。

問題を分析するための詳細情報を見るには、プレビュー・ペインのインスペクタを使用します：

1. アクションページに移動するか、アクションエディターでプレビューをクリックしてプレビューペインを開きます。

   プレビューページの {{site.data.keyword.ai-assistant}} プレビューからインスペクタにアクセスすることはできません。 代わりに、「アクション」ページの一部であるプレビュー機能を使用してください。これにより、追加情報にアクセスできます。

2. {{site.data.keyword.ai-assistant}} に顧客として対話してください。

3. 内線が呼び出されるたびに、プレビュー・ペインに詳細情報にアクセスするためのメッセージが表示されます： アイコンをクリックして、拡張インスペクターを表示または非表示にすることもできます。 検索統合への特定の呼び出しに関する情報を表示するには、プレビューペインで Inspect をクリックします。

4. 会話型検索への呼び出しが失敗する理由を見つけるには 、[概要] タブを使用します。

   概要」タブに表示されるフィールドについて知る前に、検索拡張機能の2つのフェーズを理解する。

   • 回収段階

     外部の文書検索エンジンが呼び出され、最初の結果セットを取得する初期検索フェーズを表す。

   • 回答生成段階

     検索フェーズでデータが検索され、LLMに送られ、ユーザーのために人間が読める回答を生成するフェーズを表す。

   Inspector]の[Overview]タブには、検索統合の呼び出しに関する以下の情報が表示されます。

   デバッグオプション	説明
   内線	拡張機能の設定で指定されている拡張機能の名前。
   索引	検索で使用するElasticsearchインデックスの名前で、検索拡張機能がElasticsearchを使用するように設定されている場合にのみ表示されます。
   プロジェクト ID	検索の検索フェーズでIBM Watson® Discoveryが使用するプロジェクトのID。 このフィールドは、IBM Watson® Discoveryを使用するように検索拡張機能を設定した場合にのみ表示されます。
   照会	システムがドキュメントエンジンElasticsearch、IBM Watson® Discoveryまたはカスタムサービスのサーバーサイド）で検索を開始する際に使用するクエリ。 このフィールドの値は、システムが書き換えたクエリを反映する。
   オリジナルクエリー	ユーザーが検索を開始したクエリ。 このフィールドは、マルチターン会話型検索が有効になっているときに、システムがクエリを書き換えるときにのみ表示されます。
   カスタム結果フィルター	会話型検索をトリガーした検索トリガーにカスタム結果フィルターが指定されている場合、そのカスタム結果フィルターを表示します。 このフィールドは常に回答に表示されるとは限りません。
   LLMタイプ	回答生成フェーズで呼び出された LLM。 この値は watsonx.ai である。 {{site.data.keyword.ai-assistant}} でのLLMの設定についてさらに詳しく知りたい場合は、Base LLMを参照してください。
   モデル	検索の回答生成フェーズでベースLLMが使用するモデル。
   ストリーム閉鎖の理由	ストリームが終了またはクローズされた理由を、UIに対応する値とともに示す。 このフィールドはウェブチャットでストリーミングを有効にした場合のみ表示されます。
   LLM入力トークン数	検索のアンサー生成フェーズでLLMに送られたリクエストのトークン数を示す。
   LLM生成トークン数	検索の回答生成フェーズで、LLM が回答するトークンの数を示す。
   IDKの反応	このフィールドは、検索の答えがIDK（I don't know）レスポンスに解決された場合にのみ表示されます。
   理由は不明	検索回答がシステムによってIDK（わからない）回答に解決された理由は、対応する値とともに表示されます。
   IDKトリガー・オープニング・フレーズ	このフィールドには、IDK（わからない）応答のトリガーとなった検出された標準的な冒頭フレーズが表示され、IDKの理由がこのフレーズに起因する場合にのみ表示されます。
   IDKトリガーフレーズ	このフィールドには、IDK(わからない)応答の原因となった検出されたトリガーフレーズが表示され、IDKの理由がこのフレーズに起因する場合にのみ表示される。
   帰国までの合計時間	システムが会話型検索の実行を完了するまでに要した時間の合計。
   検索時間	検索フェーズにおいて、システムが検索エンジンを呼び出し、結果を取得するのにかかる時間。
   回答生成時間	システムが検索の回答生成フェーズを完了するのにかかる時間。
   信頼閾値	検索の信頼度しきい値を表す数値。 {{site.data.keyword.ai-assistant}} の設定では、「わからない」と答える傾向としても知られている。
   抽出性	得点は、回答がどれだけ情報源から直接引用されているかを反映している。 スコアが高いほど、より直接的な引用であることを示し、スコアが低いほど、出典の言い換えや出典のサポートがないことを示す。
   検索の信頼性	確信度は、検索結果に対するシステムの確信度を示す。 閾値を下回る場合、システムは「IDK」と「検索信頼度が低すぎる」という理由で応答します。
   回答自信	確信度は、生成された答えに対するシステムの確信度を示す。 もし閾値を下回っていれば、システムはIDKとその理由 Response confidence too low を返答する。

欠落している拡張機能の再構成

誰かが 「統合 (Integrations)」 ページでアシスタントから削除した場合、またはアクションがエクスポートされてから、必要な拡張が構成されていない別のアシスタントにインポートされた場合、拡張機能が使用不可になることがあります。 これが発生すると、拡張機能を呼び出すすべてのアクション・ステップが無効になります。

この問題を訂正するには、以下のステップを実行します。

1. 必要に応じて、以前に使用したものと同じ OpenAPI 仕様を使用して拡張を再作成します。 (詳しくは、 カスタム拡張の作成 を参照してください。)

2. 拡張機能がアシスタントに追加されていることを確認してください。 (詳しくは、 アシスタントへの拡張機能の追加 を参照してください。)

3. アクション・エディターで、拡張機能を呼び出すアクション・ステップを編集し、拡張機能への呼び出しが正しく構成されているかどうかを確認します。 watsonx Assistant が必要な拡張機能を認識した場合、拡張機能の構成は自動的に復元されます。

   メッセージ Extension not fully configured が表示された場合、これは watsonx Assistant が必要な拡張機能を検出しなかったことを意味します。 「拡張の編集」 をクリックします。

4. 内線設定ウィンドウで、電話をかけたい内線を選択します。

   watsonx Assistant が、同じ OpenAPI 文書を使用して作成された使用可能な拡張機能を認識すると、この拡張機能を選択したことを示すメッセージが表示されます。 ただし、使用可能な任意の拡張機能を選択できます。

5. 「操作」 フィールドと 「パラメーター」 フィールドに正しい値が指定されていることを確認します。

6. **「適用」**をクリックします。

7. アクションの作成に使用した拡張機能とは異なる拡張機能を選択した場合は、拡張機能の応答プロパティーにアクセスする後続のステップを変更する必要が生じることがあります。 応答プロパティーを参照する後続のステップを確認し、参照がまだ有効で正しいことを確認してください。