Agent Assist の記事の候補機能は、人間のエージェントとエンドユーザー間の会話をフォローし、人間のエージェントに関連ドキュメントの候補を提供します。人間のエージェントは、会話の進行中にこれらの候補を調べ、どのドキュメントを読むか、どのドキュメントをエンドユーザーと共有するかを決定できます。記事の候補機能を使用すると、人間のエージェントは、エンドユーザーと会話しながら、エンドユーザーの問題を理解して解決できます。
Agent Assist は、記事をエージェントに提案するために使用できるベースラインの記事候補モデルを提供します。必要であれば、独自の会話型データを使用してカスタムモデルをトレーニングし、パフォーマンスを向上させることができます。記事の候補で使用するカスタム候補モデルをトレーニングする場合は、Google 担当者にお問い合わせください。
このドキュメントでは、API を使用して記事の候補を実装し、実行時にこの機能から候補を取得するプロセスについて説明します。記事の候補の結果を、設計時に Agent Assist コンソールを使用してテストすることもできますが、実行時に API を直接呼び出す必要があります。Agent Assist コンソールを使用して機能のパフォーマンスをテストする方法については、チュートリアル セクションをご覧ください。
始める前に
このガイドを開始する前に、以下を完了してください。
- GCP プロジェクトで Dialogflow API を有効にします。
- プロジェクトで Data Labeling API を有効にします。
会話プロファイルを構成する
Agent Assist から提案を取得するには、アップロードしたドキュメントを含むナレッジベースを作成し、会話プロファイルを構成する必要があります。API を直接呼び出したくない場合は、Agent Assist コンソールを使用してこれらの操作を行うこともできます。
ナレッジベースを作成する
ドキュメントのアップロードを開始する前に、まずこういったドキュメントを配置するナレッジベースを作成する必要があります。ナレッジベースを作成するには、KnowledgeBase
タイプの create
メソッドを呼び出します。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- KNOWLEDGE_BASE_DISPLAY_NAME: 目的のナレッジベース名
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/knowledgeBases
JSON 本文のリクエスト:
{ "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/knowledgeBases/NDA4MTM4NzE2MjMwNDUxMjAwMA", "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME" }
knowledgeBases
の後のパスセグメントには新しいナレッジベース ID が含まれます。
Python
ナレッジ ドキュメントを作成する
ナレッジベースにドキュメントを追加できるようになりました。ナレッジベースでドキュメントを作成するには、Document
タイプの create
メソッドを呼び出します。KnowledgeType
を ARTICLE_SUGGESTION
に設定する。この例では、一般公開されている Cloud Storage バケットにアップロードされた返品注文情報の HTML ファイルを使用します。独自のシステムで記事の候補を設定する場合、ドキュメントは次のいずれかの形式にする必要があります。ドキュメントのベストプラクティスについて詳しくは、ナレッジ ドキュメントのドキュメントをご覧ください。
ナレッジ ドキュメントの形式:
- Cloud Storage バケットに保存されているファイル。API を呼び出すときにパスを指定できます。
- ドキュメントのテキスト コンテンツで、API リクエストで送信できます。
- 公開 URL。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- KNOWLEDGE_BASE_ID: 前回のリクエストから返されたナレッジベース ID
- DOCUMENT_DISPLAY_NAME: 目的のナレッジ ドキュメント名
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents
JSON 本文のリクエスト:
{ "displayName": "DOCUMENT_DISPLAY_NAME", "mimeType": "text/html", "knowledgeTypes": "ARTICLE_SUGGESTION", "contentUri": "gs://agent-assist-public-examples/public_article_suggestion_example_returns.html" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/operations/ks-add_document-MzA5NTY2MTc5Mzg2Mzc5NDY4OA" }
レスポンスは長時間継続するオペレーションです。ポーリングして完了を確認できます。
Python
会話プロファイルを作成する
会話プロファイルでは、会話中にエージェントに提示される候補を制御する一連のパラメータを構成します。次の手順では、HumanAgentAssistantConfig
オブジェクトを使用して ConversationProfile
を作成します。API を直接呼び出したくない場合は、Agent Assist コンソールを使用してこれらの操作を行うこともできます。
初期の信頼しきい値を 0.44(以前のベースライン モデルを使用している場合は 0.1)に設定することをおすすめします。必要に応じて、推奨範囲を超えてしきい値を増やすことができます。しきい値を高くすると、精度が高くなり、カバレッジ結果が減少します(提案の削減)。しきい値を低くすると、精度が低下し、カバレッジが向上します(提案の増加)。
REST とコマンドライン
会話プロファイルを作成するには、ConversationProfile
リソースの create
メソッドを呼び出します。
noSmallTalk
: true
の場合、世間話のメッセージ(「こんにちは」や「お元気ですか」など)の後には候補はトリガーされません。false
の場合、世間話のメッセージの後に候補がトリガーされます。
onlyEndUser
: true
の場合、エンドユーザー メッセージの後にのみ候補がトリガーされます。false
の場合、エンドユーザーのメッセージの後にも、人間のエージェントのメッセージの後にも提案がトリガーされます。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- KNOWLEDGE_BASE_ID: ナレッジベース ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversationProfiles
JSON 本文のリクエスト:
{ "name": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID", "displayName": "my-conversation-profile-display-name", "humanAgentAssistantConfig": { "notificationConfig": {}, "humanAgentSuggestionConfig": { "featureConfigs": [ { "enableInlineSuggestion": true, "SuggestionTriggerSettings": { "noSmallTalk": true, "onlyEndUser": true, } "suggestionFeature": { "type": "ARTICLE_SUGGESTION" }, "queryConfig": { "knowledgeBaseQuerySource": { "knowledgeBases": [ "projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID" ] } } } ] } }, "sttConfig": {}, "languageCode": "en-US" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID", "displayName": "my-conversation-profile-display-name", "humanAgentAssistantConfig": { ... } }
conversationProfiles
の後のパスセグメントには、新しい会話プロフィール ID が含まれます。
Python
(省略可)セキュリティ設定を設定する
データ削除やデータ保持などの問題に対処するために、セキュリティ パラメータを設定することもできます。この操作を行うには、SecuritySettings
リソースを作成し、securitySettings
フィールドを使用して、リソースを会話プロファイルにリンクする必要があります。
会話プロファイルに追加されたセキュリティ設定は、Agent Assist のテキスト メッセージの動作にのみ影響します。Dialogflow の操作履歴の動作は、Dialogflow のセキュリティ設定によって制御されます。これは、Dialogflow CX コンソール を使用して設定できます。
ランタイムに会話を処理する
会話を作成する
エンドユーザーと人間または仮想エージェントとのダイアログが開始されると、会話が作成されます。候補を表示するには、エンドユーザーの参加者と人間のエージェントの参加者を両方とも作成して、会話に加える必要があります。以下のセクションでは、このプロセスについて詳しく説明します。
まず、会話を作成する必要があります。
REST とコマンドライン
会話を作成するには、Conversation
リソースの create
メソッドを呼び出します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- CONVERSATION_PROFILE_ID: 会話プロファイルの作成時に受け取った ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations
JSON 本文のリクエスト:
{ "conversationProfile": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID", }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID", "lifecycleState": "IN_PROGRESS", "conversationProfile": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID", "startTime": "2018-11-05T21:05:45.622Z" }
conversations
の後のパスセグメントには、新しい会話 ID が含まれます。
Python
エンドユーザーの参加者を作成する
候補を表示するには、エンドユーザーと人間のエージェントの両方の参加者を会話に追加する必要があります。まず、エンドユーザーを会話の参加者に追加します。
REST とコマンドライン
エンドユーザーの参加者を作成するには、Participant
リソースの create
メソッドを呼び出します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- CONVERSATION_ID: 会話 ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants
JSON 本文のリクエスト:
{ "role": "END_USER", }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID", "role": "END_USER" }
participants
の後のパスセグメントには、新しいエンドユーザー参加者 ID が含まれます。
Python
人間のエージェントの参加者を作成する
人間のエージェントの参加者を会話に追加します。
REST とコマンドライン
人間のエージェントの参加者を作成するには、Participant
リソースの create
メソッドを呼び出します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- CONVERSATION_ID: 会話 ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants
JSON 本文のリクエスト:
{ "role": "HUMAN_AGENT", }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID", "role": "HUMAN_AGENT" }
participants
の後のパスセグメントには、新しい人間のエージェントの参加者 ID が含まれます。
Python
人間のエージェントからのメッセージを追加して分析する
いずれかの参加者が会話でメッセージを入力するたびに、API にメッセージを送信して処理する必要があります。Agent Assist は、人間のエージェントとエンドユーザー メッセージの分析に基づいて提案を行います。以下の例では、人間のエージェントが「ご用件はなんでしょうか?」という質問をして会話を開始します。レスポンスでは候補がまだ返されていません。
REST とコマンドライン
会話に人間のエージェントのメッセージを追加して分析するには、Participant
リソースの analyzeContent
メソッドを呼び出します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- CONVERSATION_ID: 会話 ID
- PARTICIPANT_ID: 人間のエージェントの参加者 ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent
JSON 本文のリクエスト:
{ "textInput": { "text": "How may I help you?", "languageCode": "en-US" } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "message": { "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID", "content": "How may I help you?", "languageCode": "en-US", "participant": "PARTICIPANT_ID", "participantRole": "HUMAN_AGENT", "createTime": "2020-02-13T00:01:30.683Z" }, "humanAgentSuggestionResults": [ { "suggestArticlesResponse": { "latestMessage": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID", "contextSize": 1 } } ] } } ] }
Python
エンドユーザーからのメッセージの追加と候補の取得
人間のエージェントに応答して、エンドユーザーは「注文を返品したい」と言います。今回は、API レスポンスには、関連する信頼スコアを含む推奨ドキュメントが含まれています。このチュートリアルの前半では、ナレッジベースに 1 つのナレッジ ドキュメントを追加し、そのドキュメントを返しました。信頼スコアは 0 ~ 1 の範囲です。値が大きいほど、ドキュメントが会話に関連している可能性が高くなります。ドキュメントの最初の 100 文字を含むスニペットも返されます。このスニペットは、人間のエージェントがドキュメントが役立つかどうかを判断するのに役立ちます。推奨されるドキュメントをエンドユーザーと共有することを選択した人間のエージェントに、この情報を提供することをおすすめします。
REST とコマンドライン
エンドユーザー メッセージを会話に追加して分析するには、Participant
リソースの analyzeContent
メソッドを呼び出します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- CONVERSATION_ID: 会話 ID
- PARTICIPANT_ID: エンドユーザーの参加者 ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent
JSON 本文のリクエスト:
{ "textInput": { "text": "I want to return my order.", "languageCode": "en-US" } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "message": { "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID", "content": "I want to return my order.", "languageCode": "en-US", "participant": "PARTICIPANT_ID", "participantRole": "END_USER", "createTime": "2020-02-13T00:07:35.925Z" }, "humanAgentSuggestionResults": [ { "suggestArticlesResponse": { "articleAnswers": [ { "title": "Return an order", "uri": "gs://agent-assist-public-examples/public_article_suggestion_example_returns.html", "snippets": [ "\u003cb\u003eReturn\u003c/b\u003e an \u003cb\u003eorder\u003c/b\u003e. Follow the steps below for Made-up Store \u003cb\u003ereturns\u003c/b\u003e. At this time, \nwe don't offer exchanges. In most cases, you can drop off \u003cb\u003ereturns\u003c/b\u003e at any Made-up\n ..." ], "metadata": { "title": "Return an order", "snippet": "\n \n\n\u003ch1\u003eReturn an order\u003c/h1\u003e \nFollow the steps below for Made-up Store returns. At this time, we do...", "document_display_name": "my-kdoc" }, "answerRecord": "projects/PROJECT_ID/answerRecords/ANSWER_RECORD_ID" } ], "latestMessage": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID", "contextSize": 2 } } ] }
Python
会話を完了する
会話が終わったら、API を使用して会話を完了します。
REST とコマンドライン
会話を完了するには、conversations
リソースの complete
メソッドを呼び出します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: GCP プロジェクト ID
- CONVERSATION_ID: 会話の作成時に受け取った ID
HTTP メソッドと URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID:complete
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID", "lifecycleState": "COMPLETED", "conversationProfile": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID", "startTime": "2018-11-05T21:05:45.622Z", "endTime": "2018-11-06T03:50:26.930Z" }
Python
API リクエスト オプション
上記のセクションでは、候補を受け取るために簡単な ConversationProfile
を作成する方法を説明しています。以降のセクションでは、会話中に必要に応じて実装できる機能をいくつか説明します。
Pub/Sub 候補の通知
上記のセクションでは、ConversationProfile は人間のエージェントのアシスタントのみを使用して作成されました。各メッセージが会話に追加された後に候補を受け取るために、会話中に API を呼び出す必要がありました。候補の通知イベントを受け取る場合は、会話プロファイルの作成時に notificationConfig
フィールドを設定します。このオプションでは、Cloud Pub/Sub を使用し、会話が進行して新しい候補が利用可能になったときに、候補の通知をアプリケーションに送信します。