Console
    Contact Us Start free

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

    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 .
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: