Tool

Tool details that the model may use to generate response.

A Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model. A Tool object should contain exactly one type of Tool (e.g FunctionDeclaration, Retrieval or GoogleSearchRetrieval).

Fields
functionDeclarations[] object (FunctionDeclaration)

Optional. Function tool type. One or more function declarations to be passed to the model along with the current user query. Model may decide to call a subset of these functions by populating FunctionCall in the response. user should provide a FunctionResponse for each function call in the next turn. Based on the function responses, Model will generate the final response back to the user. Maximum 512 function declarations can be provided.

retrieval object (Retrieval)

Optional. Retrieval tool type. System will always execute the provided retrieval tool(s) to get external knowledge to answer the prompt. Retrieval results are presented to the model for generation.

googleSearchRetrieval
(deprecated) object (GoogleSearchRetrieval)

Optional. Specialized retrieval tool that is powered by Google Search.

googleMaps object (GoogleMaps)

Optional. GoogleMaps tool type. Tool to support Google Maps in Model.

codeExecution object (CodeExecution)

Optional. CodeExecution tool type. Enables the model to execute code as part of generation.

urlContext object (UrlContext)

Optional. Tool to support URL context retrieval.

computerUse object (ComputerUse)

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

JSON representation 
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "retrieval": {
    object (Retrieval)
  },
  "googleSearch": {
    object (GoogleSearch)
  },
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "googleMaps": {
    object (GoogleMaps)
  },
  "enterpriseWebSearch": {
    object (EnterpriseWebSearch)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "urlContext": {
    object (UrlContext)
  },
  "computerUse": {
    object (ComputerUse)
  }
}

Retrieval

Defines a retrieval tool that model can call to access external knowledge.

Fields
disableAttribution
(deprecated) boolean

Optional. Deprecated. This option is no longer supported.

source Union type
The source of the retrieval. source can be only one of the following:
vertexRagStore object (VertexRagStore)

Set to use data source powered by Vertex RAG store. user data is uploaded via the VertexRagDataService.

externalApi object (ExternalApi)

Use data source powered by external API for grounding.

JSON representation 
{
  "disableAttribution": boolean,

  // source
  "vertexAiSearch": {
    object (VertexAISearch)
  },
  "vertexRagStore": {
    object (VertexRagStore)
  },
  "externalApi": {
    object (ExternalApi)
  }
  // Union type
}

VertexAISearch

Retrieve from Vertex AI Search datastore or engine for grounding. datastore and engine are mutually exclusive. See https://cloud.google.com/products/agent-builder

Fields
datastore string

Optional. Fully-qualified Vertex AI Search data store resource id. Format: projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}

engine string

Optional. Fully-qualified Vertex AI Search engine resource id. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}

maxResults integer

Optional. Number of search results to return per query. The default value is 10. The maximumm allowed value is 10.

filter string

Optional. Filter strings to be passed to the search API.

dataStoreSpecs[] object (DataStoreSpec)

Specifications that define the specific DataStores to be searched, along with configurations for those data stores. This is only considered for Engines with multiple data stores. It should only be set if engine is used.

JSON representation 
{
  "datastore": string,
  "engine": string,
  "maxResults": integer,
  "filter": string,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ]
}

DataStoreSpec

Define data stores within engine to filter on in a search call and configurations for those data stores. For more information, see https://cloud.google.com/generative-ai-app-builder/docs/reference/rpc/google.cloud.discoveryengine.v1#datastorespec

Fields
dataStore string

Full resource name of DataStore, such as Format: projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}

filter string

Optional. Filter specification to filter documents in the data store specified by dataStore field. For more information on filtering, see Filtering

JSON representation 
{
  "dataStore": string,
  "filter": string
}

VertexRagStore

Retrieve from Vertex RAG Store for grounding.

Fields
ragCorpora[]
(deprecated) string

Optional. Deprecated. Please use ragResources instead.

ragResources[] object (RagResource)

Optional. The representation of the rag source. It can be used to specify corpus only or ragfiles. Currently only support one corpus or multiple files from one corpus. In the future we may open up multiple corpora support.

ragRetrievalConfig object (RagRetrievalConfig)

Optional. The retrieval config for the Rag query.

storeContext boolean

Optional. Currently only supported for Gemini Multimodal Live API.

