// 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.dialogflow.v2beta1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/dialogflow/v2beta1/ces_tool.proto";
import "google/cloud/dialogflow/v2beta1/toolset.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Dialogflow.V2Beta1";
option go_package = "cloud.google.com/go/dialogflow/apiv2beta1/dialogflowpb;dialogflowpb";
option java_multiple_files = true;
option java_outer_classname = "CompanionAgentProto";
option java_package = "com.google.cloud.dialogflow.v2beta1";
option objc_class_prefix = "DF";

// Service for managing companion agents.
service CompanionAgents {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/dialogflow";

  // Creates a companion agent.
  rpc CreateCompanionAgent(CreateCompanionAgentRequest)
      returns (CompanionAgent) {
    option (google.api.http) = {
      post: "/v2beta1/{parent=projects/*/locations/*}/companionAgents"
      body: "companion_agent"
    };
    option (google.api.method_signature) =
        "parent,companion_agent,companion_agent_id";
  }

  // Gets a companion agent.
  rpc GetCompanionAgent(GetCompanionAgentRequest) returns (CompanionAgent) {
    option (google.api.http) = {
      get: "/v2beta1/{name=projects/*/locations/*/companionAgents/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Updates a companion agent.
  rpc UpdateCompanionAgent(UpdateCompanionAgentRequest)
      returns (CompanionAgent) {
    option (google.api.http) = {
      patch: "/v2beta1/{companion_agent.name=projects/*/locations/*/companionAgents/*}"
      body: "companion_agent"
    };
    option (google.api.method_signature) = "companion_agent,update_mask";
  }

  // Deletes a companion agent.
  rpc DeleteCompanionAgent(DeleteCompanionAgentRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v2beta1/{name=projects/*/locations/*/companionAgents/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists companion agents.
  rpc ListCompanionAgents(ListCompanionAgentsRequest)
      returns (ListCompanionAgentsResponse) {
    option (google.api.http) = {
      get: "/v2beta1/{parent=projects/*/locations/*}/companionAgents"
    };
    option (google.api.method_signature) = "parent";
  }
}

// Request of CreateCompanionAgent.
message CreateCompanionAgentRequest {
  // Required. Resource identifier of the project creating the companion agent.
  // Format: `projects/{project}/locations/{location}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/CompanionAgent"
    }
  ];

  // Required. The companion agent to create.
  CompanionAgent companion_agent = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The resource ID of the companion agent to create. If not
  // provided, the server will auto-generate a resource ID.
  string companion_agent_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for GetCompanionAgent.
message GetCompanionAgentRequest {
  // Required. The unique resource identifier of the CompanionAgent to get all
  // information for. Format:
  // `projects/{project}/locations/{location}/companionAgents/{companion_agent}`.
  // Contains the information about the project_id, location_id,
  // companion_agent_id
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/CompanionAgent"
    }
  ];
}

// Request message for ListCompanionAgents.
message ListCompanionAgentsRequest {
  // Required. The parent resource name to list the companion agents for.
  // Format: `projects/{project}/locations/{location}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/CompanionAgent"
    }
  ];

  // Optional. Maximum number of companion agents to return in a single page.
  // By default 100 and at most 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The page token, received from a previous call.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for ListCompanionAgents.
message ListCompanionAgentsResponse {
  // The list of companion agents.
  repeated CompanionAgent companion_agents = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

// Request message for UpdateCompanionAgent.
message UpdateCompanionAgentRequest {
  // Required. The Companion Agent to update.
  CompanionAgent companion_agent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Update mask for Companion Agent.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Request message for DeleteCompanionAgent.
message DeleteCompanionAgentRequest {
  // Required. The unique resource identifier of the CompanionAgent to delete.
  // Format:
  // `projects/{project}/locations/{location}/companionAgents/{companion_agent}`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/CompanionAgent"
    }
  ];
}

