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)
  },
  "functionSpec": {
    object (FunctionTool)
  }
  // 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.
functionSpec

object (FunctionTool)

Client side executed function 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,
  "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 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,
  "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 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.

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.

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.

get

 Retrieves the specified Tool.

list

 Returns a list of Tools in the specified agent.

patch

 Update the specified Tool.