# Dialogflow API . projects . conversations . suggestions

## Instance Methods

Close httplib2 connections.

Generates all the suggestions using generators configured in the conversation profile. A generator is used only if its trigger event is matched.

Get answers for the given query based on knowledge documents.

Suggest summary for a conversation based on specific historical messages. The range of the messages to be used for summary can be specified in the request.

### Method Details

`close()`

    Close httplib2 connections.

`generate(conversation, body=None, x__xgafv=None)`

    Generates all the suggestions using generators configured in the conversation profile. A generator is used only if its trigger event is matched.

    Args:
      conversation: string, Required. The conversation for which the suggestions are generated. Format: `projects//locations//conversations/`. The conversation must be created with a conversation profile which has generators configured in it to be able to get suggestions. (required)
      body: object, The request body.
        The object takes the form of:

    { # The request message for Conversations.GenerateSuggestions.
      "latestMessage": "A String", # Optional. The name of the latest conversation message for which the request is triggered. Format: `projects//locations//conversations//messages/`.
      "triggerEvents": [ # Optional. A list of trigger events. Only generators configured in the conversation_profile whose trigger_event is listed here will be triggered.
        "A String",
      ],
    }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response message for Conversations.GenerateSuggestions.
      "generatorSuggestionAnswers": [ # The answers generated for the conversation based on context.
        { # A GeneratorSuggestion answer.
          "answerRecord": "A String", # Answer record that uniquely identifies the suggestion. This can be used to provide suggestion feedback.
          "generatorSuggestion": { # Suggestion generated using a Generator. # Suggestion details.
            "agentCoachingSuggestion": { # Suggestion for coaching agents. # Optional. Suggestion to coach the agent.
              "agentActionSuggestions": [ # Optional. Suggested actions for the agent to take.
                { # Actions suggested for the agent. This is based on applicable instructions.
                  "agentAction": "A String", # Optional. The suggested action for the agent.
                  "duplicateCheckResult": { # Duplication check for the suggestion. # Output only. Duplicate check result for the agent action suggestion.
                    "duplicateSuggestions": [ # Output only. The duplicate suggestions.
                      { # The duplicate suggestion details. Keeping answer_record and sources together as they are identifiers for duplicate suggestions.
                        "answerRecord": "A String", # Output only. The answer record id of the past duplicate suggestion.
                        "similarityScore": 3.14, # Output only. The similarity score of between the past and current suggestion.
                        "sources": { # Sources for the suggestion. # Output only. Sources for the suggestion.
                          "instructionIndexes": [ # Output only. Source instruction indexes for the suggestion. This is the index of the applicable_instructions field.
                            42,
                          ],
                        },
                        "suggestionIndex": 42, # Output only. The index of the duplicate suggestion in the past suggestion list.
                      },
                    ],
                  },
                  "sources": { # Sources for the suggestion. # Output only. Sources for the agent action suggestion.
                    "instructionIndexes": [ # Output only. Source instruction indexes for the suggestion. This is the index of the applicable_instructions field.
                      42,
                    ],
                  },
                },
              ],
              "applicableInstructions": [ # Optional. Instructions applicable based on the current context.
                { # Agent Coaching instructions that customer can configure.
                  "agentAction": "A String", # Optional. The action that human agent should take. For example, "apologize for the slow shipping". If the users only want to use agent coaching for intent detection, agent_action can be empty
                  "condition": "A String", # Optional. The condition of the instruction. For example, "the customer wants to cancel an order". If the users want the instruction to be triggered unconditionally, the condition can be empty.
                  "displayDetails": "A String", # Optional. The detailed description of this instruction.
                  "displayName": "A String", # Optional. Display name for the instruction.
                  "duplicateCheckResult": { # Duplication check for the suggestion. # Output only. Duplication check for the AgentCoachingInstruction.
                    "duplicateSuggestions": [ # Output only. The duplicate suggestions.
                      { # The duplicate suggestion details.
                        "answerRecord": "A String", # Output only. The answer record id of the past duplicate suggestion.
                        "similarityScore": 3.14, # Output only. The similarity score of between the past and current suggestion.
                        "suggestionIndex": 42, # Output only. The index of the duplicate suggestion in the past suggestion list.
                      },
                    ],
                  },
                  "systemAction": "A String", # Optional. The action that system should take. For example, "call GetOrderTime with order_number={order number provided by the customer}". If the users don't have plugins or don't want to trigger plugins, the system_action can be empty
                },
              ],
              "sampleResponses": [ # Optional. Sample response for the Agent.
                { # Sample response that the agent can use. This could be based on applicable instructions and ingested data from other systems.
                  "duplicateCheckResult": { # Duplication check for the suggestion. # Output only. Duplicate check result for the sample response.
                    "duplicateSuggestions": [ # Output only. The duplicate suggestions.
                      { # The duplicate suggestion details. Keeping answer_record and sources together as they are identifiers for duplicate suggestions.
                        "answerRecord": "A String", # Output only. The answer record id of the past duplicate suggestion.
                        "similarityScore": 3.14, # Output only. The similarity score of between the past and current suggestion.
                        "sources": { # Sources for the suggestion. # Output only. Sources for the suggestion.
                          "instructionIndexes": [ # Output only. Source instruction indexes for the suggestion. This is the index of the applicable_instructions field.
                            42,
                          ],
                        },
                        "suggestionIndex": 42, # Output only. The index of the duplicate suggestion in the past suggestion list.
                      },
                    ],
                  },
                  "responseText": "A String", # Optional. Sample response for Agent in text.
                  "sources": { # Sources for the suggestion. # Output only. Sources for the Sample Response.
                    "instructionIndexes": [ # Output only. Source instruction indexes for the suggestion. This is the index of the applicable_instructions field.
                      42,
                    ],
                  },
                },
              ],
            },
            "freeFormSuggestion": { # Suggestion generated using free form generator. # Optional. Free form suggestion.
              "response": "A String", # Required. Free form suggestion.
            },
            "summarySuggestion": { # Suggested summary of the conversation. # Optional. Suggested summary.
              "summarySections": [ # Required. All the parts of generated summary.
                { # A component of the generated summary.
                  "section": "A String", # Required. Name of the section.
                  "summary": "A String", # Required. Summary text for the section.
                },
              ],
            },
            "toolCallInfo": [ # Optional. List of request and response for tool calls executed.
              { # Request and response for a tool call.
                "toolCall": { # Represents a call of a specific tool's action with the specified inputs. # Required. Request for a tool call.
                  "action": "A String", # Optional. The name of the tool's action associated with this call.
                  "answerRecord": "A String", # Optional. The answer record associated with this tool call.
                  "createTime": "A String", # Output only. Create time of the tool call.
                  "inputParameters": { # Optional. The action's input parameters.
                    "a_key": "", # Properties of the object.
                  },
                  "state": "A String", # Output only. State of the tool call
                  "tool": "A String", # Optional. The tool associated with this call. Format: `projects//locations//tools/`.
                  "toolDisplayDetails": "A String", # Optional. A human readable description of the tool.
                  "toolDisplayName": "A String", # Optional. A human readable short name of the tool, to be shown on the UI.
                },
                "toolCallResult": { # The result of calling a tool's action. # Required. Response for a tool call.
                  "action": "A String", # Optional. The name of the tool's action associated with this call.
                  "answerRecord": "A String", # Optional. The answer record associated with this tool call result.
                  "content": "A String", # Only populated if the response content is utf-8 encoded.
                  "createTime": "A String", # Output only. Create time of the tool call result.
                  "error": { # An error produced by the tool call. # The tool call's error.
                    "message": "A String", # Optional. The error message of the function.
                  },
                  "rawContent": "A String", # Only populated if the response content is not utf-8 encoded. (by definition byte fields are base64 encoded).
                  "tool": "A String", # Optional. The tool associated with this call. Format: `projects//locations//tools/`.
                },
              },
            ],
          },
          "sourceGenerator": "A String", # The name of the generator used to generate this suggestion. Format: `projects//locations//generators/`.
        },
      ],
      "latestMessage": "A String", # The name of the latest conversation message used as context for compiling suggestion. Format: `projects//locations//conversations//messages/`.
    }

