legacy-libs/dialogflow/protos/google/cloud/dialogflow/v2/agent.proto

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