// Guidance instruction for the companion agent.
message GuidanceInstruction {
  // Actions to take, including agent action and system action (automation).
  message Action {
    // Required. Description of action item. It can be a agent action (e.g.
    // "Send a message to the customer", "greet the customer") or system action
    // (e.g. "Update the ticket", "Create a task", "cancel the order").
    string description = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // Optional. Display name for the instruction. This name should be unique
  // within the companion agent.
  string display_name = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The detailed description of this instruction.
  string display_details = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The condition of the instruction. For example, "the customer
  // wants to cancel an order".  If the users want the instruction to be
  // triggered unconditionally, the condition can be empty.
  string condition = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The action items that can be processed.
  repeated Action actions = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Event that triggers the guidance instruction.
  // If UNSPECIFIED, the instruction triggering will be the same as the skill's
  // skill_triggering_event.
  CompanionAgent.TriggerEvent trigger_event = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether to disable suggested reply generation for this
  // instruction. When set to `true`, guidance generated from this instruction
  // will not include a suggested reply. Default is `false` (suggested reply
  // enabled).
  bool disable_suggested_reply = 7 [(google.api.field_behavior) = OPTIONAL];
}

// Companion agent.
message CompanionAgent {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/CompanionAgent"
    pattern: "projects/{project}/locations/{location}/companionAgents/{companion_agent}"
    plural: "companionAgents"
    singular: "companionAgent"
  };

  // Event that triggers companion agent skills and guidance instructions.
  enum TriggerEvent {
    // Default value for TriggerEvent.
    // For skill_triggering_event, UNSPECIFIED defaults to CUSTOMER_MESSAGE.
    // For instruction trigger_event, UNSPECIFIED defaults to the skill's
    // skill_triggering_event.
    TRIGGER_EVENT_UNSPECIFIED = 0;

    // Triggers when each chat message or voice utterance ends.
    END_OF_UTTERANCE = 1;

    // Triggers after each customer message.
    CUSTOMER_MESSAGE = 2;

    // Triggers after each agent message.
    AGENT_MESSAGE = 3;
  }

  // Skill configuration for the companion agent.
  message SkillConfig {
    // The event that should trigger the skill.
    enum SkillTriggerEvent {
      // Default value for SkillTriggerEvent.
      SKILL_TRIGGER_EVENT_UNSPECIFIED = 0;

      // Triggers when each chat message or voice utterance ends.
      END_OF_UTTERANCE = 1;

      // Triggers after each customer message.
      CUSTOMER_MESSAGE = 2;

      // Triggers after each agent message.
      AGENT_MESSAGE = 3;
    }

    // Each SkillConfig will be one of the following specific skill configs.
    oneof config {
      // Optional. Guidance skill configuration.
      GuidanceSkillConfig guidance_skill_config = 2
          [(google.api.field_behavior) = OPTIONAL];
    }

    // Optional. The event that should trigger the skill.
    SkillTriggerEvent skill_triggering_event = 1
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Guidance skill configuration.
  message GuidanceSkillConfig {
    // Optional. Customized instructions for guidance.
    repeated GuidanceInstruction guidance_instructions = 2
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. This is specific additional guidance that can configured by the
    // user.
    string overarching_guidance = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Knowledge source configuration for guidance.
    KnowledgeSource knowledge_source = 5
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Knowledge source configuration for knowledge retrieval.
  message KnowledgeSource {}

  // Identifier. The unique identifier of the companion agent.
  // Format:
  // `projects/{project}/locations/{location}/companionAgents/{companion_agent}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. Creation time of this companion agent.
  google.protobuf.Timestamp create_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Update time of this companion agent.
  google.protobuf.Timestamp update_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. List of CES toolset specs that the companion agent can choose
  // from.
  repeated ToolsetTool toolset_tools = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. List of CES tool specs that the companion agent can choose from.
  repeated CesToolSpec ces_tool_specs = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Display name for the companion agent.
  // Character limit is 63.
  string display_name = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Description for the companion agent.
  string description = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. List of skill configs for the companion agent.
  // Allows at most one instance of each
  // [SkillConfig][google.cloud.dialogflow.v2beta1.CompanionAgent.SkillConfig]
  // type.
  repeated SkillConfig skill_configs = 7
      [(google.api.field_behavior) = OPTIONAL];
}