REST Resource: projects.locations.extensions

Resource: Extension

extensions are tools for large language models to access external data, run computations, etc.

Fields
namestring

Identifier. The resource name of the Extension.

displayNamestring

Required. The display name of the Extension. The name can be up to 128 characters long and can consist of any UTF-8 characters.

descriptionstring

Optional. The description of the Extension.

createTimestring (Timestamp format)

Output only. timestamp when this Extension was created.

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

updateTimestring (Timestamp format)

Output only. timestamp when this Extension was most recently updated.

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

etagstring

Optional. Used to perform consistent read-modify-write updates. If not set, a blind "overwrite" update happens.

manifestobject (ExtensionManifest)

Required. Manifest of the Extension.

extensionOperations[]object (ExtensionOperation)

Output only. Supported operations.

runtimeConfigobject (RuntimeConfig)

Optional. Runtime config controlling the runtime behavior of this Extension.

toolUseExamples[]object (ToolUseExample)

Optional. Examples to illustrate the usage of the extension as a tool.

privateServiceConnectConfigobject (ExtensionPrivateServiceConnectConfig)

Optional. The PrivateServiceConnect config for the extension. If specified, the service endpoints associated with the Extension should beregistered with private network access in the provided service Directory.

If the service contains more than one endpoint with a network, the service will arbitrarilty choose one of the endpoints to use for extension execution.

satisfiesPzsboolean

Output only. reserved for future use.

satisfiesPziboolean

Output only. reserved for future use.

JSON representation
{"name":string,"displayName":string,"description":string,"createTime":string,"updateTime":string,"etag":string,"manifest":{object (ExtensionManifest)},"extensionOperations":[{object (ExtensionOperation)}],"runtimeConfig":{object (RuntimeConfig)},"toolUseExamples":[{object (ToolUseExample)}],"privateServiceConnectConfig":{object (ExtensionPrivateServiceConnectConfig)},"satisfiesPzs":boolean,"satisfiesPzi":boolean}

ExtensionManifest

Manifest spec of an Extension needed for runtime execution.

Fields
namestring

Required. Extension name shown to the LLM. The name can be up to 128 characters long.

descriptionstring

Required. The natural language description shown to the LLM. It should describe the usage of the extension, and is essential for the LLM to perform reasoning. e.g., if the extension is a data store, you can let the LLM know what data it contains.

apiSpecobject (ApiSpec)

Required. Immutable. The API specification shown to the LLM.

authConfigobject (AuthConfig)

Required. Immutable. type of auth supported by this extension.

JSON representation
{"name":string,"description":string,"apiSpec":{object (ApiSpec)},"authConfig":{object (AuthConfig)}}

ApiSpec

The API specification shown to the LLM.

Fields
api_specUnion type
api_spec can be only one of the following:
openApiYamlstring

The API spec in Open API standard and YAML format.

openApiGcsUristring

Cloud Storage URI pointing to the OpenAPI spec.

