Knowledge connectors

Knowledge connectors complement defined intents. They parse knowledge documents (for example, FAQs or articles) to find automated responses. To configure them, you define one or more knowledge bases, which are collections of knowledge documents.

You can enable knowledge bases for your agent, so all detect intent requests can find automated responses using your knowledge bases. Alternatively, you can specify one or more knowledge bases in your individual detect intent requests.

It is common for an agent using knowledge connectors to also use defined intents. Knowledge connectors offer less response precision and control than intents. You should define your intents to handle complex user requests, and let knowledge connectors handle simple requests.

For a list of supported languages, see the Knowledge Connectors column in the languages reference.

Limitations

The knowledge connectors feature is only available for the global region.

Enable beta features

Ensure that beta features are enabled:

  1. Go to the Dialogflow ES Console.
  2. Select an agent.
  3. Click the settings button next to the agent's name.
  4. Scroll down while on the General tab and ensure that Beta Features is enabled.
  5. If you have made changes, click Save.

Create a knowledge base and document

Follow the instructions in the knowledge bases how-to to create a knowledge base and document.

Settings for knowledge connectors

You can enable or disable knowledge bases for your agent. Enabled knowledge bases will be considered for all intent matching requests that do not specify knowledge bases. To enable or disable knowledge bases:

  1. Go to the Dialogflow ES Console.
  2. Select an agent.
  3. Click Knowledge in the left sidebar menu.
  4. Select one or more knowledge bases from the list.
  5. Click Enable or Disable.

When an end-user expression also matches an intent, you can specify how strongly you prefer knowledge results:

  1. Scroll down to the Adjust Knowledge Results Preference section.
  2. Adjust the slider from weaker (preference given to intent) to stronger (preference given to knowledge). For more information, see Detect intent responses below.

Configure responses

By default, a knowledge base is configured with a single default text response populated with the best matching knowledge answer. You can change this response and add rich response messages. Knowledge responses may contain up to three answers per knowledge base, and you can reference these answers in your configured responses. To add responses:

  1. From the Knowledge page, click your knowledge base name.
  2. Scroll down to the Responses section and add responses as desired:
    1. When defining the first response, use $Knowledge.Question[1] and $Knowledge.Answer[1] where you want the question and answer to be supplied.
    2. The index for $Knowledge.Question and $Knowledge.Answer starts at 1, so increase this index when adding more responses.
  3. Click Save once you are done editing.

When defining responses, you should consider these points:

  • If the number of defined responses is greater than the number N of knowledge connector response matches, only N responses will be returned.
  • Given that the accuracy could be lower than matching explicitly defined intents, we recommend returning three responses to your users when possible.

Example:

Knowledge connector integration screenshot

Detect intent with knowledge base

When making a detect intent request, you can specify one or more knowledge bases for a possible response. Explicitly supplying knowledge bases in a request overrides the settings for enabled and disabled knowledge bases.

The samples below show you how to use the Dialogflow Console, REST API (including command line), or client libraries to detect intent. To use the API, call the detectIntent method on the Sessions type.

Web UI

You can interact with the agent and receive knowledge connector responses via the Dialogflow simulator:

  1. Follow the steps above to enable a knowledge base.
  2. Follow the steps above to define responses.
  3. Type "How do I sign up?" in the simulator.

REST

Call the detectIntent method on the Sessions type and specify the knowledge base in the queryParams field.

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/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent

Request JSON body: 

{
 "queryInput": {
   "text": {
     "text": "How do I sign up?",
     "languageCode": "en-US"
   }
 },
 "queryParams": {
   "knowledgeBaseNames": ["projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID"]
 }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  ...
  "queryResult": {
    "queryText": "How do I sign up?",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
    "intent": {
      "name": "projects/my-gcp-project/agent/intents/487c7242-a769-408a-a339-47b95e10dac4",
      "displayName": "Knowledge.KnowledgeBase.MzkzNTAyMDE3NDQxNDk3MDg4MA"
    },
    "intentDetectionConfidence": 0.99371547,
    "languageCode": "en-us",
    "knowledgeAnswers": {
      "answers": [
        {
          "answer": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
          "matchConfidenceLevel": "HIGH",
          "matchConfidence": 0.99371547
        },
        {
          "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 and Cloud Bigtable).",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0012244871
        },
        {
          "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.",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0011537358
        }
      ]
    }
  }
}

