--- sourceDocument: Yokohama 対話型インターフェース sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/yokohama/conversational-interfaces Release : - yokohama ft:locale : - ja-JP ft:publication_title : - Yokohama 対話型インターフェース ft:clusterId : - convint bundleId : - convint workflow : - Platform --- # 仮想エージェントスクリプト # 仮想エージェントスクリプト {#ariaid-title1} * リリースバージョン: Yokohama * * 更新日 2025年01月29日 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：14分 ServiceNow® 仮想エージェントスクリプトのメソッドと変数を使用して、応答、トリガー、フロースクリプトなどのチャットスクリプトを記述します。変数は、ライブサポートトピックと会話のコンテキストを提供することもできます。仮想エージェントスクリプトによって、ユーザーまたはユーザーの入力に関する情報を保持するなど、トピックの文脈を提供できます。この情報を使って、スクリプトによる挨拶や確認を表示するなど、会話をカスタマイズできます。スクリプトは、会話中に得られた情報に対して実行される特定のアクションを指定することもできます。これらのアクションは、ServiceNow レコードの作成や更新に使用できます。スクリプトは、トピックが定義されているスコープ内のサーバーで実行されます。すべてのスコープの保護が適用されます。スコープ対象のアプリケーション向けに会話を開発する場合は、スコープ付き API を使用する必要があります。サーバースクリプトで実行されるほとんどの API を使用できます。 ## ユーザー入力と ServiceNow レコード変数 {#virtual-agent-scripts__section_ssh_pxw_sdb} 仮想エージェントでは、トピックに対して作成するスクリプトで次の変数を使用できます。ユーザー入力変数 : 入力コントロールをトピックに追加すると、システムは自動的にユーザー入力 (文字列、ブール値など) を格納する変数を作成します。構文は `vaInputs.myvar` であり、`myvar` は入力ノードに割り当てた名前です。たとえば、First prompt という名前を含むテキスト入力プロンプトには、`vaInputs.first_prompt` と呼ばれるシステム定義の変数があります。名前に含まれるスペースはアンダースコア文字に置き換えられ、大文字は小文字に変更されます。 ServiceNow レコード変数 : ServiceNow テーブルをクエリするトピック向けにスクリプトを作成すると、返されたレコードオブジェクト (GlideRecord) は自動的にトピックで使用できるようになります。変数の構文は `vaInputs.myvar` であり、`myvar` はレコードオブジェクトです。ServiceNow テーブルをクエリしてレコードオブジェクトを返す方法の詳細については、「[スクリプトでのテーブルのクエリ](https://www.servicenow.com/docs/access?context=c_UsingGlideRecordToQueryTables&version=yokohama&pubname=yokohama-api-reference&ft:locale=en-US)」を参照してください。 ServiceNow レコードを含む変数でドット連結を使用して、テーブル内の特定のフィールドを指定します。構文は `vaInputs.myvar.field `です。スクリプト内でのドット連結の詳細については、「[ドット連結の例](https://www.servicenow.com/docs/access?context=dot-walking-examples&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US)」を参照してください。ユーザー入力と ServiceNow レコード変数へのアクセス : vaInputs オブジェクトを使用して、スクリプトの ServiceNow レコード変数にアクセスします。たとえば、`vaInputs.myvar == "expected value"` のようにします。レコードではないユーザー入力から値にアクセスするには、`vaInputs.myvar.getValue()` を使用します。以下の方法があります。 {#virtual-agent-scripts__table_uht_pzs_cpb__entry__2} | 手法 | 説明 | |-|-| | vaInputs.myvar == "expected value" | `myvar` が期待値と一致するかどうかを評価します。注: ユーザー入力変数の値は、ユーザー入力コントロールを使用して割り当てられます。これらの値は、スクリプトでは変更できません。 * Yokohama リリースでは、追加のデータタイプがサポートされています。詳細については、「[仮想エージェントトピックの入力データタイプ](https://servicenow-prod.fluidtopics.net/lIzc7~fASmemPyUH1PPSeA "一般的に使用される Glide 仮想エージェント (com.glide.cs.chatbot) のデータタイプの入力は、スクリプトを記述せずに仮想エージェントデザイナーで定義できます。カスタムコントロールまたはトピックブロックの [開始] ノードで入力データタイプを定義します。")」を参照してください。 * デフォルトでは、ユーザー変数は使用可能であり、ユーザーの sys_user レコードへの参照となります。 {#virtual-agent-scripts__ul_dsz_rbt_cpb} | | vaInputs.myvar.getValue(); | 値を返します。 | | vaInputs.myvar.getDisplayValue(); | 格納された値が ServiceNow レコードでない場合、表示値を返します。ServiceNow レコードを含む変数については、このメソッドはその表の表示フィールドで定義されている表示値を戻します。次の例は、ユーザー入力のラベルと選択値を示しています。この場合、`myVar.getValue()` は 10、20、または 30 の値を返します。 `myVar.getDisplayValue()` は Apple、Orange、または Pear を返します。図 : 1. 選択リストの例 | | vaInputs.myvar.getDefaultValue(); | 確認メッセージでデフォルト値を返します。 | | vaInputs.myvar.getDefaultDisplayValue(); | 確認メッセージでデフォルト値の表示値を返します。 | | vaInputs.myvar.unbindEntity(); | NLU 予測サービスが抽出エンティティをスロット入力した入力変数の値を削除 (初期入力値からバインド解除) します。たとえば、ユーザーが確認プロンプトで選択を変更することにした場合、入力変数からエンティティの値をバインド解除できます。ユーザーが対応する入力ノードに戻ると、再度プロンプトが表示されます。注: トピックで NLU を有効にする必要があります。仮想エージェントデザイナーで、\[プロパティ\] タブを選択して NLU を設定します。NLU エンティティの定義の詳細については、「[エンティティ](https://www.servicenow.com/docs/access?context=entities&version=yokohama&pubname=yokohama-intelligent-experiences&ft:locale=en-US)」を参照してください。 | [表 : 1. vaInputs メソッド] {#virtual-agent-scripts__table_uht_pzs_cpb} ## スクリプト変数 {#virtual-agent-scripts__section_kpv_qxj_12b} ServiceNow テーブルに格納されていない情報に対してスクリプト変数を定義することができ、その情報をトピックの他の場所で共有するために使用できます。スクリプト変数は、整数、ブール値、文字列などのプリミティブを格納するワークフロースクラッチパッド変数に似ています。文字列値は、静的または動的スクリプト値のいずれかです。変数サイドバーを使用して、仮想エージェントデザイナーのトピックのスクリプト変数を定義します。図 : 2. 変数サイドバー注: スクリプト変数は、高度なスクリプティングスキルを持つトピック作成者が使用するためのものです。構文は `vaVars.myvar` であり、`myvar` は変数に割り当てた名前です。たとえば、`vaVars.myvar = value;` という変数を使用して変数に値を割り当てることができます。ユーザー入力変数とは異なり、スクリプト変数にはスクリプト内の値を割り当てることができます。トピックでのスクリプト変数の定義の詳細については、「[トピックのスクリプト変数の定義](https://servicenow-prod.fluidtopics.net/M~PQxslKWnHkViRjnYrILA "変数サイドバーを使用して、トピックのスクリプト変数を定義します。スクリプト変数には、ServiceNow テーブルにない情報を格納できます。この情報は、トピック内の任意の場所で共有できます。")」を参照してください。 ## コンテキスト変数 {#virtual-agent-scripts__section_mc5_tvw_22b} コンテキスト変数はグローバルスコープで有効ですが、システム変数はトピックのスコープ内で有効です。Web クライアント URL 内のシステムパラメーターでコンテキスト変数を使用できます。これらの変数は、`vContext` オブジェクトを使用して、会話のどこでも使用できます。これらのオプションを使用して、事前定義された変数で仮想エージェントへのリンクを作成します。次のリンク例には、`sysparm_city=milan` のパラメータが含まれています。仮想エージェントの会話を開くことに加えて、このリンクを使用すると、値が `milan` である変数 `city` が作成されます。この変数は、`vContext.city` を使用してスクリプト内でアクセスできます。 https://.service-now.com/$sn-va-web-client-app.do?sysparm_city=milan 多くのライブエージェント変数をトピックスクリプトで使用できます。これらの変数には次のようなものがあります。 * application * language * portal * search_text * short_description {#virtual-agent-scripts__ul_nvm_krg_rwb} 変数の構文は `vaContext.LiveAgent_myvar` です。ここで、`myvar` は[ライブエージェントコンテキスト変数](https://servicenow-prod.fluidtopics.net/p7gv_1R6bBpVRyDQofap3w "チャットコンテキスト変数を使用して、トピックから特定の情報を渡してライブエージェントと共有したり、ボット会話をライブエージェントにルーティングする方法を制御します。仮想エージェントには一部のデフォルト変数が含まれ、新しい変数を定義できます。")の 1 つです。`vaVars.LiveAgent_myvar = value;` を使用して変数にアクセスします。トピックスクリプトでライブエージェント変数を使用するには、仮想エージェントデザイナーでトピックを開きます。\[プロパティ\] タブで、\[ライブエージェント変数\] の横にある鉛筆アイコンを選択して、それらをトピックに追加します。仮想エージェントに含まれるライブエージェントコンテキスト変数の詳細については、「[ライブエージェントチャットのコンテキスト変数](https://servicenow-prod.fluidtopics.net/p7gv_1R6bBpVRyDQofap3w "チャットコンテキスト変数を使用して、トピックから特定の情報を渡してライブエージェントと共有したり、ボット会話をライブエージェントにルーティングする方法を制御します。仮想エージェントには一部のデフォルト変数が含まれ、新しい変数を定義できます。")」を参照してください。 {#virtual-agent-scripts__table_evl_vbd_cfc__entry__2} | 手法 | 説明 | |-|-| | vaVars.global_utterance | スキルピッカーがレンダリングされ、発言が入力されたときに更新されます。 | [表 : 2. vaVars メソッド] {#virtual-agent-scripts__table_evl_vbd_cfc} ## vaSystem メソッド {#virtual-agent-scripts__section_bdc_wtr_h2b} vaSystem オブジェクトのメソッドを使用して、さまざまなタスクを実行できます。実行できるタスクには次のようなものがあります。 * レコードに画像を添付します。 * 現在のトピックの検索に使用された検索文字列にアクセスします。 * ライブエージェントが会話を受信できることを確認します。 * ユーザーをライブエージェントにコネクトします。 {#virtual-agent-scripts__ul_rgh_w31_fpb} 注: 文書化されていないシステムメソッドの使用はお勧めしません。このようなメソッドはサポートされていないため、事前の通知なしに中止または変更される可能性があります。 {#virtual-agent-scripts__table_xvn_c5r_h2b__entry__2} | 手法 | 説明 | |-|-| | vaSystem.applyLinkTemplate(String sysId, String tableName, String actionName) | ポータルに固有の外部リンクを作成します。 | | vaSystem.attachRecordToConversation(String tableName, String sysId) | 仮想エージェントのインタラクションレコードの \[関連タスク\] リストに ServiceNow レコードを添付します。これらのレコードは、仮想エージェントの会話中に更新または作成されます。 | | vaSystem.attachToRecord(String mediaId, String tableName, String sysId) | アップロードされた画像を ServiceNow レコードに添付します。このメソッドは次のパラメーターを使用します。 * `mediaId`：添付する画像のパスです。顧客が入力した画像を使用するには、画像入力変数で `getValue()` を使用します。例： `vaInputs.image_input.getValue()` 。 * `tableName`：テーブルの名前を含む文字列です。 * `sysId`: レコードの sys_id です。 {#virtual-agent-scripts__ul_dlj_4yr_h2b} | | vaSystem.connectToAgent() | 顧客をライブエージェントに接続します。このメソッドの詳細については、[ライブエージェントへの仮想エージェント会話の転送](https://servicenow-prod.fluidtopics.net/g_kPERkMPUSl6yOkYtnbtQ "仮想エージェント会話がライブエージェントに転送されるときに使用されるチャットサポートインターフェイスなどの、ライブチャットサポートを管理します。") を参照してください。 | | vaSystem.didConnectToLiveAgent() | 現在の会話がライブエージェントに接続されたかどうかをブール値 (true または false) で返します。 | | vaSystem.getClosingMessage() | システムプロパティ com.glide.cs.general.closing_message から会話の終了メッセージを返します。(メッセージは、Microsoft Teams や Slack などのサードパーティのメッセージングアプリでは異なります)。 | | vaSystem.getConversationId() | 現在の会話の会話 ID を返します。 | | vaSystem.getGreetingMessage() | UI メッセージから「こんにちは。私は仮想エージェントです。本日のご用件をお知らせください。」という挨拶メッセージを返します。 | | vaSystem.getInteractionSysId() | 現在の会話のインタラクション ID を返します。 | | vaSystem.getSearchText() | ユーザーが最後に入力した発言を返します。 | | vaSystem.getTopicSelectionMessage() | 「問題やご要望を教えてください。リストから、私がお手伝いできる内容をご覧いただけます。」といった UI メッセージが返されます。(メッセージは、Microsoft Teams や Slack などのサードパーティのメッセージングアプリでは異なります)。このメソッドは、システムプロパティ com.glide.cs.topic_picker_msg から返されます。 | | vaSystem.getTranscript() | 会話の転写を取得します。 | | vaSystem.isLiveAgentAvailable() | ライブエージェントがボットから転送された会話を受信できるかどうかを確認します。会話をライブエージェントに転送するには、`vaSystem.connectToAgent()` を使用する前にこのメソッドを呼び出します。 | | vaSystem.isLiveAgentConfigured() | ライブチャットが有効かどうかを返します。 | | vaSystem.resetAllEntities() | 会話に記録されたすべてのエンティティをリセットします。 | | vaSystem.sendBatchedMessages() | キューに入っているメッセージをすぐに送信します。 | | vaSystem.sendSeparatorMessage() | セパレーターメッセージ行を送信し、`getClosingMessage()` から終結メッセージを返します。 | | vaSystem.sendSystemMessage(String message, Boolean showAvatar) | システムメッセージを送信し、`getGreetingMessage()` から挨拶メッセージを返します。 | | vaSystem.sendTopicPickerControl(String topicSelectionMessage, String topicPickerButtonLabel) | メッセージと \[すべて表示\] ボタンのラベルに関連付けられた値を含むトピックピッカーのコントロールを送信します。 | | vaSystem.sendSkillPickerControl(skillSelectionMessage, args) | スキルピッカーコントロールをユーザーに送信します。 `skillSelectionMessage` は、ピッカーを表示する前に表示されるメッセージです。`args` パラメーターを使用すると、追加の構成オプションを使用できます。 * `hideSkillDetails` は、スキル選択メッセージを非表示にします。デフォルトは `false` です。 * `hidePromotedTopics` は、昇格されたトピックをスキルピッカーから非表示にします。デフォルトは `false` です。 * `hideShowMeEverything` は、スキルピッカーから \[すべて表示\] ボタンを削除します。デフォルトは `false` です。 * 該当するスキルがない場合、`showNoSkillsConfigured` に「スキルが構成されていません」というメッセージが表示されます。デフォルトは `false` です。 * `appendPromotedSkillsToMsg` は、昇格されたスキルの箇条書きリストをスキル選択メッセージに追加します。デフォルトは `true` です。 {#virtual-agent-scripts__ul_lwk_dgx_22c} | | vaSystem.switchTopicByName() | ユーザーが現在の会話トピックから指定されたトピック名にジャンプできるようにします。\[X\] ボタンを使用して、ユーザーは会話を終了できます。トピックが終了すると、ユーザーはグローバルトピックを再開します。会話が終了したら、ユーザーはチャットウィンドウの下部にある \[新しい会話を開始するには、ここをクリックしてください\] を選択してトピックを再開できます。オプションの resumeBehavior パラメーターは、次のように会話フローを再開する方法を指定します。 * resumeBehavior=resume の場合、仮想エージェントは呼び出し元トピックを再開します。 * resumeBehavior=skip の場合、仮想エージェントは呼び出し元トピックをスキップします。 {#virtual-agent-scripts__ul_x2k_rxk_gtb} resumeBehavior が指定されていない場合、インスタンスのデフォルトの動作が使用されます。 | | vaSystem.switchTopicById(sysid) | このメソッドは sys_cb_topic の sysid であり、ユーザーが現在の会話トピックから指定されたトピック ID にジャンプできるようにします。\[X\] ボタンを使用して、ユーザーは会話を終了できます。トピックが終了すると、ユーザーはグローバルトピックを再開します。会話が終了したら、ユーザーはチャットウィンドウの下部にある \[新しい会話を開始するには、ここをクリックしてください\] を選択してトピックを再開できます。オプションの resumeBehavior パラメーターは、次のように会話フローを再開する方法を指定します。 * resumeBehavior=resume の場合、仮想エージェントは呼び出し元トピックを再開します。 * resumeBehavior=skip の場合、仮想エージェントは呼び出し元トピックをスキップします。 {#virtual-agent-scripts__ul_hwt_21l_gtb} resumeBehavior が指定されていない場合、インスタンスのデフォルトの動作が使用されます。 | | vaSystem.topicDiscovery(String searchTextOverride, Boolean keywordImpl) | searchTextOverride パラメーターの用語に基づいてトピックディスカバリーを実行します。このメソッドは次のパラメーターを使用します。 * `searchTextOverride`：トピックディスカバリーを実行する文字列。 * `keywordImpl`：キーワードを使用するかどうかを決定するブール値。 {#virtual-agent-scripts__ul_rq2_zst_ssb} | [表 : 3. 仮想エージェントトピックスクリプトで使用されるメソッド] {#virtual-agent-scripts__table_xvn_c5r_h2b} {#virtual-agent-scripts__table_mqd_wqp_1jb__entry__2} | 手法 | 説明 | |-|-| | sn_cs.VASystemObject.getTranscriptById(\) | 現在の仮想エージェントの会話の転写を取得します。 | [表 : 4. 仮想エージェント以外のトピックで使用できるメソッド] {#virtual-agent-scripts__table_mqd_wqp_1jb} **関連概念** * [ドメインセパレーションと仮想エージェント](https://servicenow-prod.fluidtopics.net/Lewo3OW~vQA13_TMeyJCUQ "ドメインセパレーションは、仮想エージェントアプリケーションでサポートされています。ドメインセパレーションでは、データ、プロセス、および管理タスクをドメインと呼ばれる論理的なグループに分けることができます。どのユーザーがデータを表示できるか、データにアクセスできるかなど、このアプリケーションのいくつかの側面を制御できます。") * [仮想エージェントインタラクションレコード](https://servicenow-prod.fluidtopics.net/P5Xqji70SlUrCvIzi~7FSg "仮想エージェントの会話が発生するたびに、インタラクションレコードは、インタラクション [interaction] テーブルで会話全体をキャプチャします。レコードには、会話で使用されるすべてのトピック要素と、ライブエージェントの転送が含まれます。") **関連資料** * [仮想エージェントロール](https://servicenow-prod.fluidtopics.net/4GKzLAparb9phKHDHClMtA#VA-roles "仮想エージェントは、仮想エージェントのアドミニストレーターとして操作するユーザーに複数のロールを追加します。") * [仮想エージェントトピックの入力データタイプ](https://servicenow-prod.fluidtopics.net/lIzc7~fASmemPyUH1PPSeA "一般的に使用される Glide 仮想エージェント (com.glide.cs.chatbot) のデータタイプの入力は、スクリプトを記述せずに仮想エージェントデザイナーで定義できます。カスタムコントロールまたはトピックブロックの [開始] ノードで入力データタイプを定義します。") * [NLU システムエンティティ](https://servicenow-prod.fluidtopics.net/G8uBmHj6630R~Xytamr34A "グローバルに定義された NLU エンティティを使用して、仮想エージェントが会話から抽出できるシステム情報を識別します。エンティティは、トピックの「ノードレス」入力変数として定義できます。これらの変数は、NLU サービスプロバイダー予測からスロット入力するか、トピックのスコープ外で指定できます。") * [仮想エージェントの URL パラメーター](https://servicenow-prod.fluidtopics.net/iF6b22ketWYR2ORY0L4Zlg "仮想エージェントには、アドミニストレーターがインスタンス URL に追加して、ページコンテンツのレンダリング方法を制御できるさまざまなシステムパラメーターが用意されています。") * [仮想エージェントのレイテンシフィードバック](https://servicenow-prod.fluidtopics.net/n86YeDc3BRBSzsVN5dSrRw "com.glide.cs.message.processing.enabledシステムプロパティは、生成 AI 大規模言語モデル (LLM) が仮想エージェントチャットウィジェットとNow Assistパネルで要求を処理しているときは常に要求者に通知します。")