Agents

A Dialogflow CX agent is a virtual agent that handles concurrent conversations with your end-users. It is a natural language understanding module that understands the nuances of human language. Dialogflow translates end-user text or audio during a conversation to structured data that your apps and services can understand. You design and build a Dialogflow agent to handle the types of conversations required for your system.

A Dialogflow agent is similar to a human call center agent. You train them both to handle expected conversation scenarios, and your training does not need to be overly explicit.

Create an agent

To create an agent:

Console

  1. Open the Dialogflow CX Console.
  2. Create or choose a Google Cloud project.
  3. Click Create agent.
  4. Select Auto-generate to create a data store agent or select Build your own to create other kinds of agents.
  5. Complete the form for basic agent settings:
    1. You can choose any display name.
    2. Select your preferred location. Click the Edit button if you want to change advanced location settings.
    3. Select your preferred time zone.
    4. Select the default language for your agent. You cannot change the default language for an agent once it is created.
  6. Click Save.

API

If you have not already configured location settings for your project, you must configure these settings with the console before creating agents with the API. Currently, you cannot configure location settings with the API.

To create an agent, see the create method for the Agent type.

Select a protocol and version for the Agent reference:

Protocol V3 V3beta1
REST Agent resource Agent resource
RPC Agent interface Agent interface
C++ AgentsClient Not available
C# AgentsClient Not available
Go AgentsClient Not available
Java AgentsClient AgentsClient
Node.js AgentsClient AgentsClient
PHP Not available Not available
Python AgentsClient AgentsClient
Ruby Not available Not available

Agent data

Dialogflow agents serve as top-level containers for settings and data for virtual agents.

To access an agent's data:

Console

  1. Open the Dialogflow CX Console.
  2. Choose the Google Cloud project for the agent.
  3. Find the agent in the list.
  4. Click the agent display name.
  5. Update flows, pages, etc. as described in other guides.

API

See the guides for the data you want to update.

The following data is associated with agents:

For more information about how data is applied at varying levels, see the data application levels.

Agent settings

To access agent settings:

Console

  1. Open the Dialogflow CX Console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Click Agent Settings.
  5. Update the settings as desired.
  6. Click Save.

API

See the get and patch/update methods for the Agent type.

Select a protocol and version for the Agent reference:

Protocol V3 V3beta1
REST Agent resource Agent resource
RPC Agent interface Agent interface
C++ AgentsClient Not available
C# AgentsClient Not available
Go AgentsClient Not available
Java AgentsClient AgentsClient
Node.js AgentsClient AgentsClient
PHP Not available Not available
Python AgentsClient AgentsClient
Ruby Not available Not available

The following subsections describe the different categories of agent settings.

General settings

The following general settings are available for agents:

  • Display name

    A human-readable name for your agent.

  • Time zone

    The default time zone for your agent.

  • Default language

    The default language supported by your agent. Once an agent is created, the default language cannot be changed. However, you can perform the following:

    1. Export your agent to the JSON format.
    2. Unzip the downloaded file.
    3. Find the agent.json file.
    4. Update the defaultLanguageCode and supportedLanguageCodes fields to the desired values.
    5. Restore the agent to the same or different agent from step 1.
    6. Update language-specific training phrases and entity values as needed.
  • Agent lock

    • Lock the agent

      Indicates whether the agent is locked. A locked agent cannot be edited.

  • Logging settings

    • Enable Cloud Logging

      Indicates whether Cloud logging is enabled for the agent.

    • Enable interaction logging

      Indicates whether you would like Google to collect and store redacted end-user queries for quality improvement.

  • BigQuery export

    • Enable BigQuery export

      Indicates whether BigQuery export is enabled.

    • BigQuery dataset

      The BigQuery dataset name.

    • BigQuery table

      The BigQuery table name.

  • Intent Suggestions

    You can enable intent suggestions.

  • Custom payload template

    In this section, you can create descriptions and payloads for custom payload templates.

ML settings

Dialogflow uses machine learning (ML) algorithms to understand end-user inputs, match them to intents, and extract structured data. Dialogflow learns from training phrases that you provide and the language models built into Dialogflow. Based on this data, it builds a model for making decisions about which intent should be matched to an end-user input. You can apply unique ML settings for each flow of an agent, and the model created by Dialogflow is unique for each flow.

