feat: Add new RPC IngestContextReferences, GenerateSuggestions

docs: clarified wording around phrase_sets

PiperOrigin-RevId: 733912069

Author: Google APIs

google/cloud/dialogflow/v2/audio_config.proto

@@ -292,6 +292,8 @@ message SpeechToTextConfig {
   string model = 2;
 
   // List of names of Cloud Speech phrase sets that are used for transcription.
+  // For phrase set limitations, please refer to [Cloud Speech API quotas and
+  // limits](https://cloud.google.com/speech-to-text/quotas#content).
   repeated string phrase_sets = 4 [(google.api.resource_reference) = {
     type: "speech.googleapis.com/PhraseSet"
   }];

google/cloud/dialogflow/v2/conversation.proto

@@ -117,6 +117,17 @@ service Conversations {
     option (google.api.method_signature) = "name";
   }
 
+  // Data ingestion API.
+  // Ingests context references for an existing conversation.
+  rpc IngestContextReferences(IngestContextReferencesRequest)
+      returns (IngestContextReferencesResponse) {
+    option (google.api.http) = {
+      post: "/v2/{conversation=projects/*/locations/*/conversations/*}:ingestContextReferences"
+      body: "*"
+    };
+    option (google.api.method_signature) = "conversation,context_references";
+  }
+
   // Lists messages that belong to a given conversation.
   // `messages` are ordered by `create_time` in descending order. To fetch
   // updates without duplication, send request with filter
@@ -192,6 +203,22 @@ service Conversations {
       }
     };
   }
+
+  // Generates all the suggestions using generators configured in the
+  // conversation profile. A generator is used only if its trigger event is
+  // matched.
+  rpc GenerateSuggestions(GenerateSuggestionsRequest)
+      returns (GenerateSuggestionsResponse) {
+    option (google.api.http) = {
+      post: "/v2/{conversation=projects/*/conversations/*}/suggestions:generate"
+      body: "*"
+      additional_bindings {
+        post: "/v2/{conversation=projects/*/locations/*/conversations/*}/suggestions:generate"
+        body: "*"
+      }
+    };
+    option (google.api.method_signature) = "conversation";
+  }
 }
 
 // Represents a conversation.
@@ -273,6 +300,62 @@ message Conversation {
         [(google.api.field_behavior) = OUTPUT_ONLY];
   }
 
