変数を使用して、顧客の応答を格納し、会話の後半でコンテンツを再利用できます。
変数を使用して、顧客を動的に別の会話パスにルーティングする論理式を作成することもできます。 たとえば、顧客の名前を 「customerName 」という変数に保存しておけば、エージェントが会話を続けるときに、顧客の名前を呼び出すことができます。
また、変数は他のトピックやPower Automateフローに渡したり、返したりすることができます。
変数を作成する
Question ノードなどの出力を返すノードは、適切な型の出力変数を自動的に作成します。
チップ
名前を変更し、ノードを識別しやすくします。 ノードの名前フィールドを選択して名前を直接更新するか、ノードのその他 (…) アイコンを選択してメニューから名前の変更を選択します。 コード エディター でノードの名前を変更することもできます。
トリガー ノードと 手順に進む ノードの名前を変更することはできません。
ノード名の長さは 500 文字までです。
使用するエンティティを選択する
既定では、質問ノードは複数選択式オプションで作成されます。 別の 事前構築済みエンティティまたはカスタム エンティティを使用するには、[ 識別 ] ボックスを選択し、目的の種類の情報を選択します。
変数名を変更する
変数には、作成する時に自動的に名前が付けられます。 ベスト プラクティスは、エージェントを維持する必要があるすべてのユーザーに目的を明確にするために、変数にわかりやすい名前を付ける方法です。
変数を選択します。 変数プロパティ パネルが表示されます。
[ 変数名] に、変数の目的の名前を入力します。
変数を設定する
通常、質問 ノードを使用して、ユーザー入力を変数に保存します。 ただし、変数の値を自分で設定したい場合もあります。 このような場合、変数値の設定ノードを使用します。
ノードの下にある [ ノードの追加
] アイコンを選択し、[ 変数値の設定 ] ノードを追加します。[変数の管理] を選択>変数の値を設定します。 [ 変数値の設定 ] ノードがキャンバスに表示されます。
変数の設定の下にあるボックスを選択し、新しい変数を作成するを選択します。 新しい変数が作成されました。 値を割り当てるまでその型は不明です。
対象値には、次のいずれかの方法で値を指定します:
- リテラル値を入力します。
- 同じ型の既存の変数を選択します。
- Power Fx 式を使用します。 Power Fx 式は、Table 型や Record 型などのリテラル値を使用できない、より複雑な型に有効です。
アクション ノードで変数を使用する
アクション ノードで変数を使用する場合、その基本型がフローまたは Bot Framework スキルに指定されたパラメーター型と一致する場合は、そのパラメーターに渡すことができます。 Action ノードからの出力により、新しい変数が生成されます。
詳細については、「 トピックからエージェント フローを呼び出す 」および 「入力変数と出力変数を使用して情報を渡す」のシナリオ例を参照してください。
変数の入力にリテラル値を使用する
入力パラメーターに値を設定できるノードでは、他の変数を値として選択する代わりに、常にリテラル値を入力できます。
ノードはリテラル値を文字列、数値、またはブール値として解釈を試みます。 たとえば、123 は数値として解釈されます。 文字列の値として解釈する場合は、"123" のように値を二重引用符で囲んでください。
シナリオによっては (たとえば複雑な型を使用するシナリオなど)、特定の型を設定するために Power Fx 式 を使用する必要があるかもしれません。
Azure Key Vault シークレットの環境変数を使用する
環境変数は、キー コンテナー内のシークレットを参照できます。 シークレット環境変数は、独自の考慮事項がある環境変数の特殊なケースです。
Power Apps ポータルでシークレットの環境変数を作成するには、そのキー コンテナーを構成する必要があります。
Copilot Studio にこの Key Vault の閲覧を許可するには、以下の操作を行う必要があります:
Key Vault シークレット ユーザー ロールを Microsoft Copilot Studio Service アプリケーションに割り当てます。
環境のすべてのエージェントがシークレットにアクセスすることを承認するには、シークレットに
AllowedEnvironmentsタグを作成し、許可されている環境 ID をコンマで区切って追加します。この環境から特定のエージェントだけにこの Key Vault の使用を許可するには、タグ
AllowedAgentsを作成し、エージェント識別子を{envId}/{schemaName}の形式で記述します。 複数の値を指定する場合は、カンマで区切ってください。最大文字数に達してもまだエージェントを追加する必要がある場合は、説明的で一意の名前を持つ別のタグを追加します (
AllowedAgents2など)。
シークレット値はダイアログのランタイムに 5 分間キャッシュされます。 失敗した読み取りは 30 秒間キャッシュされます。
警告
エージェントにシークレットを追加することで、このシークレットの値を公開できます。 環境内のエージェントを編集できるユーザーはだれでも 、メッセージ ノードを追加し、メッセージ内のシークレット環境変数の値を返すことができます。
変数パネル
変数 パネルでは、どのノードで定義または使用されているかに関係なく、トピックで使用できるすべての変数を表示できます。 変数ごとに、他のトピックから値を受け取るか、その値を他のトピックに返すか、またはその両方を行うかを選択できます。 また、変数プロパティ パネルで変数を選択して、そのプロパティを編集することもできます。
[変数] パネルを開くには、トピックのメニュー バーで [変数] を選択します。
![[変数] ボタンが強調表示されている [変数] パネルのスクリーンショット。](media/authoring-variables/authoring-variables-open-variable-pane.png)
![[変数] ボタンを示す作成キャンバスのスクリーンショット。](media/authoring-variables/authoring-subtopic-pass-variable-variables-bar.png)
変数のプロパティ パネル
[ 変数のプロパティ ] パネルでは、変数の名前を変更したり、エージェントが変数を使用する場所を確認したり、 グローバル変数に変換したりできます。 ただし、グローバル変数をトピック変数に戻すことはできません。 トピック変数が他のトピックから値を受け取ったり、他のトピックに値を渡したりできるかどうかを選択することもできます。
変数の 変数プロパティ ペインを開くには、変数 パネルで目的の変数を選択します。 変数を使用する任意のノードから、目的の変数を選択して[変数 プロパティ ]パネルを開くこともできます。
トピック間で変数を渡す
あるトピックを別のトピックにリダイレクトする場合、元のトピックから宛先トピックに変数の値を渡すことができ、また宛先トピックから元のトピックに値を返すこともできます。 トピック間で変数を渡すことは、後のトピックが必要とする情報がすでに収集されている場合に特に役立ちます。 ユーザーは、同じ質問に複数回回答する必要がないことに感謝しています。
他のトピックから値を受け取る
トピックが (質問ノードなどで) 変数を定義すると、エージェントは変数の値を入力するためにユーザーに質問を行います。 すでにエージェントが前のトピックで値を取得している場合は、再度質問をする必要はありません。 このような場合、変数を 他のトピックから値を受け取る ように設定することができます。 別のトピックがこのトピックにリダイレクトされるとき、この変数に変数の値 (またはリテラル値) を渡して、質問をスキップすることができます。 ユーザーからエージェントへの会話のエクスペリエンスはシームレスです。
この例では、あいさつ と 顧客との会話 の 2 つのトピックを使用します。 両方のトピックが顧客の名前を尋ねます。 ただし、あいさつのトピックが最初に実行される場合、顧客と会話するトピックはその質問をスキップします。 代わりに、あいさつ トピックから渡された変数の値を使用します。
顧客と会話するトピックのフローは次のとおりです。
テスト パネルに示すように、このトピックが最初にトリガされると、ユーザーに 「何と呼べばよいですか?」 と尋ねます。その値を customerName という文字列変数に格納します。 customerName 変数も、他のトピックから値を取得するように設定されています。 トピックの最後は、「customerName様、素晴らしい一日をお過ごしください」というメッセージで締めくくられています。
あいさつトピックのフローは次のとおりです。
テスト パネルに示すように、このトピックが最初にトリガされると、ユーザーに 「何と呼べばよいですか?」 と尋ねます。その値を customerName という文字列変数に格納します。 トピックは、「customerName様、はじめまして」というメッセージを送信します。次に、 顧客と話す トピックにリダイレクトされ、「customerName様、素晴らしい一日をお過ごしください」というメッセージが送信されます。ただし、顧客と会話する トピックでは、ユーザー名を再度尋ねる処理がスキップされていることに注意してください。 代わりに、あいさつトピックから渡された customerName 変数の値が使われました。
最後に、2 つ目の会話を再度示します。今回は顧客と会話するトピックの視点からです。
他のトピックから値を受け取るようにトピックを設定する手順を見ていきましょう。 このシナリオの例では、定義済みのトピックあいさつをソーストピックとして使用し、新しいトピック顧客との会話を宛先トピックとして使用していますが、可能な限り以前のトピックの値を使用する必要があるトピックであれば、どのトピックでも同じ手順で動作します。
宛先のトピックを設定する
宛先トピックは、リダイレクト先のトピックであり、他のトピックから値を受け取るトピックです。 この例では、顧客と会話するです。
新しいトピックを作成し、「顧客と会話する」という名前を付けます。
「私に話しかけてください」、「私と話してください」、「私とチャットしてください」などのトリガーフレーズを追加します。
質問 ノードを追加し、メッセージに何とお呼びすればいいですか?と入力します。
特定の下で、構築済みエンティティ 個人名 を選択します。
変数名を選択します。 変数のプロパティ ペインが開きます。
既定の名前を 「customerName」 に置き換えてから、他のトピックから値を受信するを選択します。
メッセージ ノードを追加します。
メッセージボックスに「素晴らしい一日をお過ごしください」と入力します。
変数の挿入 アイコン ({x}) を選択し、customerName を選択します。
変数の後のスペースを選択し、「!」と入力します。
トピックを保存します。
ソース トピックを設定する
ソース トピックはリダイレクトを行うトピックであり、値を提供し、それを宛先のトピックに渡すものです。 この例では、あいさつです。
あいさつ トピックに移動し、トリガー ノードを除くデフォルトのノードを削除します。
質問 ノードを追加し、メッセージに「お名前をお伝えください」と入力します。
特定の下で、構築済みエンティティ 個人名 を選択します。
既定の名称を「customerNameFromGreeting」に置き換えます。
メッセージ ノードを追加します。
メッセージボックスに「初めまして、」と入力します。
変数の挿入 アイコン ({x}) を選択し、customerNameFromGreeting を選択します。
変数の後のスペースを選択し、「!」と入力します。
リダイレクト ノードを追加し、宛先トピック 顧客との会話を選択します。
入力の追加を選択し、値を渡す先の宛先トピックからの変数を選択します。
> アイコンを選択し、値を渡したい変数、この例では customerNameFromGreeting を選択します。
リダイレクト ノードは次のようになります。
トピックを保存します。
値を元のトピックに戻す
エージェントでは、トピックは特定の情報を収集することを目的とします。 他の複数のトピックでそれを呼び出し、情報を変数として返すように期待できます。 変数は、元のトピックの一部になり、他の変数と同様に使用できます。 エージェントが取得する情報がトピック全体で利用できるようにし、グローバル変数 の必要性を減らすことができます。
前のセクションからの例を継続しましょう。 顧客と会話するトピック で新しい質問をし、その回答を あいさつ トピックに返します。
返される変数のソース トピックを設定する
変数をトピックに返す場合、ソース トピックは元のトピックに返す値を提供するトピックです。 この例では、ソース トピックは 顧客との会話です。
ソース トピックに移動します。
質問 ノードを追加し、メッセージに「お住まいの場所をお伝えください」と入力します。
特定 配下で、構築済みエンティティ 都市 を選択します。
変数を選択して 変数プロパティ パネルで開きます。 customerCity という名前を付け、値を元のトピックに戻す を選択します。
メッセージ ノードを追加します。
変数の挿入 アイコン ({x}) を選択し、customerCity を選択します。
メッセージ ボックスの変数の後に、「この時期はきっと素晴しいでしょうね!」と入力します。
トピックを保存します。
返される変数の宛先トピックを設定する
変数をトピックに返す場合、宛先トピックは現在のトピックから値を受け取るトピックになります。 この例では、宛先トピックは あいさつ です。
宛先のトピックに移動します。
ソース トピックで選択した変数は、リダイレクト ノードに出力変数として表示されます。
トピックを保存します。
値の解析
値の解析ノードを使用すると、ある型の値を別の型の値に変換することができます。 [値の解析] ノードの一般的なユース ケースは、生の JSON を変換することです。 たとえば、エージェントはフローを呼び出し、次に API を呼び出します。 API が計算結果を返します。 次に、この結果を解析し、1 つ以上のプリミティブ変数を返す方法が必要です。 [値の解析] ノードを使用すると、次のような文字列として API の結果全体を送信できます。
{
"Name": "Parker",
"Position": "Product manager",
"Company": "Contoso",
"FormerPositions": [{
"Position": "Customer service representative"
}
]
}
値の解析 ノードでは、現在の文字列変数を Record 型の変数に変換できます。この変数では、Power Fx エディターによる IntelliSense のコード補完と提案が提供されます。
JSON 文字列の解析に加えて、[ 値の解析 ] ノードの主な用途は、実行時に型指定されていないオブジェクトを解析することです。 最も一般的な使用例は、イベントを受信して、イベント値を解析する必要がある場合です。 または、実行時にチャネルによって異なる System.Activity.ChannelData プロパティを解析することもできます。
Teams からのイベントからの情報を解析する必要がある場合は、Teams 開発者ドキュメントを参照して、予想されるイベントの例を見つけてください。 その後、サンプル イベントをサンプル データとして使用して、このセクションの手順に従うことができます。
値の解析ノードをトピックに追加するには:
値を解析するノードの下にある [ ノードの追加
] アイコンを選択し、[ 変数の管理] をポイントして、[ 値の解析] を選択します。値の解析ノードを追加し、解析する変数を選択します。
データ型を選択します。 この場合はサンプル データからを選択します。
[ サンプル JSON からスキーマを取得] を選択し、開いたエディターで目的の JSON 例を入力して、[確認] を選択 します。
最後に、解析された値を保持する変数を選択します。 通常は、新しい変数を作成します。
これで、出力変数に、予期される型である record が含まれるようになりました。