`searchKnowledge(conversation, body=None, x__xgafv=None)`

    Get answers for the given query based on knowledge documents.

    Args:
      conversation: string, Optional. The conversation (between human agent and end user) where the search request is triggered. Format: `projects//locations//conversations/`. (required)
      body: object, The request body.
        The object takes the form of:

    { # The request message for Conversations.SearchKnowledge.
      "conversation": "A String", # Optional. The conversation (between human agent and end user) where the search request is triggered. Format: `projects//locations//conversations/`.
      "conversationProfile": "A String", # Required. The conversation profile used to configure the search. Format: `projects//locations//conversationProfiles/`.
      "endUserMetadata": { # Optional. Information about the end-user to improve the relevance and accuracy of generative answers. This will be interpreted and used by a language model, so, for good results, the data should be self-descriptive, and in a simple structure. Example: ```json { "subscription plan": "Business Premium Plus", "devices owned": [ {"model": "Google Pixel 7"}, {"model": "Google Pixel Tablet"} ] } ```
        "a_key": "", # Properties of the object.
      },
      "exactSearch": True or False, # Optional. Whether to search the query exactly without query rewrite.
      "latestMessage": "A String", # Optional. The name of the latest conversation message when the request is triggered. Format: `projects//locations//conversations//messages/`.
      "parent": "A String", # Required. The parent resource contains the conversation profile Format: 'projects/' or `projects//locations/`.
      "query": { # Represents the natural language text to be processed. # Required. The natural language text query for knowledge search.
        "languageCode": "A String", # Required. The language of this conversational query. See [Language Support](https://cloud.google.com/dialogflow/docs/reference/language) for a list of the currently supported language codes. Note that queries in the same session do not necessarily need to specify the same language.
        "text": "A String", # Required. The UTF-8 encoded natural language text to be processed. Text length must not exceed 256 characters for virtual agent interactions.
      },
      "querySource": "A String", # Optional. The source of the query in the request.
      "searchConfig": { # Configuration specific to search queries with data stores. # Optional. Configuration specific to search queries with data stores.
        "boostSpecs": [ # Optional. Boost specifications for data stores.
          { # Boost specifications for data stores. Maps from datastore name to their boost configuration. Do not specify more than one BoostSpecs for each datastore name. If multiple BoostSpecs are provided for the same datastore name, the behavior is undefined.
            "dataStores": [ # Optional. Data Stores where the boosting configuration is applied. The full names of the referenced data stores. Formats: `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}` `projects/{project}/locations/{location}/dataStores/{data_store}`
              "A String",
            ],
            "spec": [ # Optional. A list of boosting specifications.
              { # Boost specification to boost certain documents. A copy of google.cloud.discoveryengine.v1main.BoostSpec, field documentation is available at https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1alpha/BoostSpec
                "conditionBoostSpecs": [ # Optional. Condition boost specifications. If a document matches multiple conditions in the specifications, boost scores from these specifications are all applied and combined in a non-linear way. Maximum number of specifications is 20.
                  { # Boost applies to documents which match a condition.
                    "boost": 3.14, # Optional. Strength of the condition boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0. Setting to 1.0 gives the document a big promotion. However, it does not necessarily mean that the boosted document will be the top result at all times, nor that other documents will be excluded. Results could still be shown even when none of them matches the condition. And results that are significantly more relevant to the search query can still trump your heavily favored but irrelevant documents. Setting to -1.0 gives the document a big demotion. However, results that are deeply relevant might still be shown. The document will have an upstream battle to get a fairly high ranking, but it is not blocked out completely. Setting to 0.0 means no boost applied. The boosting condition is ignored.
                    "boostControlSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
                      "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
                      "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
                        { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
                          "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
                          "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
                        },
                      ],
                      "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
                      "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
                    },
                    "condition": "A String", # Optional. An expression which specifies a boost condition. The syntax and supported fields are the same as a filter expression. Examples: * To boost documents with document ID "doc_1" or "doc_2", and color "Red" or "Blue": * (id: ANY("doc_1", "doc_2")) AND (color: ANY("Red","Blue"))
                  },
                ],
              },
            ],
          },
        ],
        "filterSpecs": [ # Optional. Filter specification for data store queries. Maps from datastore name to the filter expression for that datastore. Do not specify more than one FilterSpecs for each datastore name. If multiple FilterSpecs are provided for the same datastore name, the behavior is undefined.
          { # Filter specification for data store queries.
            "dataStores": [ # Optional. The data store where the filter configuration is applied. Full resource name of data store, such as projects/{project}/locations/{location}/collections/{collectionId}/ dataStores/{dataStoreId}.
              "A String",
            ],
            "filter": "A String", # Optional. The filter expression to be applied. Expression syntax is documented at https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata#filter-expression-syntax
          },
        ],
      },
      "sessionId": "A String", # Required. The ID of the search session. The session_id can be combined with Dialogflow V3 Agent ID retrieved from conversation profile or on its own to identify a search session. The search history of the same session will impact the search result. It's up to the API caller to choose an appropriate `Session ID`. It can be a random number or some type of session identifiers (preferably hashed). The length must not exceed 36 characters.
    }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response message for Conversations.SearchKnowledge.
      "answers": [ # Most relevant snippets extracted from articles in the given knowledge base, ordered by confidence.
        { # Represents a SearchKnowledge answer.
          "answer": "A String", # The piece of text from the knowledge base documents that answers the search query
          "answerRecord": "A String", # The name of the answer record. Format: `projects//locations//answer Records/`
          "answerSources": [ # All sources used to generate the answer.
            { # The sources of the answers.
              "metadata": { # Metadata associated with the article.
                "a_key": "", # Properties of the object.
              },
              "snippet": "A String", # The relevant snippet of the article.
              "title": "A String", # The title of the article.
              "uri": "A String", # The URI of the article.
            },
          ],
          "answerType": "A String", # The type of the answer.
        },
      ],
      "rewrittenQuery": "A String", # The rewritten query used to search knowledge.
    }

`suggestConversationSummary(conversation, body=None, x__xgafv=None)`

    Suggest summary for a conversation based on specific historical messages. The range of the messages to be used for summary can be specified in the request.

    Args:
      conversation: string, Required. The conversation to fetch suggestion for. Format: `projects//locations//conversations/`. (required)
      body: object, The request body.
        The object takes the form of:

    { # The request message for Conversations.SuggestConversationSummary.
      "assistQueryParams": { # Represents the parameters of human assist query. # Optional. Parameters for a human assist query. Only used for POC/demo purpose.
        "documentsMetadataFilters": { # Key-value filters on the metadata of documents returned by article suggestion. If specified, article suggestion only returns suggested documents that match all filters in their Document.metadata. Multiple values for a metadata key should be concatenated by comma. For example, filters to match all documents that have 'US' or 'CA' in their market metadata values and 'agent' in their user metadata values will be ``` documents_metadata_filters { key: "market" value: "US,CA" } documents_metadata_filters { key: "user" value: "agent" } ```
          "a_key": "A String",
        },
      },
      "contextSize": 42, # Optional. Max number of messages prior to and including [latest_message] to use as context when compiling the suggestion. By default 500 and at most 1000.
      "latestMessage": "A String", # Optional. The name of the latest conversation message used as context for compiling suggestion. If empty, the latest message of the conversation will be used. Format: `projects//locations//conversations//messages/`.
    }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response message for Conversations.SuggestConversationSummary.
      "contextSize": 42, # Number of messages prior to and including last_conversation_message used to compile the suggestion. It may be smaller than the SuggestSummaryRequest.context_size field in the request if there weren't that many messages in the conversation.
      "latestMessage": "A String", # The name of the latest conversation message used as context for compiling suggestion. Format: `projects//locations//conversations//messages/`.
      "summary": { # Generated summary for a conversation. # Generated summary.
        "answerRecord": "A String", # The name of the answer record. Format: "projects//answerRecords/"
        "baselineModelVersion": "A String", # The baseline model version used to generate this summary. It is empty if a baseline model was not used to generate this summary.
        "text": "A String", # The summary content that is concatenated into one string.
        "textSections": { # The summary content that is divided into sections. The key is the section's name and the value is the section's content. There is no specific format for the key or value.
          "a_key": "A String",
        },
      },
    }