REST Resource: projects.locations.tools

Resource: Tool

Represents a tool.

JSON representation 
{
  "name": string,
  "toolKey": string,
  "displayName": string,
  "description": string,
  "actionConfirmationRequirement": {
    string: enum (ConfirmationRequirement),
    ...
  },
  "createTime": string,
  "updateTime": string,

  // Union field specification can be only one of the following:
  "extensionSpec": {
    object (ExtensionTool)
  },
  "functionSpec": {
    object (FunctionTool)
  },
  "connectorSpec": {
    object (ConnectorTool)
  },
  "openApiSpec": {
    object (OpenApiTool)
  }
  // End of list of possible types for union field specification.
  "satisfiesPzs": boolean,
  "satisfiesPzi": boolean
}
Fields
name

string

Output only. Identifier. The resource name of the tool. Format: projects/<Project ID>/locations/<Location ID>/tools/<Tool ID>.
toolKey

string

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.
displayName

string

Optional. A human readable short name of the tool, to be shown on the UI.
description

string

Optional. A human readable description of the tool.
actionConfirmationRequirement

map (key: string, value: enum (ConfirmationRequirement))

Optional. Confirmation requirement for the actions. Each key is an action name in the actionSchemas. 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 methodType - confirmation is not required if and only if methodType is GET.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
createTime

string (Timestamp format)

Output only. Creation time of this tool.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Update time of this tool.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
Union field specification. Specification of the Tool. specification can be only one of the following:
extensionSpec
(deprecated)

object (ExtensionTool)

Vertex extension tool specification.
functionSpec

object (FunctionTool)

Client side executed function specification.
connectorSpec

object (ConnectorTool)

Integration connectors tool specification.
openApiSpec

object (OpenApiTool)

OpenAPI tool.
satisfiesPzs

boolean

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.
satisfiesPzi

boolean

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.

ConfirmationRequirement

Types of confirmation requirement.

Enums
CONFIRMATION_REQUIREMENT_UNSPECIFIED Unspecified. Whether the action requires confirmation is inferred from methodType.
REQUIRED Conformation is required.
NOT_REQUIRED Conformation is not required.

ExtensionTool

An ExtensionTool is a way to use Vertex Extensions as a tool.

JSON representation 
{
  "name": string
}
Fields
name

string

Required. The full name of the referenced vertex extension. Format: projects/{project}/locations/{location}/extensions/{extension}

FunctionTool

A Function tool describes the functions to be invoked on the client side.

JSON representation 
{
  "inputSchema": {
    object
  },
  "outputSchema": {
    object
  },
  "methodType": enum (MethodType)
}
Fields
inputSchema

object (Struct format)

Optional. The JSON schema is encapsulated in a 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.
outputSchema

object (Struct format)

Optional. The JSON schema is encapsulated in a 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.
methodType

enum (MethodType)

Optional. The method type of the function. If not specified, the default value is GET.

MethodType

The method type of the tool.

Enums
METHOD_TYPE_UNSPECIFIED Unspecified.
GET GET method.
POST POST method.
PUT PUT method.
DELETE DELETE method.
PATCH PATCH method.

ConnectorTool

A ConnectorTool enabling using Integration Connectors Connections as tools.

JSON representation 
{
  "name": string,
  "actions": [
    {
      object (Action)
    }
  ]
}
Fields
name

string

Required. The full resource name of the referenced Integration Connectors Connection. Format: 'projects/*/locations/*/connections/*'
actions[]

object (Action)

Required. Actions for the tool to use.

Action

Configuration of a Connection operation for the tool to use.

JSON representation 
{
  "inputFields": [
    string
  ],
  "outputFields": [
    string
  ],

  // Union field action_spec can be only one of the following:
  "connectionActionId": string,
  "entityOperation": {
    object (EntityOperation)
  }
  // End of list of possible types for union field action_spec.
}
Fields
inputFields[]

string

Optional. Entity fields to use as inputs for the operation. If no fields are specified, all fields of the Entity will be used.
outputFields[]

string

Optional. Entity fields to return from the operation. If no fields are specified, all fields of the Entity will be returned.
Union field action_spec. Required. Specification for an action to configure for the tool to use. action_spec can be only one of the following:
connectionActionId

string

ID of a Connection action for the tool to use.
entityOperation

object (EntityOperation)

Entity operation configuration for the tool to use.

EntityOperation

Entity CRUD operation specification.

JSON representation 
{
  "entityId": string,
  "operation": enum (OperationType)
}
Fields
entityId

string

Required. ID of the entity.
operation

enum (OperationType)

Required. Operation to perform on the entity.

OperationType

The operation to perform on the entity.

Enums
OPERATION_TYPE_UNSPECIFIED Operation type unspecified. Invalid, ConnectorTool create/update will fail.
LIST List operation.
GET Get operation.
CREATE Create operation.
UPDATE Update operation.
DELETE Delete operation.

OpenApiTool

An OpenAPI tool is a way to provide the Tool specifications in the Open API schema format.

