// 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];
}