REST Resource: projects.locations.agents.tools

Resource: Tool

A tool provides a list of actions which are available to the Playbook to attain its goal. A Tool consists of a description of the tool's usage and a specification of the tool which contains the schema and authentication information.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "toolType": enum (ToolType),

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

string

The unique identifier of the Tool. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/tools/<ToolID>.
displayName

string

Required. The human-readable name of the Tool, unique within an agent.
description

string

Required. High level description of the Tool and its usage.
toolType

enum (ToolType)

Output only. The tool type.
Union field specification. Specification of the Tool. specification can be only one of the following:
openApiSpec

object (OpenApiTool)

OpenAPI specification of the Tool.
dataStoreSpec

object (DataStoreTool)

Data store search tool specification.
extensionSpec

object (ExtensionTool)

Vertex extension tool specification.
functionSpec

object (FunctionTool)

Client side executed function specification.
connectorSpec

object (ConnectorTool)

Integration connectors tool specification.

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,
  "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.
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,
  "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.
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 Diglogflow 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 Diglogflow 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
}
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.

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

DataStoreTool

A DataStoreTool is a way to provide specifications needed to search a list of data stores.

JSON representation 
{
  "dataStoreConnections": [
    {
      object (DataStoreConnection)
    }
  ],
  "fallbackPrompt": {
    object (FallbackPrompt)
  }
}
Fields
dataStoreConnections[]

object (DataStoreConnection)

Required. List of data stores to search.
fallbackPrompt

object (FallbackPrompt)

Required. Fallback prompt configurations to use.

FallbackPrompt

This type has no fields.

A FallbackPrompt is a way to provide specifications for the Data Store fallback prompt when generating responses.

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. Formats: 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
  }
}
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.

ConnectorTool

A ConnectorTool enabling using Integration Connectors Connections as tools.

JSON representation 
{
  "name": string,
  "actions": [
    {
      object (Action)
    }
  ],
  "endUserAuthConfig": {
    object (EndUserAuthConfig)
  }
}
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.
endUserAuthConfig

object (EndUserAuthConfig)

Optional. Integration Connectors end-user authentication configuration. If configured, the end-user authentication fields will be passed in the Integration Connectors API request and override the admin, default authentication configured for the Connection. Note: The Connection must have authentication override enabled in order to specify an EUC configuration here - otherwise, the ConnectorTool creation will fail. See: https://cloud.google.com/application-integration/docs/configure-connectors-task#configure-authentication-override

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.

EndUserAuthConfig

End-user authentication configuration used for Connection calls. The field values can either be hardcoded authentication values or the names of session parameters or request parameters.

If parameter names are provided, then those parameters can be used to pass the authentication values dynamically, through $session.params.param-id or $request.payload.param-id.

JSON representation 
{

  // Union field end_user_auth_config can be only one of the following:
  "oauth2AuthCodeConfig": {
    object (Oauth2AuthCodeConfig)
  },
  "oauth2JwtBearerConfig": {
    object (Oauth2JwtBearerConfig)
  }
  // End of list of possible types for union field end_user_auth_config.
}
Fields
Union field end_user_auth_config. The end-user authentication configuration. end_user_auth_config can be only one of the following:
oauth2AuthCodeConfig

object (Oauth2AuthCodeConfig)

Oauth 2.0 Authorization Code authentication.
oauth2JwtBearerConfig

object (Oauth2JwtBearerConfig)

JWT Profile Oauth 2.0 Authorization Grant authentication.

Oauth2AuthCodeConfig

Oauth 2.0 Authorization Code authentication configuration.

JSON representation 
{
  "oauthToken": string
}
Fields
oauthToken

string

Required. Oauth token value or parameter name to pass it through.

Oauth2JwtBearerConfig

JWT Profile Oauth 2.0 Authorization Grant authentication configuration.

JSON representation 
{
  "issuer": string,
  "subject": string,
  "clientKey": string
}
Fields
issuer

string

Required. Issuer value or parameter name to pass it through.
subject

string

Required. Subject value or parameter name to pass it through.
clientKey

string

Required. Client key value or parameter name to pass it through.

ToolType

Represents the type of the tool.

Enums
TOOL_TYPE_UNSPECIFIED Default value. This value is unused.
CUSTOMIZED_TOOL Customer provided tool.
BUILTIN_TOOL First party built-in tool created by Dialogflow which cannot be modified.

Methods

create

 Creates a Tool in the specified agent.

delete

 Deletes a specified Tool.

export

 Exports the selected tools.

get

 Retrieves the specified Tool.

list

 Returns a list of Tools in the specified agent.

patch

 Update the specified Tool.