googleapis/google/cloud/dialogflow/v2beta1/tool.proto

// 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/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.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 = "ToolProto";
option java_package = "com.google.cloud.dialogflow.v2beta1";
option objc_class_prefix = "DF";
option (google.api.resource_definition) = {
  type: "secretmanager.googleapis.com/SecretVersion"
  pattern: "projects/{project}/secrets/{secret}/versions/{version}"
};

// Tool Service for LLM powered Agent Assist. Tools can be used to interact with
// remote APIs (e.g. fetching orders) to retrieve additional information as
// input to LLM.
service Tools {
  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 tool.
  rpc CreateTool(CreateToolRequest) returns (Tool) {
    option (google.api.http) = {
      post: "/v2beta1/{parent=projects/*/locations/*}/tools"
      body: "tool"
    };
    option (google.api.method_signature) = "parent,tool,tool_id";
  }

  // Retrieves a tool.
  rpc GetTool(GetToolRequest) returns (Tool) {
    option (google.api.http) = {
      get: "/v2beta1/{name=projects/*/locations/*/tools/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists tools.
  rpc ListTools(ListToolsRequest) returns (ListToolsResponse) {
    option (google.api.http) = {
      get: "/v2beta1/{parent=projects/*/locations/*}/tools"
    };
    option (google.api.method_signature) = "parent";
  }

  // Deletes a tool.
  rpc DeleteTool(DeleteToolRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v2beta1/{name=projects/*/locations/*/tools/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Updates a tool.
  rpc UpdateTool(UpdateToolRequest) returns (Tool) {
    option (google.api.http) = {
      patch: "/v2beta1/{tool.name=projects/*/locations/*/tools/*}"
      body: "tool"
    };
    option (google.api.method_signature) = "tool,update_mask";
  }
}

// Request message of CreateTool.
message CreateToolRequest {
  // Required. The project/location to create tool for. Format:
  // `projects/<Project ID>/locations/<Location ID>`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Tool"
    }
  ];

  // Required. The tool to create.
  Tool tool = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The ID to use for the tool, which will become the final
  // component of the tool's resource name.
  //
  // The tool ID must be compliant with the regression formula
  // `[a-zA-Z][a-zA-Z0-9_-]*` with the characters length in range of [3,64].
  // If the field is not provide, an Id will be auto-generated.
  // If the field is provided, the caller is responsible for
  // 1. the uniqueness of the ID, otherwise the request will be rejected.
  // 2. the consistency for whether to use custom ID or not under a project to
  // better ensure uniqueness.
  string tool_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message of GetTool.
message GetToolRequest {
  // Required. The tool resource name to retrieve. Format:
  // `projects/<Project ID>/locations/<Location ID>/tools/<Tool ID>`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Tool" }
  ];
}

// Request message of ListTools.
message ListToolsRequest {
  // Required. The project/location to list tools for. Format:
  // `projects/<Project ID>/locations/<Location ID>`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Tool"
    }
  ];

  // Optional. Maximum number of conversation models to return in a single page.
  // Default to 10.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response of ListTools.
message ListToolsResponse {
  // List of tools retrieved.
  repeated Tool tools = 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 of DeleteTool.
message DeleteToolRequest {
  // Required. The tool resource name to delete. Format:
  // `projects/<Project ID>/locations/<Location ID>/tools/<Tool ID>`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Tool" }
  ];
}

// Request of UpdateTool.
message UpdateToolRequest {
  // Required. The tool to update.
  // The name field of tool is to identify the tool to
  // update.
  Tool tool = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The list of fields to update.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Represents a tool.
message Tool {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/Tool"
    pattern: "projects/{project}/locations/{location}/tools/{tool}"
    plural: "tools"
    singular: "tool"
  };

  // Types of confirmation requirement.
  enum ConfirmationRequirement {
    // Unspecified. Whether the action requires confirmation is inferred from
    // method_type.
    CONFIRMATION_REQUIREMENT_UNSPECIFIED = 0;

    // Conformation is required.
    REQUIRED = 1;

    // Conformation is not required.
    NOT_REQUIRED = 2;
  }

  // The method type of the function.
  enum MethodType {
    // Unspecified.
    METHOD_TYPE_UNSPECIFIED = 0;

    // GET method.
    GET = 1;

    // POST method.
    POST = 2;

    // PUT method.
    PUT = 3;

    // DELETE method.
    DELETE = 4;

    // PATCH method.
    PATCH = 5;
  }

  // An ExtensionTool is a way to use Vertex Extensions as a tool.
  message ExtensionTool {
    // Required. The full name of the referenced vertex extension.
    // Format:
    // `projects/{project}/locations/{location}/extensions/{extension}`
    string name = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // A Function tool describes the functions to be invoked on the client side.
  message FunctionTool {
    // Optional. The JSON schema is encapsulated in a
    // [google.protobuf.Struct][google.protobuf.Struct] to describe the input of
    // the function. This input is a JSON object that contains the function's
    // parameters as properties of the object.
    google.protobuf.Struct input_schema = 1
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The JSON schema is encapsulated in a
    // [google.protobuf.Struct][google.protobuf.Struct] to describe the output
    // of the function. This output is a JSON object that contains the
    // function's parameters as properties of the object.
    google.protobuf.Struct output_schema = 2
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The method type of the function. If not specified, the default
    // value is GET.
    MethodType method_type = 4 [(google.api.field_behavior) = OPTIONAL];
  }

  // An OpenAPI tool is a way to provide the Tool specifications in the Open API
  // schema format.
  message OpenApiTool {
    // Schema representation.
    oneof schema {
      // Required. The OpenAPI schema specified as a text.
      string text_schema = 1 [(google.api.field_behavior) = REQUIRED];
    }

    // Optional. Authentication information required by the API.
    Authentication authentication = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. TLS configuration for the HTTPS verification.
    TLSConfig tls_config = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Service Directory configuration.
    ServiceDirectoryConfig service_directory_config = 4
        [(google.api.field_behavior) = OPTIONAL];
  }

  // A ConnectorTool enabling using Integration Connectors Connections as tools.
  message ConnectorTool {
    // Configuration of a Connection operation for the tool to use.
    message Action {
      // Entity CRUD operation specification.
      message EntityOperation {
        // The operation to perform on the entity.
        enum OperationType {
          // Operation type unspecified. Invalid, ConnectorTool create/update
          // will fail.
          OPERATION_TYPE_UNSPECIFIED = 0;

          // List operation.
          LIST = 1;

          // Get operation.
          GET = 2;

          // Create operation.
          CREATE = 3;

          // Update operation.
          UPDATE = 4;

          // Delete operation.
          DELETE = 5;
        }

        // Required. ID of the entity.
        string entity_id = 1 [(google.api.field_behavior) = REQUIRED];

        // Required. Operation to perform on the entity.
        OperationType operation = 2 [(google.api.field_behavior) = REQUIRED];
      }

      // Required. Specification for an action to configure for the tool to use.
      oneof action_spec {
        // ID of a Connection action for the tool to use.
        string connection_action_id = 4;

        // Entity operation configuration for the tool to use.
        EntityOperation entity_operation = 5;
      }

      // Optional. Entity fields to use as inputs for the operation.
      // If no fields are specified, all fields of the Entity will be used.
      repeated string input_fields = 2 [(google.api.field_behavior) = OPTIONAL];

      // Optional. Entity fields to return from the operation.
      // If no fields are specified, all fields of the Entity will be returned.
      repeated string output_fields = 3
          [(google.api.field_behavior) = OPTIONAL];
    }

    // Required. The full resource name of the referenced Integration Connectors
    // Connection. Format: 'projects/*/locations/*/connections/*'
    string name = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Actions for the tool to use.
    repeated Action actions = 2 [(google.api.field_behavior) = REQUIRED];
  }

  // Authentication information required for API calls
  message Authentication {
    // Config for authentication with API key.
    message ApiKeyConfig {
      // Required. The parameter name or the header name of the API key.
      // E.g., If the API request is "https://example.com/act?X-Api-Key=<API
      // KEY>", "X-Api-Key" would be the parameter name.
      string key_name = 1 [(google.api.field_behavior) = REQUIRED];

      // Optional. The API key. If the `secret_version_for_api_key` field is
      // set, this field will be ignored.
      string api_key = 2 [(google.api.field_behavior) = OPTIONAL];

      // Optional. The name of the SecretManager secret version resource storing
      // the API key. If this field is set, the `api_key` field will be ignored.
      // Format: `projects/{project}/secrets/{secret}/versions/{version}`
      string secret_version_for_api_key = 4 [
        (google.api.field_behavior) = OPTIONAL,
        (google.api.resource_reference) = {
          type: "secretmanager.googleapis.com/SecretVersion"
        }
      ];

      // Required. Key location in the request.
      RequestLocation request_location = 3
          [(google.api.field_behavior) = REQUIRED];
    }

    // The location of the API key in the request.
    enum RequestLocation {
      // Default value. This value is unused.
      REQUEST_LOCATION_UNSPECIFIED = 0;

      // Represents the key in http header.
      HEADER = 1;

      // Represents the key in query string.
      QUERY_STRING = 2;
    }

    // Config for authentication with OAuth.
    message OAuthConfig {
      // OAuth grant types. Only [client credential
      // grant](https://oauth.net/2/grant-types/client-credentials) is
      // supported.
      enum OauthGrantType {
        // Default value. This value is unused.
        OAUTH_GRANT_TYPE_UNSPECIFIED = 0;

        // Represents the [client credential
        // flow](https://oauth.net/2/grant-types/client-credentials).
        CLIENT_CREDENTIAL = 1;
      }

      // Required. OAuth grant types.
      OauthGrantType oauth_grant_type = 1
          [(google.api.field_behavior) = REQUIRED];

      // Required. The client ID from the OAuth provider.
      string client_id = 2 [(google.api.field_behavior) = REQUIRED];

      // Optional. The client secret from the OAuth provider. If the
      // `secret_version_for_client_secret` field is set, this field will be
      // ignored.
      string client_secret = 3 [(google.api.field_behavior) = OPTIONAL];

      // Optional. The name of the SecretManager secret version resource storing
      // the client secret. If this field is set, the `client_secret` field will
      // be ignored. Format:
      // `projects/{project}/secrets/{secret}/versions/{version}`
      string secret_version_for_client_secret = 6 [
        (google.api.field_behavior) = OPTIONAL,
        (google.api.resource_reference) = {
          type: "secretmanager.googleapis.com/SecretVersion"
        }
      ];

      // Required. The token endpoint in the OAuth provider to exchange for an
      // access token.
      string token_endpoint = 4 [(google.api.field_behavior) = REQUIRED];

      // Optional. The OAuth scopes to grant.
      repeated string scopes = 5 [(google.api.field_behavior) = OPTIONAL];
    }

    // Config for auth using [Dialogflow service
    // agent](https://cloud.google.com/iam/docs/service-agents#dialogflow-service-agent).
    message ServiceAgentAuthConfig {
      // Indicate the auth token type generated from the [Diaglogflow service
      // agent](https://cloud.google.com/iam/docs/service-agents#dialogflow-service-agent).
      enum ServiceAgentAuth {
        // Service agent auth type unspecified. Default to ID_TOKEN.
        SERVICE_AGENT_AUTH_UNSPECIFIED = 0;

        // Use [ID
        // token](https://cloud.google.com/docs/authentication/token-types#id)
        // generated from service agent. This can be used to access Cloud
        // Function and Cloud Run after you grant Invoker role to
        // `service-<PROJECT-NUMBER>@gcp-sa-dialogflow.iam.gserviceaccount.com`.
        ID_TOKEN = 1;

        // Use [access
        // token](https://cloud.google.com/docs/authentication/token-types#access)
        // generated from service agent. This can be used to access other Google
        // Cloud APIs after you grant required roles to
        // `service-<PROJECT-NUMBER>@gcp-sa-dialogflow.iam.gserviceaccount.com`.
        ACCESS_TOKEN = 2;
      }

      // Optional. Indicate the auth token type generated from the [Diglogflow
      // service
      // agent](https://cloud.google.com/iam/docs/service-agents#dialogflow-service-agent).
      // The generated token is sent in the Authorization header.
      ServiceAgentAuth service_agent_auth = 1
          [(google.api.field_behavior) = OPTIONAL];
    }

    // Config for authentication using bearer token.
    message BearerTokenConfig {
      // Optional. The text token appended to the text `Bearer` to the request
      // Authorization header.
      // [Session parameters
      // reference](https://cloud.google.com/dialogflow/cx/docs/concept/parameter#session-ref)
      // can be used to pass the token dynamically, e.g.
      // `$session.params.parameter-id`.
      string token = 1 [(google.api.field_behavior) = OPTIONAL];

      // Optional. The name of the SecretManager secret version resource storing
      // the Bearer token. If this field is set, the `token` field will be
      // ignored. Format:
      // `projects/{project}/secrets/{secret}/versions/{version}`
      string secret_version_for_token = 2 [
        (google.api.field_behavior) = OPTIONAL,
        (google.api.resource_reference) = {
          type: "secretmanager.googleapis.com/SecretVersion"
        }
      ];
    }

    // The auth configuration.
    oneof auth_config {
      // Config for API key auth.
      ApiKeyConfig api_key_config = 1;

      // Config for OAuth.
      OAuthConfig oauth_config = 2;

      // Config for [Diglogflow service
      // agent](https://cloud.google.com/iam/docs/service-agents#dialogflow-service-agent)
      // auth.
      ServiceAgentAuthConfig service_agent_auth_config = 3;

      // Config for bearer token auth.
      BearerTokenConfig bearer_token_config = 4;
    }
  }

  // The TLS configuration.
  message TLSConfig {
    // The CA certificate.
    message CACert {
      // Required. The name of the allowed custom CA certificates. This
      // can be used to disambiguate the custom CA certificates.
      string display_name = 1 [(google.api.field_behavior) = REQUIRED];

      // Required. The allowed custom CA certificates (in DER format) for
      // HTTPS verification. This overrides the default SSL trust store. If this
      // is empty or unspecified, Dialogflow will use Google's default trust
      // store to verify certificates. N.B. Make sure the HTTPS server
      // certificates are signed with "subject alt name". For instance a
      // certificate can be self-signed using the following command,
      // ```
      //    openssl x509 -req -days 200 -in example.com.csr \
      //      -signkey example.com.key \
      //      -out example.com.crt \
      //      -extfile <(printf "\nsubjectAltName='DNS:www.example.com'")
      // ```
      bytes cert = 2 [(google.api.field_behavior) = REQUIRED];
    }

    // Required. Specifies a list of allowed custom CA certificates for HTTPS
    // verification.
    repeated CACert ca_certs = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // Configuration for tools using Service Directory.
  message ServiceDirectoryConfig {
    // Required. The name of [Service
    // Directory](https://cloud.google.com/service-directory) service.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/namespaces/<NamespaceID>/services/<ServiceID>`.
    // `LocationID` of the service directory must be the same as the location
    // of the tool.
    string service = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {
        type: "servicedirectory.googleapis.com/Service"
      }
    ];
  }

  // Output only. Identifier. The resource name of the tool. Format:
  // `projects/<Project ID>/locations/<Location ID>/tools/<Tool ID>`.
  string name = 1 [
    (google.api.field_behavior) = IDENTIFIER,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Required. A human readable short name of the tool, which should be unique
  // within the project. It should only contain letters, numbers, and
  // underscores, and it will be used by LLM to identify the tool.
  string tool_key = 2 [(google.api.field_behavior) = REQUIRED];

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

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

  // Optional. Confirmation requirement for the actions. Each key is an action
  // name in the action_schemas. If an action's confirmation requirement is
  // unspecified (either the key is not present, or its value is
  // CONFIRMATION_REQUIREMENT_UNSPECIFIED), the requirement is inferred from the
  // action's method_type - confirmation is not required if and only if
  // method_type is GET.
  map<string, ConfirmationRequirement> action_confirmation_requirement = 17
      [(google.api.field_behavior) = OPTIONAL];

  // Specification of the Tool.
  oneof specification {
    // Vertex extension tool specification.
    ExtensionTool extension_spec = 4 [deprecated = true];

    // Client side executed function specification.
    FunctionTool function_spec = 13;

    // Integration connectors tool specification.
    ConnectorTool connector_spec = 18;

    // OpenAPI tool.
    OpenApiTool open_api_spec = 20;
  }

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

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

  // Output only. A read only boolean field reflecting Zone Separation
  // status of the tool. If the field is absent, it means the status is unknown.
  optional bool satisfies_pzs = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A read only boolean field reflecting Zone Isolation status
  // of the tool. If the field is absent, it means the status is unknown.
  optional bool satisfies_pzi = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
}