// 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.geminidataanalytics.v1beta;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/geminidataanalytics/v1beta/data_analytics_agent.proto";
import "google/cloud/geminidataanalytics/v1beta/datasource.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Beta";
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1beta/geminidataanalyticspb;geminidataanalyticspb";
option java_multiple_files = true;
option java_outer_classname = "DataAgentProto";
option java_package = "com.google.cloud.geminidataanalytics.v1beta";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1beta";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1beta";

// Message describing a DataAgent object.
message DataAgent {
  option (google.api.resource) = {
    type: "geminidataanalytics.googleapis.com/DataAgent"
    pattern: "projects/{project}/locations/{location}/dataAgents/{data_agent}"
    plural: "dataAgents"
    singular: "dataAgent"
  };

  // The type of the agent. Can be one of the following:
  // * Data analytics agent.
  // * Data engineering agent
  oneof type {
    // Data analytics agent.
    DataAnalyticsAgent data_analytics_agent = 101;
  }

  // Optional. Identifier. The unique resource name of a DataAgent.
  // Format:
  // `projects/{project}/locations/{location}/dataAgents/{data_agent_id}`
  // `{data_agent}` is the resource id and should be 63 characters or less and
  // must match the format described in
  // https://google.aip.dev/122#resource-id-segments
  //
  // Example: `projects/1234567890/locations/global/dataAgents/my-agent`.
  //
  // It is recommended to skip setting this field during agent creation as it
  // will be inferred automatically and overwritten with the
  // {parent}/dataAgents/{data_agent_id}.
  string name = 1 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = IDENTIFIER
  ];

  // Optional. User friendly display name.
  //
  // * Must be between 1-256 characters.
  string display_name = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Description of the agent.
  //
  // * Must be between 1-1024 characters.
  string description = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Labels to help users filter related agents.
  // For example, "sales", "business", "etl", and so on.
  // Note labels are used only for filtering and not for policies.
  // See the [labels
  // documentation](https://cloud.google.com/resource-manager/docs/labels-overview)
  // for more details on label usage.
  map<string, string> labels = 5 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The time when the data agent was created.
  google.protobuf.Timestamp create_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the data agent was last updated.
  google.protobuf.Timestamp update_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. [Output only] The time the data agent was soft deleted.
  google.protobuf.Timestamp delete_time = 12
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Timestamp in UTC of when this data agent is considered
  // expired. This is *always* provided on output, regardless of what was sent
  // on input.
  google.protobuf.Timestamp purge_time = 13
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Customer managed encryption key (CMEK) to use for encrypting the
  // DataAgent resources. Cloud KMS CryptoKeys must reside in the same location
  // as the DataAgent. The expected format is
  // `projects/*/locations/*/keyRings/*/cryptoKeys/*`.
  optional string kms_key = 14 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {
      type: "cloudkms.googleapis.com/CryptoKey"
    }
  ];

  // Optional. Controls whether BigQuery Agent Analytics trace logging is
  // enabled for the agent.
  //
  // BigQuery Agent Analytics is in Preview and is delivered to enrolled
  // projects only. In a project that is not enrolled this field is accepted
  // and stored, but no trace rows are written and no error is returned.
  //
  // Trace logging is additionally suppressed for the entire turn, without
  // error, when any table in the agent's datasource carries row-level
  // security, column-level security or policy tags. It is also suppressed
  // when that determination cannot be made, for example when the caller
  // lacks permission to list a table's row access policies.
  //
  // Trace rows are written only when this is `true` and
  // `bigquery_agent_analytics_table` is set. On a BigQuery agent, enabling
  // this without a table has no effect: no table is created for the agent
  // and no rows are written. On an agent whose datasource is not BigQuery,
  // `CreateDataAgent` rejects either field with `INVALID_ARGUMENT`.
  //
  // This setting is independent of the project-level BigQuery Agent Analytics
  // setting configured through `SetAgentOpsObservability`. An agent does not
  // inherit that setting.
  optional bool bigquery_agent_analytics_enabled = 18
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The BigQuery table that BigQuery Agent Analytics trace rows are
  // written to. Has no effect unless `bigquery_agent_analytics_enabled` is
  // `true`. The Preview enrollment described on that field applies here too.
  //
  // The trace table is validated when it is set on `CreateDataAgent`, or when
  // it is included in the `update_mask` of an `UpdateDataAgent` call. The
  // following are rejected with `INVALID_ARGUMENT`:
  //
  // * The table must belong to the same project as the agent.
  // * The agent's datasource must be BigQuery. BigQuery Agent Analytics is not
  //   supported for Looker, Looker Studio or AlloyDB agents.
  //
  // These are validated against the agent as sent in the request. An agent
  // that carries no datasource is not validated, and an agent switched to a
  // non-BigQuery datasource is not re-validated; in the latter case no trace
  // rows are written.
  //
  // The destination dataset must already exist and must grant write access to
  // the project's Gemini Data Analytics service agent, whose address is
  // `service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com`
  // (that grant is not performed on your behalf). Without it the agent answers
  // normally and no trace rows are written.
  //
  // Changing the table on an existing agent affects subsequent turns only. Rows
  // already written to the previous table are left in place.
  BigQueryTableReference bigquery_agent_analytics_table = 19
      [(google.api.field_behavior) = OPTIONAL];
}