feat: mark agent.default_language_code as required feat: add return_p…

…artial response to Fulfillment docs: add notes to train agent before sending queries (#140)

PiperOrigin-RevId: 380726996

protos/google/cloud/dialogflow/cx/v3/agent.proto

@@ -58,6 +58,10 @@ service Agents {
   }
 
   // Creates an agent in the specified location.
+  //
+  // Note: You should always train flows prior to sending them queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc CreateAgent(CreateAgentRequest) returns (Agent) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*}/agents"
@@ -67,6 +71,10 @@ service Agents {
   }
 
   // Updates the specified agent.
+  //
+  // Note: You should always train flows prior to sending them queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc UpdateAgent(UpdateAgentRequest) returns (Agent) {
     option (google.api.http) = {
       patch: "/v3/{agent.name=projects/*/locations/*/agents/*}"
@@ -99,6 +107,11 @@ service Agents {
   //
   // Replaces the current agent with a new one. Note that all existing resources
   // in agent (e.g. intents, entity types, flows) will be removed.
+  //
+  //
+  // Note: You should always train flows prior to sending them queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc RestoreAgent(RestoreAgentRequest) returns (google.longrunning.Operation) {
     option (google.api.http) = {
       post: "/v3/{name=projects/*/locations/*/agents/*}:restore"
@@ -159,12 +172,15 @@ message Agent {
   // Required. The human-readable name of the agent, unique within the location.
   string display_name = 2 [(google.api.field_behavior) = REQUIRED];
 
-  // Immutable. The default language of the agent as a language tag.
+  // Required. Immutable. The default language of the agent as a language tag.
   // See [Language
   // Support](https://cloud.google.com/dialogflow/cx/docs/reference/language)
   // for a list of the currently supported language codes.
   // This field cannot be set by the [Agents.UpdateAgent][google.cloud.dialogflow.cx.v3.Agents.UpdateAgent] method.
-  string default_language_code = 3 [(google.api.field_behavior) = IMMUTABLE];
+  string default_language_code = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
 
   // The list of all languages supported by the agent (except for the
   // `default_language_code`).

protos/google/cloud/dialogflow/cx/v3/entity_type.proto

@@ -55,6 +55,10 @@ service EntityTypes {
   }
 
   // Creates an entity type in the specified agent.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc CreateEntityType(CreateEntityTypeRequest) returns (EntityType) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*}/entityTypes"
@@ -64,6 +68,10 @@ service EntityTypes {
   }
 
   // Updates the specified entity type.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc UpdateEntityType(UpdateEntityTypeRequest) returns (EntityType) {
     option (google.api.http) = {
       patch: "/v3/{entity_type.name=projects/*/locations/*/agents/*/entityTypes/*}"
@@ -73,6 +81,10 @@ service EntityTypes {
   }
 
   // Deletes the specified entity type.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc DeleteEntityType(DeleteEntityTypeRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v3/{name=projects/*/locations/*/agents/*/entityTypes/*}"

protos/google/cloud/dialogflow/cx/v3/flow.proto

@@ -43,6 +43,10 @@ service Flows {
       "https://www.googleapis.com/auth/dialogflow";
 
   // Creates a flow in the specified agent.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc CreateFlow(CreateFlowRequest) returns (Flow) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*}/flows"
@@ -76,6 +80,10 @@ service Flows {
   }
 
   // Updates the specified flow.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc UpdateFlow(UpdateFlowRequest) returns (Flow) {
     option (google.api.http) = {
       patch: "/v3/{flow.name=projects/*/locations/*/agents/*/flows/*}"
@@ -86,6 +94,10 @@ service Flows {
 
   // Trains the specified flow. Note that only the flow in 'draft' environment
   // is trained.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc TrainFlow(TrainFlowRequest) returns (google.longrunning.Operation) {
     option (google.api.http) = {
       post: "/v3/{name=projects/*/locations/*/agents/*/flows/*}:train"
@@ -118,6 +130,10 @@ service Flows {
   }
 
   // Imports the specified flow to the specified agent from a binary file.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc ImportFlow(ImportFlowRequest) returns (google.longrunning.Operation) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*}/flows:import"

protos/google/cloud/dialogflow/cx/v3/fulfillment.proto

@@ -95,6 +95,17 @@ message Fulfillment {
                         type: "dialogflow.googleapis.com/Webhook"
                       }];
 
+  // Whether Dialogflow should return currently queued fulfillment response
+  // messages in streaming APIs. If a webhook is specified, it happens before
+  // Dialogflow invokes webhook.
+  // Warning:
+  // 1) This flag only affects streaming API. Responses are still queued
+  // and returned once in non-streaming API.
+  // 2) The flag can be enabled in any fulfillment but only the first 3 partial
+  // responses will be returned. You may only want to apply it to fulfillments
+  // that have slow webhooks.
+  bool return_partial_responses = 8;
+
   // The tag used by the webhook to identify which fulfillment is being called.
   // This field is required if `webhook` is specified.
   string tag = 3;

protos/google/cloud/dialogflow/cx/v3/intent.proto

@@ -22,6 +22,7 @@ import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
+import "google/protobuf/timestamp.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3";
@@ -55,6 +56,10 @@ service Intents {
   }
 
   // Creates an intent in the specified agent.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc CreateIntent(CreateIntentRequest) returns (Intent) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*}/intents"
@@ -64,6 +69,10 @@ service Intents {
   }
 
   // Updates the specified intent.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc UpdateIntent(UpdateIntentRequest) returns (Intent) {
     option (google.api.http) = {
       patch: "/v3/{intent.name=projects/*/locations/*/agents/*/intents/*}"
@@ -73,6 +82,10 @@ service Intents {
   }
 
   // Deletes the specified intent.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc DeleteIntent(DeleteIntentRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v3/{name=projects/*/locations/*/agents/*/intents/*}"
@@ -205,11 +218,11 @@ message Intent {
   // start with a letter. Keys and values can be no longer than 63 characters
   // and no more than 128 bytes.
   //
-  // Prefix "sys." is reserved for Dialogflow defined labels. Currently allowed
+  // Prefix "sys-" is reserved for Dialogflow defined labels. Currently allowed
   // Dialogflow defined labels include:
-  // * sys.head
-  // * sys.contextual
-  // The above labels do not require value. "sys.head" means the intent is a
+  // * sys-head
+  // * sys-contextual
+  // The above labels do not require value. "sys-head" means the intent is a
   // head intent. "sys.contextual" means the intent is a contextual intent.
   map<string, string> labels = 7;
 

protos/google/cloud/dialogflow/cx/v3/page.proto

@@ -57,6 +57,10 @@ service Pages {
   }
 
   // Creates a page in the specified flow.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc CreatePage(CreatePageRequest) returns (Page) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*/flows/*}/pages"
@@ -66,6 +70,10 @@ service Pages {
   }
 
   // Updates the specified page.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc UpdatePage(UpdatePageRequest) returns (Page) {
     option (google.api.http) = {
       patch: "/v3/{page.name=projects/*/locations/*/agents/*/flows/*/pages/*}"
@@ -75,6 +83,10 @@ service Pages {
   }
 
   // Deletes the specified page.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc DeletePage(DeletePageRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v3/{name=projects/*/locations/*/agents/*/flows/*/pages/*}"

protos/google/cloud/dialogflow/cx/v3/security_settings.proto

@@ -226,8 +226,10 @@ message SecuritySettings {
   // If empty, we use the default DLP inspect config.
   //
   // The template name will have one of the following formats:
-  // `projects/PROJECT_ID/inspectTemplates/TEMPLATE_ID` OR
-  // `organizations/ORGANIZATION_ID/inspectTemplates/TEMPLATE_ID`
+  // `projects/<Project ID>/inspectTemplates/<Template ID>` OR
+  // `projects/<Project ID>/locations/<Location ID>/inspectTemplates/<Template
+  // ID>` OR
+  // `organizations/<Organization ID>/inspectTemplates/<Template ID>`
   string inspect_template = 9;
 
   // Specifies how data is retained. Note that even if the data is

protos/google/cloud/dialogflow/cx/v3/session.proto

@@ -147,6 +147,20 @@ message DetectIntentRequest {
 
 // The message returned from the DetectIntent method.
 message DetectIntentResponse {
+  // Represents different DetectIntentResponse types.
+  enum ResponseType {
+    // Not specified. This should never happen.
+    RESPONSE_TYPE_UNSPECIFIED = 0;
+
+    // Partial response. e.g. Aggregated responses in a Fulfillment that enables
+    // `return_partial_response` can be returned as partial response.
+    // WARNING: partial response is not eligible for barge-in.
+    PARTIAL = 1;
+
+    // Final response.
+    FINAL = 2;
+  }
+
   // Output only. The unique identifier of the response. It can be used to
   // locate a response in the training example set or for reporting issues.
   string response_id = 1;
@@ -169,6 +183,14 @@ message DetectIntentResponse {
 
   // The config used by the speech synthesizer to generate the output audio.
   OutputAudioConfig output_audio_config = 5;
+
+  // Response type.
+  ResponseType response_type = 6;
+
+  // Indicates whether the partial response can be cancelled when a later
+  // response arrives. e.g. if the agent specified some music as partial
+  // response, it can be cancelled.
+  bool allow_cancellation = 7;
 }
 
 // The top-level message sent by the client to the
@@ -229,6 +251,12 @@ message StreamingDetectIntentRequest {
 
   // Instructs the speech synthesizer how to generate the output audio.
   OutputAudioConfig output_audio_config = 4;
+
+  // Enable partial detect intent response. If this flag is not enabled,
+  // response stream still contains only one final `DetectIntentResponse` even
+  // if some `Fulfillment`s in the agent have been configured to return partial
+  // responses.
+  bool enable_partial_response = 5;
 }
 
 // The top-level message returned from the `StreamingDetectIntent` method.
@@ -408,8 +436,9 @@ message QueryParameters {
   google.protobuf.Struct parameters = 5;
 
   // The unique identifier of the [page][google.cloud.dialogflow.cx.v3.Page] to override the [current
-  // page][QueryResult.current_page] in the session. Format: `projects/<Project
-  // ID>/locations/<Location ID>/agents/<Agent ID>/pages/<page ID>`.
+  // page][QueryResult.current_page] in the session.
+  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
+  // ID>/flows/<Flow ID>/pages/<Page ID>`.
   //
   // If `current_page` is specified, the previous state of the session will be
   // ignored by Dialogflow, including the [previous

protos/google/cloud/dialogflow/cx/v3/transition_route_group.proto

@@ -56,6 +56,10 @@ service TransitionRouteGroups {
   }
 
   // Creates an [TransitionRouteGroup][google.cloud.dialogflow.cx.v3.TransitionRouteGroup] in the specified flow.
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc CreateTransitionRouteGroup(CreateTransitionRouteGroupRequest) returns (TransitionRouteGroup) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*/flows/*}/transitionRouteGroups"
@@ -65,6 +69,10 @@ service TransitionRouteGroups {
   }
 
   // Updates the specified [TransitionRouteGroup][google.cloud.dialogflow.cx.v3.TransitionRouteGroup].
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc UpdateTransitionRouteGroup(UpdateTransitionRouteGroupRequest) returns (TransitionRouteGroup) {
     option (google.api.http) = {
       patch: "/v3/{transition_route_group.name=projects/*/locations/*/agents/*/flows/*/transitionRouteGroups/*}"
@@ -74,6 +82,10 @@ service TransitionRouteGroups {
   }
 
   // Deletes the specified [TransitionRouteGroup][google.cloud.dialogflow.cx.v3.TransitionRouteGroup].
+  //
+  // Note: You should always train a flow prior to sending it queries. See the
+  // [training
+  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
   rpc DeleteTransitionRouteGroup(DeleteTransitionRouteGroupRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v3/{name=projects/*/locations/*/agents/*/flows/*/transitionRouteGroups/*}"