REST Resource: projects.locations.extensions

Resource: Extension

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

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)
  }
}
Fields
name

string

Identifier. The resource name of the Extension.
displayName

string

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

string

Optional. The description of the Extension.
createTime

string (Timestamp format)

Output only. timestamp when this Extension was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

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

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
etag

string

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

object (ExtensionManifest)

Required. Manifest of the Extension.
extensionOperations[]

object (ExtensionOperation)

Output only. Supported operations.
runtimeConfig

object (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.
privateServiceConnectConfig

object (ExtensionPrivateServiceConnectConfig)

Optional. The PrivateServiceConnect config for the extension. If specified, the service endpoints associated with the Extension should be registered with private network access in the provided service Directory (https://cloud.google.com/service-directory/docs/configuring-private-network-access).

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.

ExtensionManifest

Manifest spec of an Extension needed for runtime execution.

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

string

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

string

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

object (ApiSpec)

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

object (AuthConfig)

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

ApiSpec

The API specification shown to the LLM.

JSON representation 
{

  // Union field api_spec can be only one of the following:
  "openApiYaml": string,
  "openApiGcsUri": string
  // End of list of possible types for union field api_spec.
}
Fields

Union field api_spec.

api_spec can be only one of the following:
openApiYaml

string

The API spec in Open API standard and YAML format.
openApiGcsUri

string

Cloud Storage URI pointing to the OpenAPI spec.

AuthConfig

Auth configuration to run the extension.

JSON representation 
{
  "authType": enum (AuthType),

  // Union field auth_config can be only one of the following:
  "apiKeyConfig": {
    object (ApiKeyConfig)
  },
  "httpBasicAuthConfig": {
    object (HttpBasicAuthConfig)
  },
  "googleServiceAccountConfig": {
    object (GoogleServiceAccountConfig)
  },
  "oauthConfig": {
    object (OauthConfig)
  },
  "oidcConfig": {
    object (OidcConfig)
  }
  // End of list of possible types for union field auth_config.
}
Fields
authType

enum (AuthType)

type of auth scheme.

Union field auth_config.

auth_config can be only one of the following:
apiKeyConfig

object (ApiKeyConfig)

Config for API key auth.
httpBasicAuthConfig

object (HttpBasicAuthConfig)

Config for HTTP Basic auth.
googleServiceAccountConfig

object (GoogleServiceAccountConfig)

Config for Google service Account auth.
oauthConfig

object (OauthConfig)

Config for user oauth.
oidcConfig

object (OidcConfig)

Config for user OIDC auth.

ApiKeyConfig

Config for authentication with API key.

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

string

Required. The parameter name of the API key. E.g. If the API request is "https://example.com/act?apiKey=", "apiKey" would be the parameter name.
apiKeySecret

string

Required. The name of the SecretManager secret version resource storing the API key. Format: projects/{project}/secrets/{secrete}/versions/{version}
httpElementLocation

enum (HttpElementLocation)

Required. The location of the API key.

HttpElementLocation

Enum of location an HTTP element can be.

Enums
HTTP_IN_UNSPECIFIED
HTTP_IN_QUERY Element is in the HTTP request query.
HTTP_IN_HEADER Element is in the HTTP request header.
HTTP_IN_PATH Element is in the HTTP request path.
HTTP_IN_BODY Element is in the HTTP request body.

HttpBasicAuthConfig

Config for HTTP Basic Authentication.

JSON representation 
{
  "credentialSecret": string
}
Fields
credentialSecret

string

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

GoogleServiceAccountConfig

Config for Google service Account Authentication.

JSON representation 
{
  "serviceAccount": string
}
Fields
serviceAccount

string

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

OauthConfig

Config for user oauth.

JSON representation 
{

  // Union field oauth_config can be only one of the following:
  "accessToken": string,
  "serviceAccount": string
  // End of list of possible types for union field oauth_config.
}
Fields

Union field oauth_config.

oauth_config can be only one of the following:
accessToken

string

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

string

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

OidcConfig

Config for user OIDC auth.

JSON representation 
{

  // Union field oidc_config can be only one of the following:
  "idToken": string,
  "serviceAccount": string
  // End of list of possible types for union field oidc_config.
}
Fields

Union field oidc_config.

oidc_config can be only one of the following:
idToken

string

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

string

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

AuthType

type of Auth.

Enums
AUTH_TYPE_UNSPECIFIED
NO_AUTH No Auth.
API_KEY_AUTH API Key Auth.
HTTP_BASIC_AUTH HTTP Basic Auth.
GOOGLE_SERVICE_ACCOUNT_AUTH Google service Account Auth.
OAUTH OAuth auth.
OIDC_AUTH OpenID Connect (OIDC) Auth.

ExtensionOperation

Operation of an extension.

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

string

Operation ID that uniquely identifies the operations among the extension. See: "Operation Object" in https://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.
functionDeclaration

object (FunctionDeclaration)

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

FunctionDeclaration

Structured representation of a function declaration as defined by the OpenAPI 3.0 specification. Included in this declaration are the function name and parameters. This FunctionDeclaration is a representation of a block of code that can be used as a Tool by the model and executed by the client.

JSON representation 
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  },
  "response": {
    object (Schema)
  }
}
Fields
name

string

Required. The name of the function to call. Must start with a letter or an underscore. Must be a-z, A-Z, 0-9, or contain underscores, dots and dashes, with a maximum length of 64.
description

string

Optional. description and purpose of the function. Model uses it to decide how and whether to call the function.
parameters

object (Schema)