Java

To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 


import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.v2beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers.Answer;
import com.google.cloud.dialogflow.v2beta1.QueryInput;
import com.google.cloud.dialogflow.v2beta1.QueryParameters;
import com.google.cloud.dialogflow.v2beta1.QueryResult;
import com.google.cloud.dialogflow.v2beta1.SessionName;
import com.google.cloud.dialogflow.v2beta1.SessionsClient;
import com.google.cloud.dialogflow.v2beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntentKnowledge {

  // DialogFlow API Detect Intent sample with querying knowledge connector.
  public static Map<String, KnowledgeAnswers> detectIntentKnowledge(
      String projectId,
      String knowledgeBaseName,
      String sessionId,
      String languageCode,
      List<String> texts)
      throws IOException, ApiException {
    // Instantiates a client
    Map<String, KnowledgeAnswers> allKnowledgeAnswers = Maps.newHashMap();
    try (SessionsClient sessionsClient = SessionsClient.create()) {
      // Set the session name using the sessionId (UUID) and projectID (my-project-id)
      SessionName session = SessionName.of(projectId, sessionId);
      System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input
      for (String text : texts) {
        // Set the text and language code (en-US) for the query
        TextInput.Builder textInput =
            TextInput.newBuilder().setText(text).setLanguageCode(languageCode);
        // Build the query with the TextInput
        QueryInput queryInput = QueryInput.newBuilder().setText(textInput).build();

        QueryParameters queryParameters =
            QueryParameters.newBuilder().addKnowledgeBaseNames(knowledgeBaseName).build();

        DetectIntentRequest detectIntentRequest =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .setQueryParams(queryParameters)
                .build();
        // Performs the detect intent request
        DetectIntentResponse response = sessionsClient.detectIntent(detectIntentRequest);

        // Display the query result
        QueryResult queryResult = response.getQueryResult();

        System.out.format("Knowledge results:\n");
        System.out.format("====================\n");
        System.out.format("Query Text: '%s'\n", queryResult.getQueryText());
        System.out.format(
            "Detected Intent: %s (confidence: %f)\n",
            queryResult.getIntent().getDisplayName(), queryResult.getIntentDetectionConfidence());
        System.out.format(
            "Fulfillment Text: '%s'\n",
            queryResult.getFulfillmentMessagesCount() > 0
                ? queryResult.getFulfillmentMessages(0).getText()
                : "Triggered Default Fallback Intent");
        KnowledgeAnswers knowledgeAnswers = queryResult.getKnowledgeAnswers();
        for (Answer answer : knowledgeAnswers.getAnswersList()) {
          System.out.format(" - Answer: '%s'\n", answer.getAnswer());
          System.out.format(" - Confidence: '%s'\n", answer.getMatchConfidence());
        }

        KnowledgeAnswers answers = queryResult.getKnowledgeAnswers();
        allKnowledgeAnswers.put(text, answers);
      }
    }
    return allKnowledgeAnswers;
  }
}

Node.js

To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

// Imports the Dialogflow client library
const dialogflow = require('@google-cloud/dialogflow').v2beta1;
// Instantiate a DialogFlow client.
const sessionClient = new dialogflow.SessionsClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'ID of GCP project associated with your Dialogflow agent';
// const sessionId = `user specific ID of session, e.g. 12345`;
// const languageCode = 'BCP-47 language code, e.g. en-US';
// const knowledgeBaseId = `the ID of your KnowledgeBase`;
// const query = `phrase(s) to pass to detect, e.g. I'd like to reserve a room for six people`;

