FAQ Assist suggests relevant FAQ answers to human agents during a conversation with an end-user. This feature can be used to help a human agent answer common end-user questions while the human agent and end-user are in a conversation.
Agent Assist follows the conversation and parses FAQ documents stored in knowledge bases to suggest answers to end-user questions. A human agent can examine these suggestions while the conversation proceeds and make a decision about which suggestions to share with the end-user.
This document walks you through the process of using the API to implement FAQ Assist and get suggestions from this feature during runtime. You have the option of using the Agent Assist console to test your Article Suggestion results during design-time, but you must call the API directly during runtime. See the tutorials section for details about testing feature performance using the Agent Assist console.
Before you begin
Complete the following before starting this guide:
- Enable the Dialogflow API for your Google Cloud project.
Configure a conversation profile
In order to get suggestions from Agent Assist you must create a knowledge base containing your uploaded documents and configure a conversation profile. You can also perform these actions using the Agent Assist Console if you would prefer not to call the API directly.
Create a knowledge base
Before you can begin uploading documents you must first create a knowledge base
to put them in. To create a knowledge base, call the create
method on the
KnowledgeBase
type.
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: your GCP project ID
- KNOWLEDGE_BASE_DISPLAY_NAME: desired knowledge base name
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/knowledgeBases
Request JSON body:
{ "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/knowledgeBases/NDA4MTM4NzE2MjMwNDUxMjAwMA", "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME" }
The path segment after knowledgeBases
contains your new knowledge base ID.
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Create a knowledge document
You can now add documents to the knowledge base. To create a document in the
knowledge base, call the create
method on the Document
type.
Set
KnowledgeType
to FAQ
. This example uses the Cloud Storage
FAQ document that was uploaded to a publicly shared Cloud
Storage bucket. When you set up Article
Suggestion in your own system, documents must be in one of the following
formats. See the knowledge documents
documentation for more information
about document best practices.
The FAQ document can be in one of three formats:
- A public URL.
- A Cloud Storage path to a
csv
file. - A
csv
file (that you will include in the API request).
If your document is in csv
format, it must contain two columns: FAQ questions
must be listed in the first column, and the answers to each question must be
listed in the second column. Each FAQ question and its associated answer is
called an FAQ pair. Make sure that the csv
file does not contain a header
row. If your document is a public URL, it must be an FAQ page listing multiple
FAQ pairs.
See the knowledge documents documentation for best practices information.
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: your GCP project ID
- KNOWLEDGE_BASE_ID: your knowledge base ID returned from previous request
- DOCUMENT_DISPLAY_NAME: desired knowledge document name
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents
Request JSON body:
{ "displayName": "DOCUMENT_DISPLAY_NAME", "mimeType": "text/html", "knowledgeTypes": "FAQ", "contentUri": "https://cloud.google.com/storage/docs/faq" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/operations/ks-add_document-MzA5NTY2MTc5Mzg2Mzc5NDY4OA" }
The response is a long-running operation, which you can poll to check for completion.
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Create a conversation profile
A conversation profile configures a set of parameters that control the
suggestions made to an agent during a conversation. The following steps create a
ConversationProfile
with a
HumanAgentAssistantConfig
object. You can also perform these actions using the Agent Assist
Console if you would prefer not to call the API
directly.
Inline suggestions are enabled by default. Optionally, you can enable Cloud Pub/Sub notifications when you configure the conversation profile.
REST
To create a conversation profile, call thecreate
method on the
ConversationProfile
resource.
noSmallTalk
: If true
, suggestions will not be triggered after small talk
messages (such as "hi", "how are you", and so on). If false
, suggestions will
be triggered after small talk messages.
onlyEndUser
: If true
, suggestions will be triggered only after end-user
messages. If false
, suggestions will be triggered after both end-user and
human agent messages.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your GCP project ID
- KNOWLEDGE_BASE_ID: your knowledge base ID
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversationProfiles
Request JSON body:
{ "displayName": "my-conversation-profile-display-name", "humanAgentAssistantConfig": { "humanAgentSuggestionConfig": { "featureConfigs": [ { "suggestionFeature": { "type": "FAQ" }, "queryConfig": { "knowledgeBaseQuerySource": { "knowledgeBases": ["projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID"] } }, "enableEventBasedSuggestion": false, "enableInlineSuggestion": true, "SuggestionTriggerSettings": { "noSmallTalk": true, "onlyEndUser": true, } } ] } } }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID", "displayName": "my-conversation-profile-display-name", "humanAgentAssistantConfig": { ... } }
The path segment after conversationProfiles
contains your new conversation
profile ID.
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
(Optional) Set security settings
You have the option of setting security parameters to help address issues such
as data redaction and data retention. To do this, you must create a
SecuritySettings
resource, then link it to a conversation profile using the securitySettings
field.
Security settings added to a conversation profile affect the behavior of Agent Assist text messages only. The behavior of the Dialogflow interaction history is controlled by Dialogflow's security settings, which you can set using the Dialogflow CX Console.
Handle conversations at runtime
Create a conversation
When a dialog begins between an end-user and a human or virtual agent, you create a conversation. In order to see suggestions, you must also create both an end-user participant and a human agent participant and add them to the conversation. The following sections walk you through this process.
First, you must create a conversation:
REST
To create a conversation, call thecreate
method on the
Conversation
resource.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Cloud project ID
- LOCATION_ID: your location ID
- CONVERSATION_PROFILE_ID: the ID you received when creating the conversation profile
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations
Request JSON body:
{ "conversationProfile": "projects/PROJECT_ID/locations/LOCATION_ID/conversationProfiles/CONVERSATION_PROFILE_ID", }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID", "lifecycleState": "IN_PROGRESS", "conversationProfile": "projects/PROJECT_ID/locations/LOCATION_ID/conversationProfiles/CONVERSATION_PROFILE_ID", "startTime": "2018-11-05T21:05:45.622Z" }
The path segment after conversations
contains your new conversation ID.
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Create an end-user participant
You must add both end-user and human agent participants to the conversation in order to see suggestions. First, add the end-user participant to the conversation:
REST
To create an end-user participant, call the create
method on the
Participant
resource.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Cloud project ID
- LOCATION_ID: your location ID
- CONVERSATION_ID: your conversation ID
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants
Request JSON body:
{ "role": "END_USER", }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID", "role": "END_USER" }
The path segment after participants
contains your new end-user participant ID.
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Create a human agent participant
Add a human agent participant to the conversation:
REST
To create a human agent participant, call the create
method on the
Participant
resource.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Cloud project ID
- LOCATION_ID: your location ID
- CONVERSATION_ID: your conversation ID
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants
Request JSON body:
{ "role": "HUMAN_AGENT", }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID", "role": "HUMAN_AGENT" }
The path segment after participants
contains your new human agent participant
ID.
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Add and analyze a message from the human agent
Each time either participant types a message in the conversation, you need to send that message to the API for processing. Agent Assist bases its suggestions on analysis of human agent and end-user messages. In the following example, the human agent starts the conversation by asking "How may I help you?". No suggestions are returned yet in the response.
REST
To add and analyze a human agent message for the conversation, call the
analyzeContent
method on the
Participant
resource.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your GCP project ID
- CONVERSATION_ID: your conversation ID
- PARTICIPANT_ID: your human agent participant ID
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent
Request JSON body:
{ "textInput": { "text": "How may I help you?", "languageCode": "en-US" } }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "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
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Add a message from the end-user and get suggestions
In response to the agent, the end-user asks "How do I sign up?". The response contains a list of suggested answers to the end-user's question as well as a confidence score for each. All answers were drawn from the single FAQ knowledge document that we added earlier in this tutorial. The confidence threshold refers to the model's level of confidence that each FAQ suggestion is relevant to the agent's request. A higher confidence value increases the likelihood of relevant responses being returned, but can result in fewer or no responses returned if no available option meets the high threshold value. We recommend a starting confidence score value of 0.4. You can adjust this value later to improve your results if needed.
The response also includes the answer's source
, the knowledge document that
the answer came from. You should provide the suggested answers to your human
agent, who might choose to provide this information to the end-user.
REST
To add and analyze an end-user message for the conversation, call the
analyzeContent
method on the
Participant
resource.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your GCP project ID
- CONVERSATION_ID: your conversation ID
- PARTICIPANT_ID: your end-user participant ID
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent
Request JSON body:
{ "textInput": { "text": "How do I sign up?", "languageCode": "en-US" } }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "message": { "name": "projects/PROJECT_ID/conversations/fiiJBeHnQIa6Zx_DUKNlEg/messages/Rjv8ErKYS_yIqVR9SW4CpA", "content": "How may I help you?", "languageCode": "en-US", "participant": "PaZQyeiTQgCOyliHkZjs0Q", "participantRole": "HUMAN_AGENT", "createTime": "1970-01-01T00:00:00Z" }, "humanAgentSuggestionResults": [ { "suggestFaqAnswersResponse": { "faqAnswers": [ { "answer": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.", "confidence": 0.07266401, "question": "How do I sign up?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MTU0MzE0NDQwOTAwNzEyODU3NjA" }, { "answer": "Consider storing your data in a multi-regional or dual-regional bucket location if high availability is a top requirement. This ensures that your data is stored in at least two geographically separated regions, providing continued availability even in the rare event of a region-wide outage, including ones caused by natural disasters. All data, regardless of storage class, is stored redundantly across regions in these types of locations, which allows you to use storage lifecycle management without giving up high availability.", "confidence": 0.06937904, "question": "How can I maximize the availability of my data?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MzkwMjIyOTA0NDAwMjgxNjAwMA" }, { "answer": "From the Cloud Storage documentation click \"Send feedback\" near the top right of the page. This will open a feedback form. Your comments will be reviewed by the Cloud Storage team.", "confidence": 0.069021806, "question": "How do I give product feedback?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MTMxMjU2MDEwODA4NTc1OTE4MDg" }, { "answer": "Read the Pricing page for detailed information on pricing, including how Cloud Storage calculates bandwidth and storage usage.", "confidence": 0.06681696, "question": "Where can I find pricing information?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/ODUxMzkxNTA2MjQzMDIwMzkwNA" }, { "answer": "Use Object Versioning. The Object Versioning feature keeps an archived version of an object whenever you overwrite or delete the live version. If you accidentally delete an object, you can copy an archived version of it back to the live version. It's recommended that you use Object Versioning in conjunction with Object Lifecycle Management. Doing so ensures that you don't have multiple, unnecessary copies of an object, which are each subject to storage costs. Caution: Object Versioning does not protect your data if you delete the entire bucket. As an alternative, use object holds. When you place an object hold on an object, it cannot be deleted or overwritten.", "confidence": 0.06453417, "question": "How do I protect myself from accidental data deletion?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MTc3MzcyODcwOTkyODQ5Nzk3MTI" }, { "answer": "You can share an individual object with a user or group by adding an entry to that object's access control list (ACL) that grants the user or group READ permission. For step-by-step instructions, see Changing ACLs.", "confidence": 0.06336816, "question": "I want to let someone download an individual object. How do I do that?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MTAxOTkyNTI4MjQ4NTY5ODU2MA" }, { "answer": "You can simply install and use the Google Cloud CLI to download the data, even without a Google account. You do not need to activate Cloud Storage or turn on billing for this purpose. You also do not need to create credentials or authenticate to Cloud Storage.", "confidence": 0.061990723, "question": "I am just trying to download or access some data that is available to the public. How can I do that?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MTAyNDMyOTczMTkzNDA0NzQzNjg" }, { "answer": "Certain types of content are not allowed on this service; please refer to the Terms of Services and Platform Policies for details. If you believe a piece of content is in violation of our policies, report it here (select See more products, then Google Cloud Storage & Cloud Bigtable).", "confidence": 0.060459033, "question": "I believe some content hosted on your service is inappropriate, how do I report it?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/NTYzMTYxMTMwMDkxMzA4NjQ2NA" }, { "answer": "For most common Cloud Storage operations, you only need to specify the relevant bucket's name, not the project associated with the bucket. In general, you only need to specify a project identifier when creating a bucket or listing buckets in a project. For more information, see When to specify a project. To find which project contains a specific bucket: If you are searching over a moderate number of projects and buckets, use the Google Cloud Platform Console, select each project, and view the buckets it contains. Otherwise, go to the storage.bucket.get page in the API Explorer and enter the bucket's name in the bucket field. When you click Authorize and Execute, the associated project number appears as part of the response. To get the project name, use the project number in the following terminal command: gcloud projects list | grep [PROJECT_NUMBER]", "confidence": 0.05914715, "question": "I created a bucket, but don't remember which project I created it in. How can I find it?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MTQ4NTQ5ODMzMzc3Njc4NjIyNzI" }, { "answer": "Cloud Storage is designed for 99.999999999% (11 9's) annual durability, which is appropriate for even primary storage and business-critical applications. This high durability level is achieved through erasure coding that stores data pieces redundantly across multiple devices located in multiple availability zones. Objects written to Cloud Storage must be redundantly stored in at least two different availability zones before the write is acknowledged as successful. Checksums are stored and regularly revalidated to proactively verify that the data integrity of all data at rest as well as to detect corruption of data in transit. If required, corrections are automatically made using redundant data. Customers can optionally enable object versioning to add protection against accidental deletion.", "confidence": 0.05035359, "question": "How durable is my data in Cloud Storage?", "source": "projects/PROJECT_ID/knowledgeBases/NjQ2MzI1MDQwNTQ2MjYzODU5Mg/documents/NTMxOTA4MTAxMzQxMjg4ODU3Ng", "metadata": { "document_display_name": "my-document-display-name" }, "answerRecord": "projects/PROJECT_ID/answerRecords/MzMyNTc2ODI5MTY5OTM5MjUxMg" } ], "latestMessage": "projects/PROJECT_ID/conversations/fiiJBeHnQIa6Zx_DUKNlEg/messages/Rjv8ErKYS_yIqVR9SW4CpA", "contextSize": 1 } } ] }
Python
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Complete the conversation
When the conversation ends, use the API to complete the conversation.
REST
To complete the conversation, call thecomplete
method on the
conversations
resource.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your GCP project ID
- CONVERSATION_ID: the ID you received when creating the conversation
HTTP method and URL:
POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID:complete
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "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
To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
API request options
The previous sections show how to create a
ConversationProfile
in order to receive suggestions. The following sections outline some optional
functionalities that you can implement during a conversation.
Pub/Sub suggestion notifications
In the sections earlier, the
ConversationProfile
was created with only a human agent assistant. During the conversation you
needed to call the API to receive suggestions after each message was added to
the conversation. If you prefer to receive notification events for suggestions,
you can set the notificationConfig
field when creating the conversation
profile. This option uses Cloud Pub/Sub to send suggestion
notifications to your application as the conversation proceeds and new
suggestions are available.