Optional. Describes the parameters to this function in JSON Schema Object format. Reflects the Open API 3.03 Parameter Object. string Key: the name of the parameter. Parameter names are case sensitive. Schema value: the Schema defining the type used for the parameter. For function with no parameters, this can be left unset. Parameter names must start with a letter or an underscore and must only contain chars a-z, A-Z, 0-9, or underscores with a maximum length of 64. Example with 1 required and 1 optional parameter: type: OBJECT properties: param1: type: STRING param2: type: INTEGER required: - param1
response

object (Schema)

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

Schema

Schema is used to define the format of input/output data. Represents a select subset of an OpenAPI 3.0 schema object. More fields may be added in the future as needed.

JSON representation 
{
  "type": enum (Type),
  "format": string,
  "title": string,
  "description": string,
  "nullable": boolean,
  "default": value,
  "items": {
    object (Schema)
  },
  "minItems": string,
  "maxItems": string,
  "enum": [
    string
  ],
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "minProperties": string,
  "maxProperties": string,
  "minimum": number,
  "maximum": number,
  "minLength": string,
  "maxLength": string,
  "pattern": string,
  "example": value
}
Fields
type

enum (Type)

Optional. The type of the data.
format

string

Optional. The format of the data. Supported formats: for NUMBER type: "float", "double" for INTEGER type: "int32", "int64" for STRING type: "email", "byte", etc
title

string

Optional. The title of the Schema.
description

string

Optional. The description of the data.
nullable

boolean

Optional. Indicates if the value may be null.
default

value (Value format)

Optional. Default value of the data.
items

object (Schema)

Optional. SCHEMA FIELDS FOR TYPE ARRAY Schema of the elements of type.ARRAY.
minItems

string (int64 format)

Optional. Minimum number of the elements for type.ARRAY.
maxItems

string (int64 format)

Optional. Maximum number of the elements for type.ARRAY.
enum[]

string

Optional. Possible values of the element of type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
properties

map (key: string, value: object (Schema))

Optional. SCHEMA FIELDS FOR TYPE OBJECT Properties of type.OBJECT.
required[]

string

Optional. Required properties of type.OBJECT.
minProperties

string (int64 format)

Optional. Minimum number of the properties for type.OBJECT.
maxProperties

string (int64 format)

Optional. Maximum number of the properties for type.OBJECT.
minimum

number

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the type.INTEGER and type.NUMBER
maximum

number

Optional. Maximum value of the type.INTEGER and type.NUMBER
minLength

string (int64 format)

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the type.STRING
maxLength

string (int64 format)

Optional. Maximum length of the type.STRING
pattern

string

Optional. Pattern of the type.STRING to restrict a string to a regular expression.
example

value (Value format)

Optional. Example of the object. Will only populated when the object is the root.

Type

type contains the list of OpenAPI data types as defined by https://swagger.io/docs/specification/data-models/data-types/

Enums
TYPE_UNSPECIFIED Not specified, should not be used.
STRING OpenAPI string type
NUMBER OpenAPI number type
INTEGER OpenAPI integer type
BOOLEAN OpenAPI boolean type
ARRAY OpenAPI array type
OBJECT OpenAPI object type

RuntimeConfig

Runtime configuration to run the extension.

JSON representation 
{
  "defaultParams": {
    object
  },

  // Union field GoogleFirstPartyExtensionConfig can be only one of the
  // following:
  "codeInterpreterRuntimeConfig": {
    object (CodeInterpreterRuntimeConfig)
  },
  "vertexAiSearchRuntimeConfig": {
    object (VertexAISearchRuntimeConfig)
  }
  // End of list of possible types for union field
  // GoogleFirstPartyExtensionConfig.
}
Fields
defaultParams

object (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"}.
Union field GoogleFirstPartyExtensionConfig. Runtime configurations for Google first party extensions. GoogleFirstPartyExtensionConfig can be only one of the following:
codeInterpreterRuntimeConfig

object (CodeInterpreterRuntimeConfig)

code execution runtime configurations for code interpreter extension.
vertexAiSearchRuntimeConfig

object (VertexAISearchRuntimeConfig)

Runtime configuration for Vertext AI Search extension.

CodeInterpreterRuntimeConfig

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

string

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

string

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.

VertexAISearchRuntimeConfig

JSON representation 
{
  "servingConfigName": string,
  "appId": string
}
Fields
servingConfigName
(deprecated)

string

[Deprecated] Please use appId instead. Vertex AI Search serving config name. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}
appId

string

Vertex AI Search App ID. This is used to construct the search request. By setting this appId, API will construct the serving config which is required to call search API for the user. The appId and servingConfigName cannot both be empty at the same time.

ToolUseExample

A single example of the tool usage.

JSON representation 
{
  "displayName": string,
  "query": string,
  "requestParams": {
    object
  },
  "responseParams": {
    object
  },
  "responseSummary": string,

  // Union field Target can be only one of the following:
  "extensionOperation": {
    object (ExtensionOperation)
  },
  "functionName": string
  // End of list of possible types for union field Target.
}
Fields
displayName

string

Required. The display name for example.
query

string

Required. Query that should be routed to this tool.
requestParams

object (Struct format)

Request parameters used for executing this tool.
responseParams

object (Struct format)

Response parameters generated by this tool.
responseSummary

string

Summary of the tool response to the user query.
Union field Target. Target tool to use. Target can be only one of the following:
extensionOperation

object (ExtensionOperation)

Extension operation to call.
functionName

string

Function name to call.

ExtensionOperation

Identifies one operation of the extension.

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

string

Resource name of the extension.
operationId

string

Required. Operation ID of the extension.

ExtensionPrivateServiceConnectConfig

PrivateExtensionConfig configuration for the extension.

JSON representation 
{
  "serviceDirectory": string
}
Fields
serviceDirectory

string

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

Methods

delete

 Deletes an Extension.

get

 Gets an Extension.

import

 Imports an Extension.

list

 Lists Extensions in a location.

patch

 Updates an Extension.