agent.proto 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519
  1. // Copyright 2021 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. syntax = "proto3";
  15. package google.cloud.dialogflow.v2beta1;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/api/resource.proto";
  20. import "google/cloud/dialogflow/v2beta1/environment.proto";
  21. import "google/cloud/dialogflow/v2beta1/validation_result.proto";
  22. import "google/longrunning/operations.proto";
  23. import "google/protobuf/empty.proto";
  24. import "google/protobuf/field_mask.proto";
  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. // Service for managing [Agents][google.cloud.dialogflow.v2beta1.Agent].
  33. service Agents {
  34. option (google.api.default_host) = "dialogflow.googleapis.com";
  35. option (google.api.oauth_scopes) =
  36. "https://www.googleapis.com/auth/cloud-platform,"
  37. "https://www.googleapis.com/auth/dialogflow";
  38. // Retrieves the specified agent.
  39. rpc GetAgent(GetAgentRequest) returns (Agent) {
  40. option (google.api.http) = {
  41. get: "/v2beta1/{parent=projects/*}/agent"
  42. additional_bindings {
  43. get: "/v2beta1/{parent=projects/*/locations/*}/agent"
  44. }
  45. };
  46. option (google.api.method_signature) = "parent";
  47. }
  48. // Creates/updates the specified agent.
  49. rpc SetAgent(SetAgentRequest) returns (Agent) {
  50. option (google.api.http) = {
  51. post: "/v2beta1/{agent.parent=projects/*}/agent"
  52. body: "agent"
  53. additional_bindings {
  54. post: "/v2beta1/{agent.parent=projects/*/locations/*}/agent"
  55. body: "agent"
  56. }
  57. };
  58. option (google.api.method_signature) = "agent";
  59. }
  60. // Deletes the specified agent.
  61. rpc DeleteAgent(DeleteAgentRequest) returns (google.protobuf.Empty) {
  62. option (google.api.http) = {
  63. delete: "/v2beta1/{parent=projects/*}/agent"
  64. additional_bindings {
  65. delete: "/v2beta1/{parent=projects/*/locations/*}/agent"
  66. }
  67. };
  68. option (google.api.method_signature) = "parent";
  69. }
  70. // Returns the list of agents.
  71. // Since there is at most one conversational agent per project, this method is
  72. // useful primarily for listing all agents across projects the caller has
  73. // access to. One can achieve that with a wildcard project collection id "-".
  74. // Refer to [List
  75. // Sub-Collections](https://cloud.google.com/apis/design/design_patterns#list_sub-collections).
  76. rpc SearchAgents(SearchAgentsRequest) returns (SearchAgentsResponse) {
  77. option (google.api.http) = {
  78. get: "/v2beta1/{parent=projects/*}/agent:search"
  79. additional_bindings {
  80. get: "/v2beta1/{parent=projects/*/locations/*}/agent:search"
  81. }
  82. };
  83. option (google.api.method_signature) = "parent";
  84. }
  85. // Trains the specified agent.
  86. //
  87. //
  88. // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]>
  89. rpc TrainAgent(TrainAgentRequest) returns (google.longrunning.Operation) {
  90. option (google.api.http) = {
  91. post: "/v2beta1/{parent=projects/*}/agent:train"
  92. body: "*"
  93. additional_bindings {
  94. post: "/v2beta1/{parent=projects/*/locations/*}/agent:train"
  95. body: "*"
  96. }
  97. };
  98. option (google.api.method_signature) = "parent";
  99. option (google.longrunning.operation_info) = {
  100. response_type: "google.protobuf.Empty"
  101. metadata_type: "google.protobuf.Struct"
  102. };
  103. }
  104. // Exports the specified agent to a ZIP file.
  105. //
  106. //
  107. // Operation <response: [ExportAgentResponse][google.cloud.dialogflow.v2beta1.ExportAgentResponse]>
  108. rpc ExportAgent(ExportAgentRequest) returns (google.longrunning.Operation) {
  109. option (google.api.http) = {
  110. post: "/v2beta1/{parent=projects/*}/agent:export"
  111. body: "*"
  112. additional_bindings {
  113. post: "/v2beta1/{parent=projects/*/locations/*}/agent:export"
  114. body: "*"
  115. }
  116. };
  117. option (google.api.method_signature) = "parent";
  118. option (google.longrunning.operation_info) = {
  119. response_type: "google.cloud.dialogflow.v2beta1.ExportAgentResponse"
  120. metadata_type: "google.protobuf.Struct"
  121. };
  122. }
  123. // Imports the specified agent from a ZIP file.
  124. //
  125. // Uploads new intents and entity types without deleting the existing ones.
  126. // Intents and entity types with the same name are replaced with the new
  127. // versions from [ImportAgentRequest][google.cloud.dialogflow.v2beta1.ImportAgentRequest]. After the import, the imported draft
  128. // agent will be trained automatically (unless disabled in agent settings).
  129. // However, once the import is done, training may not be completed yet. Please
  130. // call [TrainAgent][google.cloud.dialogflow.v2beta1.Agents.TrainAgent] and wait for the operation it returns in order to train
  131. // explicitly.
  132. //
  133. //
  134. // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]>
  135. // An operation which tracks when importing is complete. It only tracks
  136. // when the draft agent is updated not when it is done training.
  137. rpc ImportAgent(ImportAgentRequest) returns (google.longrunning.Operation) {
  138. option (google.api.http) = {
  139. post: "/v2beta1/{parent=projects/*}/agent:import"
  140. body: "*"
  141. additional_bindings {
  142. post: "/v2beta1/{parent=projects/*/locations/*}/agent:import"
  143. body: "*"
  144. }
  145. };
  146. option (google.longrunning.operation_info) = {
  147. response_type: "google.protobuf.Empty"
  148. metadata_type: "google.protobuf.Struct"
  149. };
  150. }
  151. // Restores the specified agent from a ZIP file.
  152. //
  153. // Replaces the current agent version with a new one. All the intents and
  154. // entity types in the older version are deleted. After the restore, the
  155. // restored draft agent will be trained automatically (unless disabled in
  156. // agent settings). However, once the restore is done, training may not be
  157. // completed yet. Please call [TrainAgent][google.cloud.dialogflow.v2beta1.Agents.TrainAgent] and wait for the operation it
  158. // returns in order to train explicitly.
  159. //
  160. //
  161. // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]>
  162. // An operation which tracks when restoring is complete. It only tracks
  163. // when the draft agent is updated not when it is done training.
  164. rpc RestoreAgent(RestoreAgentRequest) returns (google.longrunning.Operation) {
  165. option (google.api.http) = {
  166. post: "/v2beta1/{parent=projects/*}/agent:restore"
  167. body: "*"
  168. additional_bindings {
  169. post: "/v2beta1/{parent=projects/*/locations/*}/agent:restore"
  170. body: "*"
  171. }
  172. };
  173. option (google.longrunning.operation_info) = {
  174. response_type: "google.protobuf.Empty"
  175. metadata_type: "google.protobuf.Struct"
  176. };
  177. }
  178. // Gets agent validation result. Agent validation is performed during
  179. // training time and is updated automatically when training is completed.
  180. rpc GetValidationResult(GetValidationResultRequest) returns (ValidationResult) {
  181. option (google.api.http) = {
  182. get: "/v2beta1/{parent=projects/*}/agent/validationResult"
  183. additional_bindings {
  184. get: "/v2beta1/{parent=projects/*/locations/*}/agent/validationResult"
  185. }
  186. };
  187. }
  188. }
  189. // A Dialogflow agent is a virtual agent that handles conversations with your
  190. // end-users. It is a natural language understanding module that understands the
  191. // nuances of human language. Dialogflow translates end-user text or audio
  192. // during a conversation to structured data that your apps and services can
  193. // understand. You design and build a Dialogflow agent to handle the types of
  194. // conversations required for your system.
  195. //
  196. // For more information about agents, see the
  197. // [Agent guide](https://cloud.google.com/dialogflow/docs/agents-overview).
  198. //
  199. message Agent {
  200. option (google.api.resource) = {
  201. type: "dialogflow.googleapis.com/Agent"
  202. pattern: "projects/{project}/agent"
  203. pattern: "projects/{project}/locations/{location}/agent"
  204. };
  205. // Match mode determines how intents are detected from user queries.
  206. enum MatchMode {
  207. // Not specified.
  208. MATCH_MODE_UNSPECIFIED = 0;
  209. // Best for agents with a small number of examples in intents and/or wide
  210. // use of templates syntax and composite entities.
  211. MATCH_MODE_HYBRID = 1;
  212. // Can be used for agents with a large number of examples in intents,
  213. // especially the ones using @sys.any or very large custom entities.
  214. MATCH_MODE_ML_ONLY = 2;
  215. }
  216. // API version for the agent.
  217. enum ApiVersion {
  218. // Not specified.
  219. API_VERSION_UNSPECIFIED = 0;
  220. // Legacy V1 API.
  221. API_VERSION_V1 = 1;
  222. // V2 API.
  223. API_VERSION_V2 = 2;
  224. // V2beta1 API.
  225. API_VERSION_V2_BETA_1 = 3;
  226. }
  227. // Represents the agent tier.
  228. enum Tier {
  229. // Not specified. This value should never be used.
  230. TIER_UNSPECIFIED = 0;
  231. // Standard tier.
  232. TIER_STANDARD = 1;
  233. // Enterprise tier (Essentials).
  234. TIER_ENTERPRISE = 2;
  235. // Enterprise tier (Plus).
  236. TIER_ENTERPRISE_PLUS = 3;
  237. }
  238. // Required. The project of this agent.
  239. // Format: `projects/<Project ID>` or
  240. // `projects/<Project ID>/locations/<Location ID>`
  241. string parent = 1 [
  242. (google.api.field_behavior) = REQUIRED,
  243. (google.api.resource_reference) = {
  244. type: "cloudresourcemanager.googleapis.com/Project"
  245. }
  246. ];
  247. // Required. The name of this agent.
  248. string display_name = 2;
  249. // Required. The default language of the agent as a language tag. See
  250. // [Language
  251. // Support](https://cloud.google.com/dialogflow/docs/reference/language)
  252. // for a list of the currently supported language codes. This field cannot be
  253. // set by the `Update` method.
  254. string default_language_code = 3;
  255. // Optional. The list of all languages supported by this agent (except for the
  256. // `default_language_code`).
  257. repeated string supported_language_codes = 4;
  258. // Required. The time zone of this agent from the
  259. // [time zone database](https://www.iana.org/time-zones), e.g.,
  260. // America/New_York, Europe/Paris.
  261. string time_zone = 5;
  262. // Optional. The description of this agent.
  263. // The maximum length is 500 characters. If exceeded, the request is rejected.
  264. string description = 6;
  265. // Optional. The URI of the agent's avatar.
  266. // Avatars are used throughout the Dialogflow console and in the self-hosted
  267. // [Web
  268. // Demo](https://cloud.google.com/dialogflow/docs/integrations/web-demo)
  269. // integration.
  270. string avatar_uri = 7;
  271. // Optional. Determines whether this agent should log conversation queries.
  272. bool enable_logging = 8;
  273. // Optional. Determines how intents are detected from user queries.
  274. MatchMode match_mode = 9 [deprecated = true];
  275. // Optional. To filter out false positive results and still get variety in
  276. // matched natural language inputs for your agent, you can tune the machine
  277. // learning classification threshold. If the returned score value is less than
  278. // the threshold value, then a fallback intent will be triggered or, if there
  279. // are no fallback intents defined, no intent will be triggered. The score
  280. // values range from 0.0 (completely uncertain) to 1.0 (completely certain).
  281. // If set to 0.0, the default of 0.3 is used.
  282. float classification_threshold = 10;
  283. // Optional. API version displayed in Dialogflow console. If not specified,
  284. // V2 API is assumed. Clients are free to query different service endpoints
  285. // for different API versions. However, bots connectors and webhook calls will
  286. // follow the specified API version.
  287. ApiVersion api_version = 14;
  288. // Optional. The agent tier. If not specified, TIER_STANDARD is assumed.
  289. Tier tier = 15;
  290. }
  291. // The request message for [Agents.GetAgent][google.cloud.dialogflow.v2beta1.Agents.GetAgent].
  292. message GetAgentRequest {
  293. // Required. The project that the agent to fetch is associated with.
  294. // Format: `projects/<Project ID>` or
  295. // `projects/<Project ID>/locations/<Location ID>`.
  296. string parent = 1 [
  297. (google.api.field_behavior) = REQUIRED,
  298. (google.api.resource_reference) = {
  299. child_type: "dialogflow.googleapis.com/Agent"
  300. }
  301. ];
  302. }
  303. // The request message for [Agents.SetAgent][google.cloud.dialogflow.v2beta1.Agents.SetAgent].
  304. message SetAgentRequest {
  305. // Required. The agent to update.
  306. Agent agent = 1 [(google.api.field_behavior) = REQUIRED];
  307. // Optional. The mask to control which fields get updated.
  308. google.protobuf.FieldMask update_mask = 2;
  309. }
  310. // The request message for [Agents.DeleteAgent][google.cloud.dialogflow.v2beta1.Agents.DeleteAgent].
  311. message DeleteAgentRequest {
  312. // Required. The project that the agent to delete is associated with.
  313. // Format: `projects/<Project ID>` or
  314. // `projects/<Project ID>/locations/<Location ID>`.
  315. string parent = 1 [
  316. (google.api.field_behavior) = REQUIRED,
  317. (google.api.resource_reference) = {
  318. child_type: "dialogflow.googleapis.com/Agent"
  319. }
  320. ];
  321. }
  322. // Contains basic configuration for a sub-agent.
  323. message SubAgent {
  324. // Required. The project of this agent.
  325. // Format: `projects/<Project ID>` or
  326. // `projects/<Project ID>/locations/<Location ID>`.
  327. string project = 1;
  328. // Optional. The unique identifier (`environment name` in dialogflow console)
  329. // of this sub-agent environment. Assumes draft environment if `environment`
  330. // is not set.
  331. string environment = 2;
  332. }
  333. // The request message for [Agents.SearchAgents][google.cloud.dialogflow.v2beta1.Agents.SearchAgents].
  334. message SearchAgentsRequest {
  335. // Required. The project to list agents from.
  336. // Format: `projects/<Project ID or '-'>` or
  337. // `projects/<Project ID or '-'>/locations/<Location ID>`.
  338. string parent = 1 [
  339. (google.api.field_behavior) = REQUIRED,
  340. (google.api.resource_reference) = {
  341. child_type: "dialogflow.googleapis.com/Agent"
  342. }
  343. ];
  344. // Optional. The maximum number of items to return in a single page. By
  345. // default 100 and at most 1000.
  346. int32 page_size = 2;
  347. // Optional. The next_page_token value returned from a previous list request.
  348. string page_token = 3;
  349. }
  350. // The response message for [Agents.SearchAgents][google.cloud.dialogflow.v2beta1.Agents.SearchAgents].
  351. message SearchAgentsResponse {
  352. // The list of agents. There will be a maximum number of items returned based
  353. // on the page_size field in the request.
  354. repeated Agent agents = 1;
  355. // Token to retrieve the next page of results, or empty if there are no
  356. // more results in the list.
  357. string next_page_token = 2;
  358. }
  359. // The request message for [Agents.TrainAgent][google.cloud.dialogflow.v2beta1.Agents.TrainAgent].
  360. message TrainAgentRequest {
  361. // Required. The project that the agent to train is associated with.
  362. // Format: `projects/<Project ID>` or
  363. // `projects/<Project ID>/locations/<Location ID>`.
  364. string parent = 1 [
  365. (google.api.field_behavior) = REQUIRED,
  366. (google.api.resource_reference) = {
  367. child_type: "dialogflow.googleapis.com/Agent"
  368. }
  369. ];
  370. }
  371. // The request message for [Agents.ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent].
  372. message ExportAgentRequest {
  373. // Required. The project that the agent to export is associated with.
  374. // Format: `projects/<Project ID>` or
  375. // `projects/<Project ID>/locations/<Location ID>`.
  376. string parent = 1 [
  377. (google.api.field_behavior) = REQUIRED,
  378. (google.api.resource_reference) = {
  379. child_type: "dialogflow.googleapis.com/Agent"
  380. }
  381. ];
  382. // Optional. The
  383. // [Google Cloud Storage](https://cloud.google.com/storage/docs/)
  384. // URI to export the agent to.
  385. // The format of this URI must be `gs://<bucket-name>/<object-name>`.
  386. // If left unspecified, the serialized agent is returned inline.
  387. string agent_uri = 2;
  388. }
  389. // The response message for [Agents.ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent].
  390. message ExportAgentResponse {
  391. // The exported agent.
  392. oneof agent {
  393. // The URI to a file containing the exported agent. This field is populated
  394. // only if `agent_uri` is specified in `ExportAgentRequest`.
  395. string agent_uri = 1;
  396. // Zip compressed raw byte content for agent.
  397. bytes agent_content = 2;
  398. }
  399. }
  400. // The request message for [Agents.ImportAgent][google.cloud.dialogflow.v2beta1.Agents.ImportAgent].
  401. message ImportAgentRequest {
  402. // Required. The project that the agent to import is associated with.
  403. // Format: `projects/<Project ID>` or
  404. // `projects/<Project ID>/locations/<Location ID>`.
  405. string parent = 1 [
  406. (google.api.field_behavior) = REQUIRED,
  407. (google.api.resource_reference) = {
  408. child_type: "dialogflow.googleapis.com/Agent"
  409. }
  410. ];
  411. // Required. The agent to import.
  412. oneof agent {
  413. // The URI to a Google Cloud Storage file containing the agent to import.
  414. // Note: The URI must start with "gs://".
  415. string agent_uri = 2;
  416. // Zip compressed raw byte content for agent.
  417. bytes agent_content = 3;
  418. }
  419. }
  420. // The request message for [Agents.RestoreAgent][google.cloud.dialogflow.v2beta1.Agents.RestoreAgent].
  421. message RestoreAgentRequest {
  422. // Required. The project that the agent to restore is associated with.
  423. // Format: `projects/<Project ID>` or
  424. // `projects/<Project ID>/locations/<Location ID>`.
  425. string parent = 1 [
  426. (google.api.field_behavior) = REQUIRED,
  427. (google.api.resource_reference) = {
  428. child_type: "dialogflow.googleapis.com/Agent"
  429. }
  430. ];
  431. // Required. The agent to restore.
  432. oneof agent {
  433. // The URI to a Google Cloud Storage file containing the agent to restore.
  434. // Note: The URI must start with "gs://".
  435. string agent_uri = 2;
  436. // Zip compressed raw byte content for agent.
  437. bytes agent_content = 3;
  438. }
  439. }
  440. // The request message for [Agents.GetValidationResult][google.cloud.dialogflow.v2beta1.Agents.GetValidationResult].
  441. message GetValidationResultRequest {
  442. // Required. The project that the agent is associated with.
  443. // Format: `projects/<Project ID>` or
  444. // `projects/<Project ID>/locations/<Location ID>`.
  445. string parent = 1 [
  446. (google.api.field_behavior) = REQUIRED,
  447. (google.api.resource_reference) = {
  448. child_type: "dialogflow.googleapis.com/Agent"
  449. }
  450. ];
  451. // Optional. The language for which you want a validation result. If not
  452. // specified, the agent's default language is used. [Many
  453. // languages](https://cloud.google.com/dialogflow/docs/reference/language)
  454. // are supported. Note: languages must be enabled in the agent before they can
  455. // be used.
  456. string language_code = 3 [(google.api.field_behavior) = OPTIONAL];
  457. }