The following agent-wide ML settings are available:

  • Allow ML to correct spelling

    If this is enabled and end-user input has a spelling or grammar mistake, an intent will be matched as though it was written correctly. The detect intent response will contain the corrected end-user input. For example, if an end-user enters "I want an applle", it will be processed as though the end-user entered "I want an apple". This also applies to matches involving both system and custom entities.

    Spell correction is available in English, French, German, Spanish, and Italian. It is available in all Dialogflow CX regions.

    Warnings and best practices:

    • Spell correction can't correct ASR (automatic speech recognition) errors, so we don't recommend enabling it for agents using ASR inputs.
    • It is possible for corrected input to match the wrong intent. You can fix this by adding commonly mismatched phrases to negative examples.
    • Spell correction increases the agent's response time slightly.
    • If an agent is defined using domain-specific jargon, the corrections may be undesired.

The following flow-specific ML settings are available:

  • NLU type

    This can be one of:

  • Auto train

    If enabled, the flow is trained whenever it is updated with the console. For large flows, this may cause console UI delays, so you should disable this setting and manually train as-needed for large flows.

  • Classification threshold

    To filter out false positive results and still get variety in matched natural language inputs for your agent, you can tune the machine learning classification threshold. This setting controls the minimum intent detection confidence required for an intent match.

    If the confidence score for an intent match is less than the threshold value, then a no-match event will be invoked.

  • Training status

    Indicates whether the flow has been trained since the latest update to the flow data.

  • Train NLU

    Use this button to manually train the flow.

Speech and IVR settings

The following speech and IVR settings are available:

  • Text-to-Speech

    • Voice selection

      You can select the language and voice used for speech synthesis.

      You may enable Custom voice for your agent by selecting the custom voice option from the voice selection dropbox and specify the custom voice name in the corresponding field. The custom voice name must follow the following pattern: projects/PROJECT_ID/locations/LOCATION/models/MODEL_NAME.

      • If you are using telephony gateway, make sure the Dialogflow Service Agent service account service-PROJECT_NUMBER@gcp-sa-dialogflow.iam.gserviceaccount.com is granted with "AutoML Predictor" in your custom voice project.
      • For regular API calls, make sure the service account used to call Dialogflow is granted with "AutoML Predictor" role in your custom voice project.
  • Speech-to-Text

    • Enable auto speech adaptation

      See Auto speech adaptation.

    • Advanced speech settings

      This section provides additional, advanced settings for speech features. You can toggle these advanced settings off and on.

      These settings are available in agent settings (applies to entire agent), flow settings (applies to entire flow and overrides agent settings), page settings (applies to page and overrides flow and agent settings), and fulfillment settings (applies to fulfillment and overrides page, flow, and agent settings). A subset of these settings are available at each level, depending on the setting relevance for the level.

      Updated agent-level settings don't propagate to the flow, page, and fulfillment level when the Customize option is selected on these lower levels. If the Customize option emcompasses multiple settings and you want to update only some of them, you may also need to update other settings if you want them to be the same as the agent-level settings.

      • Model selection (Speech-to-Text)

        Sets the speech model used for speech recognition. This setting is language-specific, so you can select different models for different languages. You can also check Override request-level speech model, which will cause the selected model to be used even if a runtime API call specifies a different model.

        For Dialogflow CX Phone Gateway, see limitations.

        For more information, see Speech models.

      • End of speech sensitivity

        Controls the sensitivity for recognizing end of speech in end-user audio input. The value ranges from 0 (low sensitivity, less likely to end speech) to 100 (high sensitivity, more likely to end speech).

      • Enable advanced timeout-based end of speech sensitivity

        If this setting is enabled, the End of speech sensitivity setting value is used as a gauge to establish a relative audio silence time-out to determine the end of speech.

        If this setting is disabled (the default), the End of speech sensitivity setting value is used to determine the end of speech by the ML model provided by Google Cloud Speech-To-Text.

        While the End of speech sensitivity setting supports only the en-US language tag by default, the Enable advanced timeout-based end of speech sensitivity setting allows for configuring end of speech sensitivity for all languages and speech models supported by Dialogflow.

      • No speech timeout

        The time duration in seconds for which Dialogflow will stop waiting for end-user audio input. The default is 5 seconds, and the maximum value is 60 seconds. For this timeout, Dialogflow invokes a no-input event.

      • Barge-in

        When enabled, an end-user can interrupt Dialogflow response audio. When interrupted, Dialogflow will stop sending audio, and it will process the next end-user input.

        If there are multiple messages in the message queue, and a message was queued by a fulfillment associated with a page, flow, or agent that has barge-in enabled, then all following messages in the queue will also have barge-in enabled. In this case, The integration will stop playing audio for all of the queued messages with barge-in enabled.

      • Allow cancellation of partial response playback

        When partial response is enabled, this setting allows cancellation of a partial response playback. If a message in the message queue is created by a fulfillment that allows cancellation, playback of the message is cancelled if another message is added to the queue. This is useful when you want an initial message to start playback, but for that playback to be cancelled if a working webhook produces another message before playback of the initial message completes.

      • Audio export bucket

        If supplied, any audio data associated with a request will be saved to the Cloud Storage bucket:

        Audio Saved Applicable requests
        End-user audio input DetectIntent, StreamingDetectIntent, AnalyzeContent, StreamingAnalyzeContent
        Text-to-speech (TTS) audio synthesized for a response AnalyzeContent, StreamingAnalyzeContent

        Grant the Storage Object Creator role to the following service accounts in your project:

        • To the service account of the format one-click@df-cx-ALPHANUMERIC_VALUE-ALPHANUMERIC_VALUE.iam.gserviceaccount.com if you use a partner built-in telephony integration.

        • To the service account of the format service-PROJECT_NUMBER@gcp-sa-dialogflow.iam.gserviceaccount.com if you use the Dialogflow CX Phone Gateway integration. To find this service account in IAM, check the Include Google-provided role grants option.

      • DTMF: See DTMF for telephony integrations.