// Define session path
const sessionPath = sessionClient.projectAgentSessionPath(
  projectId,
  sessionId
);
const knowledgeBasePath =
  'projects/' + projectId + '/knowledgeBases/' + knowledgeBaseId + '';

// The audio query request
const request = {
  session: sessionPath,
  queryInput: {
    text: {
      text: query,
      languageCode: languageCode,
    },
  },
  queryParams: {
    knowledgeBaseNames: [knowledgeBasePath],
  },
};

const responses = await sessionClient.detectIntent(request);
const result = responses[0].queryResult;
console.log(`Query text: ${result.queryText}`);
console.log(`Detected Intent: ${result.intent.displayName}`);
console.log(`Confidence: ${result.intentDetectionConfidence}`);
console.log(`Query Result: ${result.fulfillmentText}`);
if (result.knowledgeAnswers && result.knowledgeAnswers.answers) {
  const answers = result.knowledgeAnswers.answers;
  console.log(`There are ${answers.length} answer(s);`);
  answers.forEach(a => {
    console.log(`   answer: ${a.answer}`);
    console.log(`   confidence: ${a.matchConfidence}`);
    console.log(`   match confidence level: ${a.matchConfidenceLevel}`);
  });
}

Python

To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

def detect_intent_knowledge(
    project_id, session_id, language_code, knowledge_base_id, texts
):
    """Returns the result of detect intent with querying Knowledge Connector.

    Args:
    project_id: The GCP project linked with the agent you are going to query.
    session_id: Id of the session, using the same `session_id` between requests
              allows continuation of the conversation.
    language_code: Language of the queries.
    knowledge_base_id: The Knowledge base's id to query against.
    texts: A list of text queries to send.
    """
    from google.cloud import dialogflow_v2beta1 as dialogflow

    session_client = dialogflow.SessionsClient()

    session_path = session_client.session_path(project_id, session_id)
    print("Session path: {}\n".format(session_path))

    for text in texts:
        text_input = dialogflow.TextInput(text=text, language_code=language_code)

        query_input = dialogflow.QueryInput(text=text_input)

        knowledge_base_path = dialogflow.KnowledgeBasesClient.knowledge_base_path(
            project_id, knowledge_base_id
        )

        query_params = dialogflow.QueryParameters(
            knowledge_base_names=[knowledge_base_path]
        )

        request = dialogflow.DetectIntentRequest(
            session=session_path, query_input=query_input, query_params=query_params
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print("Query text: {}".format(response.query_result.query_text))
        print(
            "Detected intent: {} (confidence: {})\n".format(
                response.query_result.intent.display_name,
                response.query_result.intent_detection_confidence,
            )
        )
        print("Fulfillment text: {}\n".format(response.query_result.fulfillment_text))
        print("Knowledge results:")
        knowledge_answers = response.query_result.knowledge_answers
        for answers in knowledge_answers.answers:
            print(" - Answer: {}".format(answers.answer))
            print(" - Confidence: {}".format(answers.match_confidence))

Detect intent responses

The response for the Sessions type detectIntent method is a DetectIntentResponse. Multiple factors affect how response fields are populated.

If a defined intent and a knowledge base are both potential matches, the match confidence of each and the knowledge results preference (see Settings for knowledge connectors) are used to determine which match is the selected match. The selected match is populated in the DetectIntentResponse.queryResult field, and other potential matches are populated in the DetectIntentResponse.alternativeQueryResults field. Both of these fields contain QueryResult messages.

If a knowledge base provides a potential match:

  • QueryResult.knowledgeAnswers is populated with a list of potential knowledge answers ordered by decreasing match confidence.
  • If rich responses have been defined for the knowledge base, QueryResult.fulfillmentMessages is populated with rich response messages.

When performing a detect intent request, it is possible for the knowledge query to fail. When this happens, defined intents will be selected, so the overall detect intent request will not fail. You can find knowledge query error information in the DetectIntentResponse.alternativeQueryResults[i].diagnosticInfo field.

Manage knowledge bases

To learn more about managing knowledge bases, see Manage knowledge bases.

Previous
API interactions
Next
Training