legacy-libs/google-proto-files/google/cloud/dialogflow/v2beta1/agent.proto

   1 // Copyright 2018 Google LLC
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 syntax = "proto3";
  16
  17 package google.cloud.dialogflow.v2beta1;
  18
  19 import "google/api/annotations.proto";
  20 import "google/longrunning/operations.proto";
  21 import "google/protobuf/empty.proto";
  22 import "google/protobuf/field_mask.proto";
  23 import "google/protobuf/struct.proto";
  24
  25 option cc_enable_arenas = true;
  26 option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1";
  27 option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow";
  28 option java_multiple_files = true;
  29 option java_outer_classname = "AgentProto";
  30 option java_package = "com.google.cloud.dialogflow.v2beta1";
  31 option objc_class_prefix = "DF";
  32
  33 // Agents are best described as Natural Language Understanding (NLU) modules
  34 // that transform user requests into actionable data. You can include agents
  35 // in your app, product, or service to determine user intent and respond to the
  36 // user in a natural way.
  37 //
  38 // After you create an agent, you can add
  39 // [Intents][google.cloud.dialogflow.v2beta1.Intents],
  40 // [Contexts][google.cloud.dialogflow.v2beta1.Contexts], [Entity
  41 // Types][google.cloud.dialogflow.v2beta1.EntityTypes],
  42 // [Webhooks][google.cloud.dialogflow.v2beta1.WebhookRequest], and so on to
  43 // manage the flow of a conversation and match user input to predefined intents
  44 // and actions.
  45 //
  46 // You can create an agent using both Dialogflow Standard Edition and
  47 // Dialogflow Enterprise Edition. For details, see
  48 // [Dialogflow
  49 // Editions](https://cloud.google.com/dialogflow-enterprise/docs/editions).
  50 //
  51 // You can save your agent for backup or versioning by exporting the agent by
  52 // using the [ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent]
  53 // method. You can import a saved agent by using the
  54 // [ImportAgent][google.cloud.dialogflow.v2beta1.Agents.ImportAgent] method.
  55 //
  56 // Dialogflow provides several
  57 // [prebuilt agents](https://dialogflow.com/docs/prebuilt-agents) for common
  58 // conversation scenarios such as determining a date and time, converting
  59 // currency, and so on.
  60 //
  61 // For more information about agents, see the
  62 // [Dialogflow documentation](https://dialogflow.com/docs/agents).
  63 service Agents {
  64   // Retrieves the specified agent.
  65   rpc GetAgent(GetAgentRequest) returns (Agent) {
  66     option (google.api.http) = {
  67       get: "/v2beta1/{parent=projects/*}/agent"
  68     };
  69   }
  70
  71   // Returns the list of agents.
  72   //
  73   // Since there is at most one conversational agent per project, this method is
  74   // useful primarily for listing all agents across projects the caller has
  75   // access to. One can achieve that with a wildcard project collection id "-".
  76   // Refer to [List
  77   // Sub-Collections](https://cloud.google.com/apis/design/design_patterns#list_sub-collections).
  78   rpc SearchAgents(SearchAgentsRequest) returns (SearchAgentsResponse) {
  79     option (google.api.http) = {
  80       get: "/v2beta1/{parent=projects/*}/agent:search"
  81     };
  82   }
  83
  84   // Trains the specified agent.
  85   //
  86   //
  87   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
  88   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
  89   rpc TrainAgent(TrainAgentRequest) returns (google.longrunning.Operation) {
  90     option (google.api.http) = {
  91       post: "/v2beta1/{parent=projects/*}/agent:train"
  92       body: "*"
  93     };
  94   }
  95
  96   // Exports the specified agent to a ZIP file.
  97   //
  98   //
  99   // Operation <response:
 100   // [ExportAgentResponse][google.cloud.dialogflow.v2beta1.ExportAgentResponse],
 101   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 102   rpc ExportAgent(ExportAgentRequest) returns (google.longrunning.Operation) {
 103     option (google.api.http) = {
 104       post: "/v2beta1/{parent=projects/*}/agent:export"
 105       body: "*"
 106     };
 107   }
 108
 109   // Imports the specified agent from a ZIP file.
 110   //
 111   // Uploads new intents and entity types without deleting the existing ones.
 112   // Intents and entity types with the same name are replaced with the new
 113   // versions from ImportAgentRequest.
 114   //
 115   //
 116   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
 117   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 118   rpc ImportAgent(ImportAgentRequest) returns (google.longrunning.Operation) {
 119     option (google.api.http) = {
 120       post: "/v2beta1/{parent=projects/*}/agent:import"
 121       body: "*"
 122     };
 123   }
 124
 125   // Restores the specified agent from a ZIP file.
 126   //
 127   // Replaces the current agent version with a new one. All the intents and
 128   // entity types in the older version are deleted.
 129   //
 130   //
 131   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
 132   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 133   rpc RestoreAgent(RestoreAgentRequest) returns (google.longrunning.Operation) {
 134     option (google.api.http) = {
 135       post: "/v2beta1/{parent=projects/*}/agent:restore"
 136       body: "*"
 137     };
 138   }
 139 }
 140
 141 // Represents a conversational agent.
 142 message Agent {
 143   // Match mode determines how intents are detected from user queries.
 144   enum MatchMode {
 145     // Not specified.
 146     MATCH_MODE_UNSPECIFIED = 0;
 147
 148     // Best for agents with a small number of examples in intents and/or wide
 149     // use of templates syntax and composite entities.
 150     MATCH_MODE_HYBRID = 1;
 151
 152     // Can be used for agents with a large number of examples in intents,
 153     // especially the ones using @sys.any or very large developer entities.
 154     MATCH_MODE_ML_ONLY = 2;
 155   }
 156
 157   // Required. The project of this agent.
 158   // Format: `projects/<Project ID>`.
 159   string parent = 1;
 160
 161   // Required. The name of this agent.
 162   string display_name = 2;
 163
 164   // Required. The default language of the agent as a language tag. See
 165   // [Language Support](https://dialogflow.com/docs/reference/language) for a
 166   // list of the currently supported language codes.
 167   // This field cannot be set by the `Update` method.
 168   string default_language_code = 3;
 169
 170   // Optional. The list of all languages supported by this agent (except for the
 171   // `default_language_code`).
 172   repeated string supported_language_codes = 4;
 173
 174   // Required. The time zone of this agent from the
 175   // [time zone database](https://www.iana.org/time-zones), e.g.,
 176   // America/New_York, Europe/Paris.
 177   string time_zone = 5;
 178
 179   // Optional. The description of this agent.
 180   // The maximum length is 500 characters. If exceeded, the request is rejected.
 181   string description = 6;
 182
 183   // Optional. The URI of the agent's avatar.
 184   // Avatars are used throughout the Dialogflow console and in the self-hosted
 185   // [Web Demo](https://dialogflow.com/docs/integrations/web-demo) integration.
 186   string avatar_uri = 7;
 187
 188   // Optional. Determines whether this agent should log conversation queries.
 189   bool enable_logging = 8;
 190
 191   // Optional. Determines how intents are detected from user queries.
 192   MatchMode match_mode = 9;
 193
 194   // Optional. To filter out false positive results and still get variety in
 195   // matched natural language inputs for your agent, you can tune the machine
 196   // learning classification threshold. If the returned score value is less than
 197   // the threshold value, then a fallback intent is be triggered or, if there
 198   // are no fallback intents defined, no intent will be triggered. The score
 199   // values range from 0.0 (completely uncertain) to 1.0 (completely certain).
 200   // If set to 0.0, the default of 0.3 is used.
 201   float classification_threshold = 10;
 202 }
 203
 204 // The request message for
 205 // [Agents.GetAgent][google.cloud.dialogflow.v2beta1.Agents.GetAgent].
 206 message GetAgentRequest {
 207   // Required. The project that the agent to fetch is associated with.
 208   // Format: `projects/<Project ID>`.
 209   string parent = 1;
 210 }
 211
 212 // The request message for
 213 // [Agents.SearchAgents][google.cloud.dialogflow.v2beta1.Agents.SearchAgents].
 214 message SearchAgentsRequest {
 215   // Required. The project to list agents from.
 216   // Format: `projects/<Project ID or '-'>`.
 217   string parent = 1;
 218
 219   // Optional. The maximum number of items to return in a single page. By
 220   // default 100 and at most 1000.
 221   int32 page_size = 2;
 222
 223   // Optional. The next_page_token value returned from a previous list request.
 224   string page_token = 3;
 225 }
 226
 227 // The response message for
 228 // [Agents.SearchAgents][google.cloud.dialogflow.v2beta1.Agents.SearchAgents].
 229 message SearchAgentsResponse {
 230   // The list of agents. There will be a maximum number of items returned based
 231   // on the page_size field in the request.
 232   repeated Agent agents = 1;
 233
 234   // Token to retrieve the next page of results, or empty if there are no
 235   // more results in the list.
 236   string next_page_token = 2;
 237 }
 238
 239 // The request message for
 240 // [Agents.TrainAgent][google.cloud.dialogflow.v2beta1.Agents.TrainAgent].
 241 message TrainAgentRequest {
 242   // Required. The project that the agent to train is associated with.
 243   // Format: `projects/<Project ID>`.
 244   string parent = 1;
 245 }
 246
 247 // The request message for
 248 // [Agents.ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent].
 249 message ExportAgentRequest {
 250   // Required. The project that the agent to export is associated with.
 251   // Format: `projects/<Project ID>`.
 252   string parent = 1;
 253
 254   // Optional. The
 255   // [Google Cloud Storage](https://cloud.google.com/storage/docs/)
 256   // URI to export the agent to.
 257   // The format of this URI must be `gs://<bucket-name>/<object-name>`.
 258   // If left unspecified, the serialized agent is returned inline.
 259   string agent_uri = 2;
 260 }
 261
 262 // The response message for
 263 // [Agents.ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent].
 264 message ExportAgentResponse {
 265   // Required. The exported agent.
 266   oneof agent {
 267     // The URI to a file containing the exported agent. This field is populated
 268     // only if `agent_uri` is specified in `ExportAgentRequest`.
 269     string agent_uri = 1;
 270
 271     // The exported agent.
 272     //
 273     // Example for how to export an agent to a zip file via a command line:
 274     // <pre>curl \
 275     //   'https://dialogflow.googleapis.com/v2beta1/projects/&lt;project_name&gt;/agent:export'\
 276     //   -X POST \
 277     //   -H 'Authorization: Bearer '$(gcloud auth application-default
 278     //   print-access-token) \
 279     //   -H 'Accept: application/json' \
 280     //   -H 'Content-Type: application/json' \
 281     //   --compressed \
 282     //   --data-binary '{}' \
 283     // | grep agentContent | sed -e 's/.*"agentContent": "\([^"]*\)".*/\1/' \
 284     // | base64 --decode > &lt;agent zip file&gt;</pre>
 285     bytes agent_content = 2;
 286   }
 287 }
 288
 289 // The request message for
 290 // [Agents.ImportAgent][google.cloud.dialogflow.v2beta1.Agents.ImportAgent].
 291 message ImportAgentRequest {
 292   // Required. The project that the agent to import is associated with.
 293   // Format: `projects/<Project ID>`.
 294   string parent = 1;
 295
 296   // Required. The agent to import.
 297   oneof agent {
 298     // The URI to a Google Cloud Storage file containing the agent to import.
 299     // Note: The URI must start with "gs://".
 300     string agent_uri = 2;
 301
 302     // The agent to import.
 303     //
 304     // Example for how to import an agent via the command line:
 305     // <pre>curl \
 306     //   'https://dialogflow.googleapis.com/v2beta1/projects/&lt;project_name&gt;/agent:import\
 307     //    -X POST \
 308     //    -H 'Authorization: Bearer '$(gcloud auth application-default
 309     //    print-access-token) \
 310     //    -H 'Accept: application/json' \
 311     //    -H 'Content-Type: application/json' \
 312     //    --compressed \
 313     //    --data-binary "{
 314     //       'agentContent': '$(cat &lt;agent zip file&gt; | base64 -w 0)'
 315     //    }"</pre>
 316     bytes agent_content = 3;
 317   }
 318 }
 319
 320 // The request message for
 321 // [Agents.RestoreAgent][google.cloud.dialogflow.v2beta1.Agents.RestoreAgent].
 322 message RestoreAgentRequest {
 323   // Required. The project that the agent to restore is associated with.
 324   // Format: `projects/<Project ID>`.
 325   string parent = 1;
 326
 327   // Required. The agent to restore.
 328   oneof agent {
 329     // The URI to a Google Cloud Storage file containing the agent to restore.
 330     // Note: The URI must start with "gs://".
 331     string agent_uri = 2;
 332
 333     // The agent to restore.
 334     //
 335     // Example for how to restore an agent via the command line:
 336     // <pre>curl \
 337     //   'https://dialogflow.googleapis.com/v2beta1/projects/&lt;project_name&gt;/agent:restore\
 338     //    -X POST \
 339     //    -H 'Authorization: Bearer '$(gcloud auth application-default
 340     //    print-access-token) \
 341     //    -H 'Accept: application/json' \
 342     //    -H 'Content-Type: application/json' \
 343     //    --compressed \
 344     //    --data-binary "{
 345     //        'agentContent': '$(cat &lt;agent zip file&gt; | base64 -w 0)'
 346     //    }"</pre>
 347     bytes agent_content = 3;
 348   }
 349 }