Multimodal

See Call companion.

Share settings

See Access control.

Languages settings

Add additional language support to your agent. For the full list of languages, see the language reference.

Security settings

See Security settings.

Advanced settings

Currently, the only advanced setting is for sentiment analysis.

Export and restore an agent

You can export an agent to a file, and restore an agent with that file.

An agent export includes all agent data except the following:

An agent restore overwrites all target agent data (including all flow versions) except the following:

  • Environments: All custom environments remain unchanged in the target agent. Flow versions referenced by custom environments in the target agent will continue to exist, as long as the associated environments exist. However, these stale flow versions are not listed or selectable flow versions for the agent.
  • Vertex AI Conversation Apps: The association to a Vertex AI Conversation App remains unchanged in the target agent. (In other words, the value of engine in GenAppBuilderSettings) This means that data store agents can only be restored into other existing data store agents, because the resulting agent also needs to have an association to a Vertex AI Conversation App.
  • Vertex AI Conversation Data Stores: All references to data stores will be overwritten in the target agent according to the following rules:

    • If the target agent isn't associated with an App, then it's not possible to restore an agent with data store references into it. Trying to do so results in an error message. To fix that, you can either create a new data store agent from scratch. (Alternatively, you can turn your existing agent into a data store agent by adding a data store state handler to it. In this case you'll be guided through adding an associated App to your agent.)
    • If the target agent is associated with an App, then all the data store references will be updated upon restore: their Google Cloud project ID and location will be updated to match the App of the target agent. The collection ID and data store ID will remain unchanged. This means that you need to add data stores for all the IDs with matching types into the App of the target agent prior to the restore operation.

    Example: if the source agent refers to a data store named projects/123/locations/eu-west2/collections/default_collection/dataStores/myDataStore1 and the App of the target agent is named projects/321/locations/us-east1/collections/default_collections/engines/app123, then the resulting data store reference in the target agent will become: projects/321/locations/us-east1/collections/default_collection/dataStores/myDataStore1

When exporting, you can select the export file format. If you are using source control versioning for your agent data, you should export in the JSON format. When you restore an agent, Dialogflow automatically determines the file format.

To export or restore an agent:

Console

  1. Open the Dialogflow CX Console.
  2. Choose the Google Cloud project for the agent.
  3. Click the option menu for an agent in the list.
  4. Click the Export or Restore button.
  5. Follow instructions to complete.

API

See the export and restore methods for the Agent type.

Select a protocol and version for the Agent reference:

Protocol V3 V3beta1
REST Agent resource Agent resource
RPC Agent interface Agent interface
C++ AgentsClient Not available
C# AgentsClient Not available
Go AgentsClient Not available
Java AgentsClient AgentsClient
Node.js AgentsClient AgentsClient
PHP Not available Not available
Python AgentsClient AgentsClient
Ruby Not available Not available

If the agent size exceeds the maximum limit, use the Cloud Storage option for agent export and restore.

If you use GitHub, also see the GitHub export/restore guide.

Delete an agent

In order to delete an agent, you need a role that provides full access or edit access. See the access control guide for more information.

To delete an agent:

Console

  1. Open the Dialogflow CX Console.
  2. Choose the Google Cloud project for the agent.
  3. Click the option menu for an agent in the list.
  4. Click the delete button.
  5. Confirm deletion in the dialog.

API

See the delete method for the Agent type.

Select a protocol and version for the Agent reference:

Protocol V3 V3beta1
REST Agent resource Agent resource
RPC Agent interface Agent interface
C++ AgentsClient Not available
C# AgentsClient Not available
Go AgentsClient Not available
Java AgentsClient AgentsClient
Node.js AgentsClient AgentsClient
PHP Not available Not available
Python AgentsClient AgentsClient
Ruby Not available Not available

If you delete your project, all Dialogflow CX agents and data associated with the project are deleted immediately.