agent.proto 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446
  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.cx.v3beta1;
  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/cx/v3beta1/advanced_settings.proto";
  21. import "google/cloud/dialogflow/cx/v3beta1/flow.proto";
  22. import "google/cloud/dialogflow/cx/v3beta1/security_settings.proto";
  23. import "google/longrunning/operations.proto";
  24. import "google/protobuf/empty.proto";
  25. import "google/protobuf/field_mask.proto";
  26. option cc_enable_arenas = true;
  27. option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3Beta1";
  28. option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3beta1;cx";
  29. option java_multiple_files = true;
  30. option java_outer_classname = "AgentProto";
  31. option java_package = "com.google.cloud.dialogflow.cx.v3beta1";
  32. option objc_class_prefix = "DF";
  33. // Service for managing [Agents][google.cloud.dialogflow.cx.v3beta1.Agent].
  34. service Agents {
  35. option (google.api.default_host) = "dialogflow.googleapis.com";
  36. option (google.api.oauth_scopes) =
  37. "https://www.googleapis.com/auth/cloud-platform,"
  38. "https://www.googleapis.com/auth/dialogflow";
  39. // Returns the list of all agents in the specified location.
  40. rpc ListAgents(ListAgentsRequest) returns (ListAgentsResponse) {
  41. option (google.api.http) = {
  42. get: "/v3beta1/{parent=projects/*/locations/*}/agents"
  43. };
  44. option (google.api.method_signature) = "parent";
  45. }
  46. // Retrieves the specified agent.
  47. rpc GetAgent(GetAgentRequest) returns (Agent) {
  48. option (google.api.http) = {
  49. get: "/v3beta1/{name=projects/*/locations/*/agents/*}"
  50. };
  51. option (google.api.method_signature) = "name";
  52. }
  53. // Creates an agent in the specified location.
  54. //
  55. // Note: You should always train a flow prior to sending it queries. See the
  56. // [training
  57. // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  58. rpc CreateAgent(CreateAgentRequest) returns (Agent) {
  59. option (google.api.http) = {
  60. post: "/v3beta1/{parent=projects/*/locations/*}/agents"
  61. body: "agent"
  62. };
  63. option (google.api.method_signature) = "parent,agent";
  64. }
  65. // Updates the specified agent.
  66. //
  67. // Note: You should always train a flow prior to sending it queries. See the
  68. // [training
  69. // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  70. rpc UpdateAgent(UpdateAgentRequest) returns (Agent) {
  71. option (google.api.http) = {
  72. patch: "/v3beta1/{agent.name=projects/*/locations/*/agents/*}"
  73. body: "agent"
  74. };
  75. option (google.api.method_signature) = "agent,update_mask";
  76. }
  77. // Deletes the specified agent.
  78. rpc DeleteAgent(DeleteAgentRequest) returns (google.protobuf.Empty) {
  79. option (google.api.http) = {
  80. delete: "/v3beta1/{name=projects/*/locations/*/agents/*}"
  81. };
  82. option (google.api.method_signature) = "name";
  83. }
  84. // Exports the specified agent to a binary file.
  85. rpc ExportAgent(ExportAgentRequest) returns (google.longrunning.Operation) {
  86. option (google.api.http) = {
  87. post: "/v3beta1/{name=projects/*/locations/*/agents/*}:export"
  88. body: "*"
  89. };
  90. option (google.longrunning.operation_info) = {
  91. response_type: "ExportAgentResponse"
  92. metadata_type: "google.protobuf.Struct"
  93. };
  94. }
  95. // Restores the specified agent from a binary file.
  96. //
  97. // Replaces the current agent with a new one. Note that all existing resources
  98. // in agent (e.g. intents, entity types, flows) will be removed.
  99. //
  100. // Note: You should always train a flow prior to sending it queries. See the
  101. // [training
  102. // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  103. rpc RestoreAgent(RestoreAgentRequest) returns (google.longrunning.Operation) {
  104. option (google.api.http) = {
  105. post: "/v3beta1/{name=projects/*/locations/*/agents/*}:restore"
  106. body: "*"
  107. };
  108. option (google.longrunning.operation_info) = {
  109. response_type: "google.protobuf.Empty"
  110. metadata_type: "google.protobuf.Struct"
  111. };
  112. }
  113. // Validates the specified agent and creates or updates validation results.
  114. // The agent in draft version is validated. Please call this API after the
  115. // training is completed to get the complete validation results.
  116. rpc ValidateAgent(ValidateAgentRequest) returns (AgentValidationResult) {
  117. option (google.api.http) = {
  118. post: "/v3beta1/{name=projects/*/locations/*/agents/*}:validate"
  119. body: "*"
  120. };
  121. }
  122. // Gets the latest agent validation result. Agent validation is performed
  123. // when ValidateAgent is called.
  124. rpc GetAgentValidationResult(GetAgentValidationResultRequest) returns (AgentValidationResult) {
  125. option (google.api.http) = {
  126. get: "/v3beta1/{name=projects/*/locations/*/agents/*/validationResult}"
  127. };
  128. option (google.api.method_signature) = "name";
  129. }
  130. }
  131. // Settings related to speech recognition.
  132. message SpeechToTextSettings {
  133. // Whether to use speech adaptation for speech recognition.
  134. bool enable_speech_adaptation = 1;
  135. }
  136. // Agents are best described as Natural Language Understanding (NLU) modules
  137. // that transform user requests into actionable data. You can include agents
  138. // in your app, product, or service to determine user intent and respond to the
  139. // user in a natural way.
  140. //
  141. // After you create an agent, you can add [Intents][google.cloud.dialogflow.cx.v3beta1.Intent],
  142. // [Entity Types][google.cloud.dialogflow.cx.v3beta1.EntityType], [Flows][google.cloud.dialogflow.cx.v3beta1.Flow], [Fulfillments][google.cloud.dialogflow.cx.v3beta1.Fulfillment],
  143. // [Webhooks][google.cloud.dialogflow.cx.v3beta1.Webhook], and so on to manage the conversation flows..
  144. message Agent {
  145. option (google.api.resource) = {
  146. type: "dialogflow.googleapis.com/Agent"
  147. pattern: "projects/{project}/locations/{location}/agents/{agent}"
  148. };
  149. // The unique identifier of the agent.
  150. // Required for the [Agents.UpdateAgent][google.cloud.dialogflow.cx.v3beta1.Agents.UpdateAgent] method. [Agents.CreateAgent][google.cloud.dialogflow.cx.v3beta1.Agents.CreateAgent]
  151. // populates the name automatically.
  152. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  153. string name = 1;
  154. // Required. The human-readable name of the agent, unique within the location.
  155. string display_name = 2 [(google.api.field_behavior) = REQUIRED];
  156. // Required. Immutable. The default language of the agent as a language tag.
  157. // See [Language
  158. // Support](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  159. // for a list of the currently supported language codes.
  160. // This field cannot be set by the [Agents.UpdateAgent][google.cloud.dialogflow.cx.v3beta1.Agents.UpdateAgent] method.
  161. string default_language_code = 3 [
  162. (google.api.field_behavior) = REQUIRED,
  163. (google.api.field_behavior) = IMMUTABLE
  164. ];
  165. // The list of all languages supported by the agent (except for the
  166. // `default_language_code`).
  167. repeated string supported_language_codes = 4;
  168. // Required. The time zone of the agent from the [time zone
  169. // database](https://www.iana.org/time-zones), e.g., America/New_York,
  170. // Europe/Paris.
  171. string time_zone = 5 [(google.api.field_behavior) = REQUIRED];
  172. // The description of the agent. The maximum length is 500 characters. If
  173. // exceeded, the request is rejected.
  174. string description = 6;
  175. // The URI of the agent's avatar. Avatars are used throughout the Dialogflow
  176. // console and in the self-hosted [Web
  177. // Demo](https://cloud.google.com/dialogflow/docs/integrations/web-demo)
  178. // integration.
  179. string avatar_uri = 7;
  180. // Speech recognition related settings.
  181. SpeechToTextSettings speech_to_text_settings = 13;
  182. // Immutable. Name of the start flow in this agent. A start flow will be automatically
  183. // created when the agent is created, and can only be deleted by deleting the
  184. // agent.
  185. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  186. // ID>/flows/<Flow ID>`.
  187. string start_flow = 16 [
  188. (google.api.field_behavior) = IMMUTABLE,
  189. (google.api.resource_reference) = {
  190. type: "dialogflow.googleapis.com/Flow"
  191. }
  192. ];
  193. // Name of the [SecuritySettings][google.cloud.dialogflow.cx.v3beta1.SecuritySettings] reference for the agent.
  194. // Format: `projects/<Project ID>/locations/<Location
  195. // ID>/securitySettings/<Security Settings ID>`.
  196. string security_settings = 17 [(google.api.resource_reference) = {
  197. type: "dialogflow.googleapis.com/SecuritySettings"
  198. }];
  199. // Indicates if stackdriver logging is enabled for the agent.
  200. // Please use [agent.advanced_settings][google.cloud.dialogflow.cx.v3beta1.AdvancedSettings.LoggingSettings]
  201. // instead.
  202. bool enable_stackdriver_logging = 18 [deprecated = true];
  203. // Indicates if automatic spell correction is enabled in detect intent
  204. // requests.
  205. bool enable_spell_correction = 20;
  206. // Hierarchical advanced settings for this agent. The settings exposed at the
  207. // lower level overrides the settings exposed at the higher level.
  208. AdvancedSettings advanced_settings = 22;
  209. }
  210. // The request message for [Agents.ListAgents][google.cloud.dialogflow.cx.v3beta1.Agents.ListAgents].
  211. message ListAgentsRequest {
  212. // Required. The location to list all agents for.
  213. // Format: `projects/<Project ID>/locations/<Location ID>`.
  214. string parent = 1 [
  215. (google.api.field_behavior) = REQUIRED,
  216. (google.api.resource_reference) = {
  217. child_type: "dialogflow.googleapis.com/Agent"
  218. }
  219. ];
  220. // The maximum number of items to return in a single page. By default 100 and
  221. // at most 1000.
  222. int32 page_size = 2;
  223. // The next_page_token value returned from a previous list request.
  224. string page_token = 3;
  225. }
  226. // The response message for [Agents.ListAgents][google.cloud.dialogflow.cx.v3beta1.Agents.ListAgents].
  227. message ListAgentsResponse {
  228. // The list of agents. There will be a maximum number of items returned based
  229. // on the page_size field in the request.
  230. repeated Agent agents = 1;
  231. // Token to retrieve the next page of results, or empty if there are no more
  232. // results in the list.
  233. string next_page_token = 2;
  234. }
  235. // The request message for [Agents.GetAgent][google.cloud.dialogflow.cx.v3beta1.Agents.GetAgent].
  236. message GetAgentRequest {
  237. // Required. The name of the agent.
  238. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  239. string name = 1 [
  240. (google.api.field_behavior) = REQUIRED,
  241. (google.api.resource_reference) = {
  242. type: "dialogflow.googleapis.com/Agent"
  243. }
  244. ];
  245. }
  246. // The request message for [Agents.CreateAgent][google.cloud.dialogflow.cx.v3beta1.Agents.CreateAgent].
  247. message CreateAgentRequest {
  248. // Required. The location to create a agent for.
  249. // Format: `projects/<Project ID>/locations/<Location ID>`.
  250. string parent = 1 [
  251. (google.api.field_behavior) = REQUIRED,
  252. (google.api.resource_reference) = {
  253. child_type: "dialogflow.googleapis.com/Agent"
  254. }
  255. ];
  256. // Required. The agent to create.
  257. Agent agent = 2 [(google.api.field_behavior) = REQUIRED];
  258. }
  259. // The request message for [Agents.UpdateAgent][google.cloud.dialogflow.cx.v3beta1.Agents.UpdateAgent].
  260. message UpdateAgentRequest {
  261. // Required. The agent to update.
  262. Agent agent = 1 [(google.api.field_behavior) = REQUIRED];
  263. // The mask to control which fields get updated. If the mask is not present,
  264. // all fields will be updated.
  265. google.protobuf.FieldMask update_mask = 2;
  266. }
  267. // The request message for [Agents.DeleteAgent][google.cloud.dialogflow.cx.v3beta1.Agents.DeleteAgent].
  268. message DeleteAgentRequest {
  269. // Required. The name of the agent to delete.
  270. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  271. string name = 1 [
  272. (google.api.field_behavior) = REQUIRED,
  273. (google.api.resource_reference) = {
  274. type: "dialogflow.googleapis.com/Agent"
  275. }
  276. ];
  277. }
  278. // The request message for [Agents.ExportAgent][google.cloud.dialogflow.cx.v3beta1.Agents.ExportAgent].
  279. message ExportAgentRequest {
  280. // Required. The name of the agent to export.
  281. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  282. string name = 1 [
  283. (google.api.field_behavior) = REQUIRED,
  284. (google.api.resource_reference) = {
  285. type: "dialogflow.googleapis.com/Agent"
  286. }
  287. ];
  288. // Optional. The [Google Cloud Storage](https://cloud.google.com/storage/docs/) URI to
  289. // export the agent to. The format of this URI must be
  290. // `gs://<bucket-name>/<object-name>`.
  291. // If left unspecified, the serialized agent is returned inline.
  292. string agent_uri = 2 [(google.api.field_behavior) = OPTIONAL];
  293. // Optional. Environment name. If not set, draft environment is assumed.
  294. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  295. // ID>/environments/<Environment ID>`.
  296. string environment = 5 [
  297. (google.api.field_behavior) = OPTIONAL,
  298. (google.api.resource_reference) = {
  299. type: "dialogflow.googleapis.com/Environment"
  300. }
  301. ];
  302. }
  303. // The response message for [Agents.ExportAgent][google.cloud.dialogflow.cx.v3beta1.Agents.ExportAgent].
  304. message ExportAgentResponse {
  305. // The exported agent.
  306. oneof agent {
  307. // The URI to a file containing the exported agent. This field is populated
  308. // only if `agent_uri` is specified in [ExportAgentRequest][google.cloud.dialogflow.cx.v3beta1.ExportAgentRequest].
  309. string agent_uri = 1;
  310. // Uncompressed raw byte content for agent.
  311. bytes agent_content = 2;
  312. }
  313. }
  314. // The request message for [Agents.RestoreAgent][google.cloud.dialogflow.cx.v3beta1.Agents.RestoreAgent].
  315. message RestoreAgentRequest {
  316. // Restore option.
  317. enum RestoreOption {
  318. // Unspecified. Treated as KEEP.
  319. RESTORE_OPTION_UNSPECIFIED = 0;
  320. // Always respect the settings from the exported agent file. It may cause
  321. // a restoration failure if some settings (e.g. model type) are not
  322. // supported in the target agent.
  323. KEEP = 1;
  324. // Fallback to default settings if some settings are not supported in the
  325. // target agent.
  326. FALLBACK = 2;
  327. }
  328. // Required. The name of the agent to restore into.
  329. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  330. string name = 1 [
  331. (google.api.field_behavior) = REQUIRED,
  332. (google.api.resource_reference) = {
  333. type: "dialogflow.googleapis.com/Agent"
  334. }
  335. ];
  336. // Required. The agent to restore.
  337. oneof agent {
  338. // The [Google Cloud Storage](https://cloud.google.com/storage/docs/) URI
  339. // to restore agent from. The format of this URI must be
  340. // `gs://<bucket-name>/<object-name>`.
  341. string agent_uri = 2;
  342. // Uncompressed raw byte content for agent.
  343. bytes agent_content = 3;
  344. }
  345. // Agent restore mode. If not specified, `KEEP` is assumed.
  346. RestoreOption restore_option = 5;
  347. }
  348. // The request message for [Agents.ValidateAgent][google.cloud.dialogflow.cx.v3beta1.Agents.ValidateAgent].
  349. message ValidateAgentRequest {
  350. // Required. The agent to validate.
  351. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  352. string name = 1 [
  353. (google.api.field_behavior) = REQUIRED,
  354. (google.api.resource_reference) = {
  355. type: "dialogflow.googleapis.com/Agent"
  356. }
  357. ];
  358. // If not specified, the agent's default language is used.
  359. string language_code = 2;
  360. }
  361. // The request message for [Agents.GetAgentValidationResult][google.cloud.dialogflow.cx.v3beta1.Agents.GetAgentValidationResult].
  362. message GetAgentValidationResultRequest {
  363. // Required. The agent name.
  364. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  365. // ID>/validationResult`.
  366. string name = 1 [
  367. (google.api.field_behavior) = REQUIRED,
  368. (google.api.resource_reference) = {
  369. type: "dialogflow.googleapis.com/AgentValidationResult"
  370. }
  371. ];
  372. // If not specified, the agent's default language is used.
  373. string language_code = 2;
  374. }
  375. // The response message for [Agents.GetAgentValidationResult][google.cloud.dialogflow.cx.v3beta1.Agents.GetAgentValidationResult].
  376. message AgentValidationResult {
  377. option (google.api.resource) = {
  378. type: "dialogflow.googleapis.com/AgentValidationResult"
  379. pattern: "projects/{project}/locations/{location}/agents/{agent}/validationResult"
  380. };
  381. // The unique identifier of the agent validation result.
  382. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  383. // ID>/validationResult`.
  384. string name = 1;
  385. // Contains all flow validation results.
  386. repeated FlowValidationResult flow_validation_results = 2;
  387. }