feat: [ces] add public libraries for CES v1beta

packages/google-cloud-ces/protos/google/cloud/ces/v1beta/agent.proto

@@ -0,0 +1,236 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.cloud.ces.v1beta;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/ces/v1beta/agent_transfers.proto";
+import "google/cloud/ces/v1beta/common.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "cloud.google.com/go/ces/apiv1beta/cespb;cespb";
+option java_multiple_files = true;
+option java_outer_classname = "AgentProto";
+option java_package = "com.google.cloud.ces.v1beta";
+option (google.api.resource_definition) = {
+  type: "dialogflow.googleapis.com/DialogflowAgent"
+  pattern: "projects/{project}/locations/{location}/agents/{agent}"
+};
+
+// An agent acts as the fundamental building block that provides instructions to
+// the Large Language Model (LLM) for executing specific tasks.
+message Agent {
+  option (google.api.resource) = {
+    type: "ces.googleapis.com/Agent"
+    pattern: "projects/{project}/locations/{location}/apps/{app}/agents/{agent}"
+    plural: "agents"
+    singular: "agent"
+  };
+
+  // Default agent type. The agent uses instructions and callbacks specified in
+  // the agent to perform the task using a large language model.
+  message LlmAgent {}
+
+  // The agent which will transfer execution to a remote
+  // [Dialogflow
+  // CX](https://docs.cloud.google.com/dialogflow/cx/docs/concept/agent) agent.
+  // The Dialogflow agent will process subsequent user queries until the session
+  // ends or flow ends, and the control is transferred back to the parent CES
+  // agent.
+  message RemoteDialogflowAgent {
+    // Required. The
+    // [Dialogflow](https://docs.cloud.google.com/dialogflow/cx/docs/concept/agent)
+    // agent resource name.
+    // Format: `projects/{project}/locations/{location}/agents/{agent}`
+    string agent = 1 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = {
+        type: "dialogflow.googleapis.com/DialogflowAgent"
+      }
+    ];
+
+    // Optional. The flow ID of the flow in the Dialogflow agent.
+    string flow_id = 2 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The environment ID of the Dialogflow agent to be used for the
+    // agent execution. If not specified, the draft environment will be used.
+    string environment_id = 3 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The mapping of the app variables names to the Dialogflow
+    // session parameters names to be sent to the Dialogflow agent as input.
+    map<string, string> input_variable_mapping = 4
+        [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The mapping of the Dialogflow session parameters names to the
+    // app variables names to be sent back to the CES agent after the Dialogflow
+    // agent execution ends.
+    map<string, string> output_variable_mapping = 5
+        [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. Indicates whether to respect the message-level interruption
+    // settings configured in the Dialogflow agent.
+    //
+    // * If false: all response messages from the Dialogflow agent follow the
+    // app-level barge-in settings.
+    // * If true: only response messages with
+    // [`allow_playback_interruption`](https://docs.cloud.google.com/dialogflow/cx/docs/reference/rpc/google.cloud.dialogflow.cx.v3#text)
+    // set to true will be interruptable, all other messages follow the
+    // app-level barge-in settings.
+    bool respect_response_interruption_settings = 6
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // A toolset with a selection of its tools.
+  message AgentToolset {
+    // Required. The resource name of the toolset.
+    // Format:
+    // `projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}`
+    string toolset = 1 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = { type: "ces.googleapis.com/Toolset" }
+    ];
+
+    // Optional. The tools IDs to filter the toolset.
+    repeated string tool_ids = 4 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // The type of agent.
+  oneof agent_type {
+    // Optional. The default agent type.
+    LlmAgent llm_agent = 26 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The remote
+    // [Dialogflow](https://cloud.google.com/dialogflow/cx/docs/concept/console-conversational-agents)
+    // agent to be used for the agent execution. If this field is set, all other
+    // agent level properties will be ignored.
+    //
+    // Note: If the Dialogflow agent is in a different project from the app, you
+    // should grant `roles/dialogflow.client` to the CES service agent
+    // `service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com`.
+    RemoteDialogflowAgent remote_dialogflow_agent = 27
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Identifier. The unique identifier of the agent.
+  // Format: `projects/{project}/locations/{location}/apps/{app}/agents/{agent}`
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Required. Display name of the agent.
+  string display_name = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Human-readable description of the agent.
+  string description = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Configurations for the LLM model.
+  ModelSettings model_settings = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Instructions for the LLM model to guide the agent's behavior.
+  string instruction = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. List of available tools for the agent.
+  // Format: `projects/{project}/locations/{location}/apps/{app}/tools/{tool}`
+  repeated string tools = 7 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
+  ];
+
+  // Optional. List of child agents in the agent tree.
+  // Format: `projects/{project}/locations/{location}/apps/{app}/agents/{agent}`
+  repeated string child_agents = 8 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = { type: "ces.googleapis.com/Agent" }
+  ];
+
+  // Optional. The callbacks to execute before the agent is called.
+  // The provided callbacks are executed sequentially in the exact order they
+  // are given in the list. If a callback returns an overridden response,
+  // execution stops and any remaining callbacks are skipped.
+  repeated Callback before_agent_callbacks = 18
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The callbacks to execute after the agent is called.
+  // The provided callbacks are executed sequentially in the exact order they
+  // are given in the list. If a callback returns an overridden response,
+  // execution stops and any remaining callbacks are skipped.
+  repeated Callback after_agent_callbacks = 19
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The callbacks to execute before the model is called. If there are
+  // multiple calls to the model, the callback will be executed multiple times.
+  // The provided callbacks are executed sequentially in the exact order they
+  // are given in the list. If a callback returns an overridden response,
+  // execution stops and any remaining callbacks are skipped.
+  repeated Callback before_model_callbacks = 20
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The callbacks to execute after the model is called. If there are
+  // multiple calls to the model, the callback will be executed multiple times.
+  // The provided callbacks are executed sequentially in the exact order they
+  // are given in the list. If a callback returns an overridden response,
+  // execution stops and any remaining callbacks are skipped.
+  repeated Callback after_model_callbacks = 21
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The callbacks to execute before the tool is invoked. If there are
+  // multiple tool invocations, the callback will be executed multiple times.
+  // The provided callbacks are executed sequentially in the exact order they
+  // are given in the list. If a callback returns an overridden response,
+  // execution stops and any remaining callbacks are skipped.
+  repeated Callback before_tool_callbacks = 22
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The callbacks to execute after the tool is invoked. If there are
+  // multiple tool invocations, the callback will be executed multiple times.
+  // The provided callbacks are executed sequentially in the exact order they
+  // are given in the list. If a callback returns an overridden response,
+  // execution stops and any remaining callbacks are skipped.
+  repeated Callback after_tool_callbacks = 23
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. Timestamp when the agent was created.
+  google.protobuf.Timestamp create_time = 15
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Timestamp when the agent was last updated.
+  google.protobuf.Timestamp update_time = 16
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. List of guardrails for the agent.
+  // Format:
+  // `projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}`
+  repeated string guardrails = 17 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = { type: "ces.googleapis.com/Guardrail" }
+  ];
+
+  // Etag used to ensure the object hasn't changed during a read-modify-write
+  // operation. If the etag is empty, the update will overwrite any concurrent
+  // changes.
+  string etag = 24;
+
+  // Optional. List of toolsets for the agent.
+  repeated AgentToolset toolsets = 28 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. If the agent is generated by the LLM assistant, this field
+  // contains a descriptive summary of the generation.
+  string generated_summary = 29 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. Agent transfer rules.
+  // If multiple rules match, the first one in the list will be used.
+  repeated TransferRule transfer_rules = 30
+      [(google.api.field_behavior) = OPTIONAL];
+}