In Gemini Multimodal Live API, if storeContext bool is specified, Gemini will leverage it to automatically memorize the interactions between the client and Gemini, and retrieve context when needed to augment the response generation for users' ongoing and future interactions.

similarityTopK
(deprecated) integer

Optional. Number of top k results to return from the selected corpora.

vectorDistanceThreshold
(deprecated) number

Optional. Only return results with vector distance smaller than the threshold.

JSON representation 
{
  "ragCorpora": [
    string
  ],
  "ragResources": [
    {
      object (RagResource)
    }
  ],
  "ragRetrievalConfig": {
    object (RagRetrievalConfig)
  },
  "storeContext": boolean,
  "similarityTopK": integer,
  "vectorDistanceThreshold": number
}

RagResource

The definition of the Rag resource.

Fields
ragCorpus string

Optional. RagCorpora resource name. Format: projects/{project}/locations/{location}/ragCorpora/{ragCorpus}

ragFileIds[] string

Optional. ragFileId. The files should be in the same ragCorpus set in ragCorpus field.

JSON representation 
{
  "ragCorpus": string,
  "ragFileIds": [
    string
  ]
}

RagRetrievalConfig

Specifies the context retrieval config.

Fields
topK integer

Optional. The number of contexts to retrieve.

filter object (Filter)

Optional. Config for filters.

ranking object (Ranking)

Optional. Config for ranking and reranking.

JSON representation 
{
  "topK": integer,
  "hybridSearch": {
    object (HybridSearch)
  },
  "filter": {
    object (Filter)
  },
  "ranking": {
    object (Ranking)
  }
}

HybridSearch

Config for Hybrid Search.

Fields
alpha number

Optional. Alpha value controls the weight between dense and sparse vector search results. The range is [0, 1], while 0 means sparse vector search only and 1 means dense vector search only. The default value is 0.5 which balances sparse and dense vector search equally.

JSON representation 
{
  "alpha": number
}

Filter

Config for filters.

Fields
metadataFilter string

Optional. String for metadata filtering.

vector_db_threshold Union type
Filter contexts retrieved from the vector DB based on either vector distance or vector similarity. vector_db_threshold can be only one of the following:
vectorDistanceThreshold number

Optional. Only returns contexts with vector distance smaller than the threshold.

vectorSimilarityThreshold number

Optional. Only returns contexts with vector similarity larger than the threshold.

JSON representation 
{
  "metadataFilter": string,

  // vector_db_threshold
  "vectorDistanceThreshold": number,
  "vectorSimilarityThreshold": number
  // Union type
}

Ranking

Config for ranking and reranking.

Fields
ranking_config Union type
Config options for ranking. Currently only Rank Service is supported. ranking_config can be only one of the following:
rankService object (RankService)

Optional. Config for Rank service.

llmRanker object (LlmRanker)

Optional. Config for LlmRanker.

JSON representation 
{

  // ranking_config
  "rankService": {
    object (RankService)
  },
  "llmRanker": {
    object (LlmRanker)
  }
  // Union type
}

RankService

Config for Rank service.

Fields
modelName string

Optional. The model name of the rank service. Format: semantic-ranker-512@latest

JSON representation 
{
  "modelName": string
}

LlmRanker

Config for LlmRanker.

Fields
modelName string

Optional. The model name used for ranking. See Supported models.

JSON representation 
{
  "modelName": string
}

ExternalApi

Retrieve from data source powered by external API for grounding. The external API is not owned by Google, but need to follow the pre-defined API spec.

Fields
apiSpec enum (ApiSpec)

The API spec that the external API implements.

endpoint string

The endpoint of the external API. The system will call the API at this endpoint to retrieve the data for grounding. Example: https://acme.com:443/search

apiAuth
(deprecated) object (ApiAuth)

The authentication config to access the API. Deprecated. Please use authConfig instead.

authConfig object (AuthConfig)

The authentication config to access the API.

params Union type
Parameters for the API call. This should be matched with the API spec used. params can be only one of the following:
simpleSearchParams object (SimpleSearchParams)

Parameters for the simple search API.

elasticSearchParams object (ElasticSearchParams)

Parameters for the elastic search API.

JSON representation 
{
  "apiSpec": enum (ApiSpec),
  "endpoint": string,
  "apiAuth": {
    object (ApiAuth)
  },
  "authConfig": {
    object (AuthConfig)
  },

  // params
  "simpleSearchParams": {
    object (SimpleSearchParams)
  },
  "elasticSearchParams": {
    object (ElasticSearchParams)
  }
  // Union type
}

