// 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.v2;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Dialogflow.V2";
option go_package = "cloud.google.com/go/dialogflow/apiv2/dialogflowpb;dialogflowpb";
option java_multiple_files = true;
option java_outer_classname = "ToolCallProto";
option java_package = "com.google.cloud.dialogflow.v2";
option objc_class_prefix = "DF";

// Represents a call of a specific tool's action with the specified inputs.
message ToolCall {
  // Tool call states.
  enum State {
    // Default value.
    STATE_UNSPECIFIED = 0;

    // The tool call has been triggered.
    TRIGGERED = 1;

    // The tool call requires confirmation from a human.
    NEEDS_CONFIRMATION = 2;
  }

  // Specifies the source of this tool call.
  oneof source {
    // Optional. The [tool][google.cloud.dialogflow.v2.Tool] associated with
    // this call. Format:
    // `projects/<ProjectID>/locations/<LocationID>/tools/<ToolID>`.
    string tool = 1 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = {
        type: "dialogflow.googleapis.com/Tool"
      }
    ];

    // Optional. CES tool name for this call.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/apps/<AppID>/tools/<ToolID>`.
    string ces_tool = 11 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
    ];

    // Optional. CES toolset name for this call.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/apps/<AppID>/toolsets/ToolsetID>`.
    string ces_toolset = 12 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/Toolset" }
    ];

    // Optional. CES app name for this call.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/apps/<AppID>`.
    string ces_app = 8 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/App" }
    ];
  }

  // Optional. A human readable short name of the tool, to be shown on the UI.
  string tool_display_name = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A human readable description of the tool.
  string tool_display_details = 10 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The name of the tool's action associated with this call.
  string action = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The action's input parameters.
  google.protobuf.Struct input_parameters = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. Create time of the tool call.
  google.protobuf.Timestamp create_time = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The answer record associated with this tool call.
  string answer_record = 6 [(google.api.field_behavior) = OPTIONAL];

  // Output only. State of the tool call.
  State state = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The result of calling a tool's action.
message ToolCallResult {
  // An error produced by the tool call.
  message Error {
    // Optional. The error message of the function.
    string message = 1 [(google.api.field_behavior) = OPTIONAL];
  }

  // Specifies the source of this tool call.
  oneof source {
    // Optional. The [tool][google.cloud.dialogflow.v2.Tool] associated with
    // this call. Format:
    // `projects/<ProjectID>/locations/<LocationID>/tools/<ToolID>`.
    string tool = 1 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = {
        type: "dialogflow.googleapis.com/Tool"
      }
    ];

    // Optional. CES toolset name for this call.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/apps/<AppID>/toolsets/ToolsetID>`.
    string ces_toolset = 13 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/Toolset" }
    ];

    // Optional. CES tool name for this call.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/apps/<AppID>/tools/<ToolID>`.
    string ces_tool = 12 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
    ];

    // Optional. CES app name for this call.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/apps/<AppID>`.
    string ces_app = 11 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/App" }
    ];
  }

  // Optional. The name of the tool's action associated with this call.
  string action = 2 [(google.api.field_behavior) = OPTIONAL];

  // The tool call's result.
  oneof result {
    // The tool call's error.
    Error error = 3;

    // Only populated if the response content is not utf-8 encoded.
    // (by definition byte fields are base64 encoded).
    bytes raw_content = 5;

    // Only populated if the response content is utf-8 encoded.
    string content = 6;
  }

  // Output only. Create time of the tool call result.
  google.protobuf.Timestamp create_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The answer record associated with this tool call result.
  string answer_record = 9 [(google.api.field_behavior) = OPTIONAL];
}