JSON representation 
{
  "authentication": {
    object (Authentication)
  },
  "tlsConfig": {
    object (TLSConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },

  // Union field schema can be only one of the following:
  "textSchema": string
  // End of list of possible types for union field schema.
}
Fields
authentication

object (Authentication)

Optional. Authentication information required by the API.
tlsConfig

object (TLSConfig)

Optional. TLS configuration for the HTTPS verification.
serviceDirectoryConfig

object (ServiceDirectoryConfig)

Optional. Service Directory configuration.
Union field schema. Schema representation. schema can be only one of the following:
textSchema

string

Required. The OpenAPI schema specified as a text.

Authentication

Authentication information required for API calls

JSON representation 
{

  // Union field auth_config can be only one of the following:
  "apiKeyConfig": {
    object (ApiKeyConfig)
  },
  "oauthConfig": {
    object (OAuthConfig)
  },
  "serviceAgentAuthConfig": {
    object (ServiceAgentAuthConfig)
  },
  "bearerTokenConfig": {
    object (BearerTokenConfig)
  }
  // End of list of possible types for union field auth_config.
}
Fields
Union field auth_config. The auth configuration. auth_config can be only one of the following:
apiKeyConfig

object (ApiKeyConfig)

Config for API key auth.
oauthConfig

object (OAuthConfig)

Config for OAuth.
serviceAgentAuthConfig

object (ServiceAgentAuthConfig)

Config for Diglogflow service agent auth.
bearerTokenConfig

object (BearerTokenConfig)

Config for bearer token auth.

ApiKeyConfig

Config for authentication with API key.

JSON representation 
{
  "keyName": string,
  "apiKey": string,
  "secretVersionForApiKey": string,
  "requestLocation": enum (RequestLocation)
}
Fields
keyName

string

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=", "X-Api-Key" would be the parameter name.
apiKey

string

Optional. The API key. If the secretVersionForApiKey field is set, this field will be ignored.
secretVersionForApiKey

string

Optional. The name of the SecretManager secret version resource storing the API key. If this field is set, the apiKey field will be ignored. Format: projects/{project}/secrets/{secret}/versions/{version}
requestLocation

enum (RequestLocation)

Required. Key location in the request.

RequestLocation

The location of the API key in the request.

Enums
REQUEST_LOCATION_UNSPECIFIED Default value. This value is unused.
HEADER Represents the key in http header.
QUERY_STRING Represents the key in query string.

OAuthConfig

Config for authentication with OAuth.

JSON representation 
{
  "oauthGrantType": enum (OauthGrantType),
  "clientId": string,
  "clientSecret": string,
  "secretVersionForClientSecret": string,
  "tokenEndpoint": string,
  "scopes": [
    string
  ]
}
Fields
oauthGrantType

enum (OauthGrantType)

Required. OAuth grant types.
clientId

string

Required. The client ID from the OAuth provider.
clientSecret

string

Optional. The client secret from the OAuth provider. If the secretVersionForClientSecret field is set, this field will be ignored.
secretVersionForClientSecret

string

Optional. The name of the SecretManager secret version resource storing the client secret. If this field is set, the clientSecret field will be ignored. Format: projects/{project}/secrets/{secret}/versions/{version}
tokenEndpoint

string

Required. The token endpoint in the OAuth provider to exchange for an access token.
scopes[]

string

Optional. The OAuth scopes to grant.

OauthGrantType

OAuth grant types. Only client credential grant is supported.

Enums
OAUTH_GRANT_TYPE_UNSPECIFIED Default value. This value is unused.
CLIENT_CREDENTIAL Represents the client credential flow.

ServiceAgentAuthConfig

Config for auth using Dialogflow service agent.

JSON representation 
{
  "serviceAgentAuth": enum (ServiceAgentAuth)
}
Fields
serviceAgentAuth

enum (ServiceAgentAuth)

Optional. Indicate the auth token type generated from the Diglogflow service agent. The generated token is sent in the Authorization header.

ServiceAgentAuth

Indicate the auth token type generated from the Diaglogflow service agent.

Enums
SERVICE_AGENT_AUTH_UNSPECIFIED Service agent auth type unspecified. Default to ID_TOKEN.
ID_TOKEN Use ID token 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.
ACCESS_TOKEN Use access token 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.

BearerTokenConfig

Config for authentication using bearer token.

JSON representation 
{
  "token": string,
  "secretVersionForToken": string
}
Fields
token

string

Optional. The text token appended to the text Bearer to the request Authorization header. Session parameters reference can be used to pass the token dynamically, e.g. $session.params.parameter-id.
secretVersionForToken

string

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}

TLSConfig

The TLS configuration.

JSON representation 
{
  "caCerts": [
    {
      object (CACert)
    }
  ]
}
Fields
caCerts[]

object (CACert)

Required. Specifies a list of allowed custom CA certificates for HTTPS verification.

CACert

The CA certificate.

JSON representation 
{
  "displayName": string,
  "cert": string
}
Fields
displayName

string

Required. The name of the allowed custom CA certificates. This can be used to disambiguate the custom CA certificates.
cert

string (bytes format)

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'")

A base64-encoded string.

ServiceDirectoryConfig

Configuration for tools using Service Directory.

JSON representation 
{
  "service": string
}
Fields
service

string

Required. The name of 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.

Methods

create

 Creates a tool.

delete

 Deletes a tool.

get

 Retrieves a tool.

list

 Lists tools.

patch

 Updates a tool.