JSON representation
{// api_spec"openApiYaml":string,"openApiGcsUri":string// Union type}

AuthConfig

Auth configuration to run the extension.

Fields
authTypeenum (AuthType)

type of auth scheme.

auth_configUnion type
auth_config can be only one of the following:
apiKeyConfigobject (ApiKeyConfig)

Config for API key auth.

httpBasicAuthConfigobject (HttpBasicAuthConfig)

Config for HTTP Basic auth.

googleServiceAccountConfigobject (GoogleServiceAccountConfig)

Config for Google service Account auth.

oauthConfigobject (OauthConfig)

Config for user oauth.

oidcConfigobject (OidcConfig)

Config for user OIDC auth.

JSON representation
{"authType":enum (AuthType),// auth_config"apiKeyConfig":{object (ApiKeyConfig)},"httpBasicAuthConfig":{object (HttpBasicAuthConfig)},"googleServiceAccountConfig":{object (GoogleServiceAccountConfig)},"oauthConfig":{object (OauthConfig)},"oidcConfig":{object (OidcConfig)}// Union type}

ApiKeyConfig

JSON representation
{"name":string,"apiKeySecret":string,"httpElementLocation":enum (HttpElementLocation)}

HttpElementLocation

Enum of location an HTTP element can be.

Enums
HTTP_IN_UNSPECIFIED
HTTP_IN_QUERYElement is in the HTTP request query.
HTTP_IN_HEADERElement is in the HTTP request header.
HTTP_IN_PATHElement is in the HTTP request path.
HTTP_IN_BODYElement is in the HTTP request body.
HTTP_IN_COOKIEElement is in the HTTP request cookie.

HttpBasicAuthConfig

Config for HTTP Basic Authentication.

Fields
credentialSecretstring

Required. The name of the SecretManager secret version resource storing the base64 encoded credentials. Format:projects/{project}/secrets/{secrete}/versions/{version}

JSON representation
{"credentialSecret":string}

GoogleServiceAccountConfig

Config for Google service Account Authentication.

Fields
serviceAccountstring

Optional. The service account that the extension execution service runs as.

JSON representation
{"serviceAccount":string}

OauthConfig

Config for user oauth.

Fields
oauth_configUnion type
oauth_config can be only one of the following:
accessTokenstring

Access token for extension endpoint. Only used to propagate token from [[ExecuteExtensionRequest.runtime_auth_config]] at request time.

serviceAccountstring

The service account used to generate access tokens for executing the Extension.

JSON representation
{// oauth_config"accessToken":string,"serviceAccount":string// Union type}

OidcConfig

Config for user OIDC auth.

Fields
oidc_configUnion type
oidc_config can be only one of the following:
idTokenstring

OpenID Connect formatted id token for extension endpoint. Only used to propagate token from [[ExecuteExtensionRequest.runtime_auth_config]] at request time.

serviceAccountstring

The service account used to generate an OpenID Connect (OIDC)-compatible JWT token signed by the Google OIDC Provider (accounts.google.com) for extension endpoint (https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-oidc).

JSON representation
{// oidc_config"idToken":string,"serviceAccount":string// Union type}

AuthType

type of Auth.

Enums
AUTH_TYPE_UNSPECIFIED
NO_AUTHNo Auth.
API_KEY_AUTHAPI Key Auth.
HTTP_BASIC_AUTHHTTP Basic Auth.
GOOGLE_SERVICE_ACCOUNT_AUTHGoogle service Account Auth.
OAUTHOAuth auth.
OIDC_AUTHOpenID Connect (OIDC) Auth.

ExtensionOperation

Operation of an extension.

Fields
operationIdstring

Operation id that uniquely identifies the operations among the extension. See: "Operation Object" inhttps://swagger.io/specification/.

This field is parsed from the OpenAPI spec. For HTTP extensions, if it does not exist in the spec, we will generate one from the HTTP method and path.

functionDeclarationobject (FunctionDeclaration)

Output only. Structured representation of a function declaration as defined by the OpenAPI Spec.

JSON representation
{"operationId":string,"functionDeclaration":{object (FunctionDeclaration)}}

RuntimeConfig

Runtime configuration to run the extension.

Fields
defaultParamsobject (Struct format)

Optional. Default parameters that will be set for all the execution of this extension. If specified, the parameter values can be overridden by values in [[ExecuteExtensionRequest.operation_params]] at request time.

The struct should be in a form of map with param name as the key and actual param value as the value. E.g. If this operation requires a param "name" to be set to "abc". you can set this to something like {"name": "abc"}.

GoogleFirstPartyExtensionConfigUnion type
Runtime configurations for Google first party extensions.GoogleFirstPartyExtensionConfig can be only one of the following:
codeInterpreterRuntimeConfigobject (CodeInterpreterRuntimeConfig)

code execution runtime configurations for code interpreter extension.

vertexAiSearchRuntimeConfigobject (VertexAISearchRuntimeConfig)

Runtime configuration for Vertex AI Search extension.

JSON representation
{"defaultParams":{object},// GoogleFirstPartyExtensionConfig"codeInterpreterRuntimeConfig":{object (CodeInterpreterRuntimeConfig)},"vertexAiSearchRuntimeConfig":{object (VertexAISearchRuntimeConfig)}// Union type}

CodeInterpreterRuntimeConfig

Fields
fileInputGcsBucketstring

Optional. The Cloud Storage bucket for file input of this Extension. If specified, support input from the Cloud Storage bucket. Vertex Extension Custom code service Agent should be granted file reader to this bucket. If not specified, the extension will only accept file contents from request body and reject Cloud Storage file inputs.

fileOutputGcsBucketstring

Optional. The Cloud Storage bucket for file output of this Extension. If specified, write all output files to the Cloud Storage bucket. Vertex Extension Custom code service Agent should be granted file writer to this bucket. If not specified, the file content will be output in response body.

JSON representation
{"fileInputGcsBucket":string,"fileOutputGcsBucket":string}

VertexAISearchRuntimeConfig

Fields
servingConfigNamestring

Optional. Vertex AI Search serving config name. Format:projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{servingConfig}

engineIdstring

Optional. Vertex AI Search engine id. This is used to construct the search request. By setting this engineId, API will construct the serving config using the default value to call search API for the user. The engineId and servingConfigName cannot both be empty at the same time.

JSON representation
{"servingConfigName":string,"engineId":string}

ToolUseExample

A single example of the tool usage.

Fields
displayNamestring

Required. The display name for example.

querystring

Required. Query that should be routed to this tool.

requestParamsobject (Struct format)

Request parameters used for executing this tool.

responseParamsobject (Struct format)

Response parameters generated by this tool.

responseSummarystring

Summary of the tool response to the user query.

TargetUnion type
Target tool to use.Target can be only one of the following:
extensionOperationobject (ExtensionOperation)

Extension operation to call.

functionNamestring

Function name to call.

JSON representation
{"displayName":string,"query":string,"requestParams":{object},"responseParams":{object},"responseSummary":string,// Target"extensionOperation":{object (ExtensionOperation)},"functionName":string// Union type}

ExtensionOperation

Identifies one operation of the extension.

Fields
extensionstring

Resource name of the extension.

operationIdstring

Required. Operation id of the extension.

JSON representation
{"extension":string,"operationId":string}

ExtensionPrivateServiceConnectConfig

PrivateExtensionConfig configuration for the extension.

Fields
serviceDirectorystring

Required. The service Directory resource name in which the service endpoints associated to the extension are registered. Format:projects/{projectId}/locations/{locationId}/namespaces/{namespaceId}/services/{serviceId}

JSON representation
{"serviceDirectory":string}

Methods

delete

 Deletes an Extension.

execute

 Executes the request against a given extension.

get

 Gets an Extension.

import

 Imports an Extension.

list

 Lists Extensions in a location.

patch

 Updates an Extension.

query

 Queries an extension with a default controller.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-09-25 UTC.