+  // Represents a section of ingested context information.
+  message ContextReference {
+    // Contents ingested.
+    message ContextContent {
+      // Represents the format of the ingested string.
+      enum ContentFormat {
+        // Unspecified content format.
+        CONTENT_FORMAT_UNSPECIFIED = 0;
+
+        // Content was provided in JSON format.
+        JSON = 1;
+
+        // Content was provided as plain text.
+        PLAIN_TEXT = 2;
+      }
+
+      // Required. The information ingested in a single request.
+      string content = 1 [(google.api.field_behavior) = REQUIRED];
+
+      // Required. The format of the ingested string.
+      ContentFormat content_format = 2 [(google.api.field_behavior) = REQUIRED];
+
+      // Output only. The time when this information was incorporated into the
+      // relevant context reference.
+      google.protobuf.Timestamp ingestion_time = 3
+          [(google.api.field_behavior) = OUTPUT_ONLY];
+    }
+
+    // Represents the mode in which context reference contents are updated.
+    enum UpdateMode {
+      // Unspecified update mode.
+      UPDATE_MODE_UNSPECIFIED = 0;
+
+      // Context content updates are applied in append mode.
+      APPEND = 1;
+
+      // Context content updates are applied in overwrite mode.
+      OVERWRITE = 2;
+    }
+
+    // Required. The list of content updates for a context reference.
+    repeated ContextContent context_contents = 1
+        [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The mode in which context reference contents are updated.
+    UpdateMode update_mode = 2 [(google.api.field_behavior) = REQUIRED];
+
+    // Optional. The language of the information ingested, defaults to "en-US"
+    // if not set.
+    string language_code = 3 [(google.api.field_behavior) = OPTIONAL];
+
+    // Output only. The time the context reference was first created.
+    google.protobuf.Timestamp create_time = 4
+        [(google.api.field_behavior) = OUTPUT_ONLY];
+  }
+
   // Output only. Identifier. The unique identifier of this conversation.
   // Format: `projects/<Project ID>/locations/<Location
   // ID>/conversations/<Conversation ID>`.
@@ -331,6 +414,10 @@ message Conversation {
   // Output only. The telephony connection information.
   TelephonyConnectionInfo telephony_connection_info = 10
       [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The context reference updates provided by external systems.
+  map<string, ContextReference> ingested_context_references = 17
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // The request message for
@@ -485,6 +572,32 @@ message ConversationPhoneNumber {
   string phone_number = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
+// The request message for [ConversationsService.IngestContextReferences][].
+message IngestContextReferencesRequest {
+  // Required. Resource identifier of the conversation to ingest context
+  // information for. Format: `projects/<Project ID>/locations/<Location
+  // ID>/conversations/<Conversation ID>`.
+  string conversation = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "dialogflow.googleapis.com/Conversation"
+    }
+  ];
+
+  // Required. The context references to ingest. The key is the name of the
+  // context reference and the value contains the contents of the context
+  // reference. The key is used to incorporate ingested context references to
+  // enhance the generator.
+  map<string, Conversation.ContextReference> context_references = 2
+      [(google.api.field_behavior) = REQUIRED];
+}
+
+// The response message for [ConversationsService.IngestContextReferences][].
+message IngestContextReferencesResponse {
+  // All context references ingested.
+  map<string, Conversation.ContextReference> ingested_context_references = 1;
+}
+
 // The request message for
 // [Conversations.SuggestConversationSummary][google.cloud.dialogflow.v2.Conversations.SuggestConversationSummary].
 message SuggestConversationSummaryRequest {
@@ -678,6 +791,13 @@ message GenerateStatelessSuggestionRequest {
     string generator_name = 3;
   }
 
+  // Optional. A section of ingested context information. The key is the name of
+  // the context reference and the value contains the contents of the context
+  // reference. The key is used to incorporate ingested context references to
+  // enhance the generator.
+  map<string, Conversation.ContextReference> context_references = 4
+      [(google.api.field_behavior) = OPTIONAL];
+
   // Optional. Context of the conversation, including transcripts.
   ConversationContext conversation_context = 5
       [(google.api.field_behavior) = OPTIONAL];
@@ -1036,3 +1156,35 @@ message SearchKnowledgeAnswer {
     type: "dialogflow.googleapis.com/AnswerRecord"
   }];
 }
+
+// The request message for
+// [Conversations.GenerateSuggestions][google.cloud.dialogflow.v2.Conversations.GenerateSuggestions].
+message GenerateSuggestionsRequest {
+  // Required. The conversation for which the suggestions are generated. Format:
+  // `projects/<Project ID>/locations/<Location
+  // ID>/conversations/<Conversation ID>`.
+  //
+  // The conversation must be created with a conversation profile which has
+  // generators configured in it to be able to get suggestions.
+  string conversation = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "dialogflow.googleapis.com/Conversation"
+    }
+  ];
+
+  // Optional. The name of the latest conversation message for which the request
+  // is triggered. Format: `projects/<Project ID>/locations/<Location
+  // ID>/conversations/<Conversation ID>/messages/<Message ID>`.
+  string latest_message = 2 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = {
+      type: "dialogflow.googleapis.com/Message"
+    }
+  ];
+
+  // Optional. A list of trigger events. Only generators configured in the
+  // conversation_profile whose trigger_event is listed here will be triggered.
+  repeated TriggerEvent trigger_events = 3
+      [(google.api.field_behavior) = OPTIONAL];
+}

google/cloud/dialogflow/v2/generator.proto

@@ -320,6 +320,14 @@ message SummarizationSection {
 
     // Customer defined sections.
     CUSTOMER_DEFINED = 7;
+
+    // Concise version of the situation section. This type is only available if
+    // type SITUATION is not selected.
+    SITUATION_CONCISE = 9;
+
+    // Concise version of the action section. This type is only available if
+    // type ACTION is not selected.
+    ACTION_CONCISE = 10;
   }
 
   // Optional. Name of the section, for example, "situation".
@@ -354,6 +362,12 @@ message SummarizationContext {
   string output_language_code = 6 [(google.api.field_behavior) = OPTIONAL];
 }
 