SimpleSearchParams

This type has no fields.

The search parameters to use for SIMPLE_SEARCH spec.

ElasticSearchParams

The search parameters to use for the ELASTIC_SEARCH spec.

Fields
index string

The ElasticSearch index to use.

searchTemplate string

The ElasticSearch search template to use.

numHits integer

Optional. Number of hits (chunks) to request.

When specified, it is passed to Elasticsearch as the numHits param.

JSON representation 
{
  "index": string,
  "searchTemplate": string,
  "numHits": integer
}

ApiSpec

The API spec that the external API implements.

Enums
API_SPEC_UNSPECIFIED Unspecified API spec. This value should not be used.

GoogleSearch

GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

Fields
excludeDomains[] string

Optional. List of domains to be excluded from the search results. The default limit is 2000 domains. Example: ["amazon.com", "facebook.com"].

blockingConfidence enum (PhishBlockThreshold)

Optional. Sites with confidence level chosen & above this value will be blocked from the search results.

JSON representation 
{
  "excludeDomains": [
    string
  ],
  "blockingConfidence": enum (PhishBlockThreshold)
}

PhishBlockThreshold

These are available confidence level user can set to block malicious urls with chosen confidence and above. For understanding different confidence of webrisk, please refer to https://cloud.google.com/web-risk/docs/reference/rpc/google.cloud.webrisk.v1eap1#confidencelevel

Enums
PHISH_BLOCK_THRESHOLD_UNSPECIFIED Defaults to unspecified.
BLOCK_LOW_AND_ABOVE Blocks Low and above confidence URL that is risky.
BLOCK_MEDIUM_AND_ABOVE Blocks Medium and above confidence URL that is risky.
BLOCK_HIGH_AND_ABOVE Blocks High and above confidence URL that is risky.
BLOCK_HIGHER_AND_ABOVE Blocks Higher and above confidence URL that is risky.
BLOCK_VERY_HIGH_AND_ABOVE Blocks Very high and above confidence URL that is risky.
BLOCK_ONLY_EXTREMELY_HIGH Blocks Extremely high confidence URL that is risky.

GoogleSearchRetrieval

Tool to retrieve public web data for grounding, powered by Google.

Fields
dynamicRetrievalConfig object (DynamicRetrievalConfig)

Specifies the dynamic retrieval configuration for the given source.

JSON representation 
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

Describes the options to customize dynamic retrieval.

Fields
mode enum (Mode)

The mode of the predictor to be used in dynamic retrieval.

dynamicThreshold number

Optional. The threshold to be used in dynamic retrieval. If not set, a system default value is used.

JSON representation 
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

Mode

The mode of the predictor to be used in dynamic retrieval.

Enums
MODE_UNSPECIFIED Always trigger retrieval.
MODE_DYNAMIC Run retrieval only when system decides it is necessary.

GoogleMaps

Tool to retrieve public maps data for grounding, powered by Google.

Fields
enableWidget boolean

Optional. If true, include the widget context token in the response.

JSON representation 
{
  "enableWidget": boolean
}

EnterpriseWebSearch

Tool to search public web data, powered by Vertex AI Search and Sec4 compliance.

Fields
excludeDomains[] string

Optional. List of domains to be excluded from the search results. The default limit is 2000 domains.

blockingConfidence enum (PhishBlockThreshold)

Optional. Sites with confidence level chosen & above this value will be blocked from the search results.

JSON representation 
{
  "excludeDomains": [
    string
  ],
  "blockingConfidence": enum (PhishBlockThreshold)
}

CodeExecution

This type has no fields.

Tool that executes code generated by the model, and automatically returns the result to the model.

See also [ExecutableCode]and [CodeExecutionResult] which are input and output to this tool.

UrlContext

This type has no fields.

Tool to support URL context.

ComputerUse

Tool to support computer use.

Fields
environment enum (Environment)

Required. The environment being operated.

excludedPredefinedFunctions[] string

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

JSON representation 
{
  "environment": enum (Environment),
  "excludedPredefinedFunctions": [
    string
  ]
}

Environment

Represents the environment being operated, such as a web browser.

Enums
ENVIRONMENT_UNSPECIFIED Defaults to browser.
ENVIRONMENT_BROWSER Operates in a web browser.