+// Free form generator context that customer can configure.
+message FreeFormContext {
+  // Optional. Free form text input to LLM.
+  string text = 1 [(google.api.field_behavior) = OPTIONAL];
+}
+
 // LLM generator.
 message Generator {
   option (google.api.resource) = {
@@ -375,6 +389,9 @@ message Generator {
 
   // Required. Input context of the generator.
   oneof context {
+    // Input of free from generator to LLM.
+    FreeFormContext free_form_context = 11;
+
     // Input of prebuilt Summarization feature.
     SummarizationContext summarization_context = 13;
   }
@@ -387,6 +404,18 @@ message Generator {
   // is triggered in a conversation.
   TriggerEvent trigger_event = 5 [(google.api.field_behavior) = OPTIONAL];
 
+  // The foundation model to use for generating suggestions. If a foundation
+  // model isn't specified here, a model specifically tuned for the feature
+  // type (and version when applicable) will be used.
+  oneof foundation_model {
+    // Optional. The published Large Language Model name.
+    // * To use the latest model version, specify the model name without version
+    //   number. Example: `text-bison`
+    // * To use a stable model version, specify the version number as well.
+    //   Example: `text-bison@002`.
+    string published_model = 15 [(google.api.field_behavior) = OPTIONAL];
+  }
+
   // Output only. Creation time of this generator.
   google.protobuf.Timestamp create_time = 8
       [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -396,6 +425,12 @@ message Generator {
       [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
+// Suggestion generated using free form generator.
+message FreeFormSuggestion {
+  // Required. Free form suggestion.
+  string response = 1 [(google.api.field_behavior) = REQUIRED];
+}
+
 // Suggested summary of the conversation.
 message SummarySuggestion {
   // A component of the generated summary.
@@ -416,6 +451,10 @@ message SummarySuggestion {
 message GeneratorSuggestion {
   // The suggestion could be one of the many types
   oneof suggestion {
+    // Optional. Free form suggestion.
+    FreeFormSuggestion free_form_suggestion = 1
+        [(google.api.field_behavior) = OPTIONAL];
+
     // Optional. Suggested summary.
     SummarySuggestion summary_suggestion = 2
         [(google.api.field_behavior) = OPTIONAL];
@@ -434,4 +473,10 @@ enum TriggerEvent {
   // Conversations.GenerateStatelessSuggestion and
   // Conversations.GenerateSuggestions.
   MANUAL_CALL = 2;
+
+  // Triggers after each customer message only.
+  CUSTOMER_MESSAGE = 3;
+
+  // Triggers after each agent message only.
+  AGENT_MESSAGE = 4;
 }

google/cloud/dialogflow/v2/participant.proto

@@ -21,6 +21,7 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/dialogflow/v2/audio_config.proto";
+import "google/cloud/dialogflow/v2/generator.proto";
 import "google/cloud/dialogflow/v2/session.proto";
 import "google/protobuf/field_mask.proto";
 import "google/protobuf/struct.proto";
@@ -847,6 +848,39 @@ message SuggestFaqAnswersResponse {
   int32 context_size = 3;
 }
 
+// The response message for
+// [Conversations.GenerateSuggestions][google.cloud.dialogflow.v2.Conversations.GenerateSuggestions].
+message GenerateSuggestionsResponse {
+  // A GeneratorSuggestion answer.
+  message GeneratorSuggestionAnswer {
+    // Suggestion details.
+    GeneratorSuggestion generator_suggestion = 1;
+
+    // The name of the generator used to generate this suggestion. Format:
+    // `projects/<Project ID>/locations/<Location ID>/generators/<Generator
+    // ID>`.
+    string source_generator = 2;
+
+    // Answer record that uniquely identifies the suggestion. This can be used
+    // to provide suggestion feedback.
+    string answer_record = 3 [(google.api.resource_reference) = {
+      type: "dialogflow.googleapis.com/AnswerRecord"
+    }];
+  }
+
+  // The answers generated for the conversation based on context.
+  repeated GeneratorSuggestionAnswer generator_suggestion_answers = 1;
+
+  // The name of the latest conversation message used as context for
+  // compiling suggestion.
+  //
+  // Format: `projects/<Project ID>/locations/<Location
+  // ID>/conversations/<Conversation ID>/messages/<Message ID>`.
+  string latest_message = 2 [(google.api.resource_reference) = {
+    type: "dialogflow.googleapis.com/Message"
+  }];
+}
+
 // The request message for
 // [Participants.SuggestSmartReplies][google.cloud.dialogflow.v2.Participants.SuggestSmartReplies].
 message SuggestSmartRepliesRequest {
@@ -1098,6 +1132,10 @@ message SuggestionResult {
 
     // SuggestSmartRepliesResponse if request is for SMART_REPLY.
     SuggestSmartRepliesResponse suggest_smart_replies_response = 4;
+
+    // Suggestions generated using generators triggered by customer or agent
+    // messages.
+    GenerateSuggestionsResponse generate_suggestions_response = 9;
   }
 }